Get session AI usage
Billed AI spend for a session, per turn and per session, written as each model call happens (main loop and utilities such as compaction, web search, web fetch, subagent summaries and embeddings). With includeChildren=true it also covers every subagent session below this one and adds them into totals. Turns and sessions created before per-turn tracking report usageTracked: false and usage: null; totals.complete is false when any are in scope.
/api/agent/sessions/{sessionId}/usagesessionIdstringrequiredincludeChildrenenumAlso report every subagent session below this one (default false).
runLimitintegerMaximum turns listed in runs (default 500, max 2000). Totals always cover every turn.
Request
curl -X GET https://trickest.io/api/agent/sessions/{sessionId}/usage \
-H "Authorization: Token $TRICKEST_TOKEN"Responses
sessionIdstringrequiredincludeChildrenbooleanrequiredsessionsobject[]requiredsessionIdstringrequiredparentSessionIdstringrequiredlevelintegerrequiredLevels below the requested session; 0 is the session itself.
titlestringrequiredstatusstringrequiredcreatedAtstringrequiredusageTrackedbooleanrequiredFalse when the session predates per-turn tracking; usage is then null.
usageCompletebooleanrequiredFalse when usage is known to miss calls: tracking began after the session started, or an attribution write failed.
usageobjectrequiredcallsintegerrequiredbilledUsdnumberrequiredWhat the vault is charged: raw cost × the vault markup at write time.
inputTokensintegerrequiredIncludes cache reads and cache writes.
outputTokensintegerrequiredcachedInputTokensintegerrequiredcacheCreationTokensintegerrequiredwebSearchRequestsintegerrequiredutilityBilledUsdnumberrequiredSpend outside main-loop model calls: compaction, web search/fetch, subagent summaries, embeddings.
utilityCallsintegerrequiredpriceFallbackbooleanrequiredAt least one call was priced from fallback rates; treat the figure as an estimate.
byKindstringrequiredoutsideTurnobjectrequiredcallsintegerrequiredbilledUsdnumberrequiredWhat the vault is charged: raw cost × the vault markup at write time.
inputTokensintegerrequiredIncludes cache reads and cache writes.
outputTokensintegerrequiredcachedInputTokensintegerrequiredcacheCreationTokensintegerrequiredwebSearchRequestsintegerrequiredrunCountintegerrequireduntrackedRunCountintegerrequiredrunsobject[]requiredrunIdstringrequiredsessionIdstringrequiredstatusstringrequiredtriggeredBystringrequiredstartedAtstringrequiredcompletedAtstringrequiredturnUsageStatusstringrequiredcomplete / partial / unknown, as the turn reported at finalize.
usageTrackedbooleanrequiredusageRecordedbooleanrequiredAt least one call was recorded against this turn.
usageobjectrequiredcallsintegerrequiredbilledUsdnumberrequiredWhat the vault is charged: raw cost × the vault markup at write time.
inputTokensintegerrequiredIncludes cache reads and cache writes.
outputTokensintegerrequiredcachedInputTokensintegerrequiredcacheCreationTokensintegerrequiredwebSearchRequestsintegerrequiredutilityBilledUsdnumberrequiredSpend outside main-loop model calls: compaction, web search/fetch, subagent summaries, embeddings.
utilityCallsintegerrequiredpriceFallbackbooleanrequiredAt least one call was priced from fallback rates; treat the figure as an estimate.
byKindstringrequiredrunsTruncatedbooleanrequiredtotalsobjectrequiredusageobjectrequiredcallsintegerrequiredbilledUsdnumberrequiredWhat the vault is charged: raw cost × the vault markup at write time.
inputTokensintegerrequiredIncludes cache reads and cache writes.
outputTokensintegerrequiredcachedInputTokensintegerrequiredcacheCreationTokensintegerrequiredwebSearchRequestsintegerrequiredutilityBilledUsdnumberrequiredSpend outside main-loop model calls: compaction, web search/fetch, subagent summaries, embeddings.
utilityCallsintegerrequiredpriceFallbackbooleanrequiredAt least one call was priced from fallback rates; treat the figure as an estimate.
byKindstringrequiredsessionCountintegerrequireduntrackedSessionCountintegerrequiredincompleteSessionCountintegerrequiredrunCountintegerrequireduntrackedRunCountintegerrequiredcompletebooleanrequiredFalse when anything in scope predates tracking or is known to miss calls; usage is then a lower bound.
sessionsTruncatedbooleanrequiredcodestringrequiredmessagestringrequireddetailsobjectField-level detail when the error is a validation failure.
codestringrequiredmessagestringrequireddetailsobjectField-level detail when the error is a validation failure.
codestringrequiredmessagestringrequireddetailsobjectField-level detail when the error is a validation failure.
codestringrequiredmessagestringrequireddetailsobjectField-level detail when the error is a validation failure.
codestringrequiredmessagestringrequireddetailsobjectField-level detail when the error is a validation failure.