Get Agent Token Usage
get_agent_token_usageRead-onlyIdempotent
Summarize token usage per agent from completed sessions, with optional filters for name and time range, and include failed sessions to capture all consumption.
Instructions
Aggregate agent session token usage grouped by agent name.
Fetches agent sessions and groups them by agent name, computing token consumption statistics (sum, average, min, max) for both input and output tokens per agent. Sessions with missing or null token values are still counted toward session_count but contribute 0 to sum, average, and min/max calculations. Sessions with no agent name are grouped under a None-keyed entry rather than dropped. Only COMPLETE sessions are included by default — see include_failed to also include FAILED sessions.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent_name | No | Filter to agent names containing this substring (case-insensitive) | |
| started_after | No | ISO 8601 timestamp — only include sessions started at or after this time | |
| include_failed | No | By default only COMPLETE sessions count toward usage (finished, billable work). Set true to also include FAILED sessions, which can still have consumed real tokens. Non-terminal statuses (PENDING, RUNNING, PAUSED, ...) are always excluded either way, since their totals aren't final. | |
| started_before | No | ISO 8601 timestamp — only include sessions started at or before this time |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes | Response model for the agent token usage aggregation endpoint. Wraps a list of AgentTokenUsageStats objects, one per distinct agent name (including a None-keyed entry for sessions with no agent name), sorted by total_tokens descending. Attributes: root: List of AgentTokenUsageStats objects with aggregated token usage metrics per agent. |