> For the complete documentation index, see [llms.txt](https://docs.ibexa.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ibexa.ai/developers/rest-api/agents/get-agent-usage.md).

# Get Agent Usage

Get aggregated execution cost, token, and credit usage for an agent.

Groups results by the requested time period (day, month, or year). Returns token/cost usage (`items`) and AGENT\_EXECUTION credit spend (`credits`) as parallel lists matched by `period` — not merged into one row, since `items` may have multiple rows per period (one per currency) while credits carry no currency dimension. Each `credits` entry also splits out `execution_credits_spent`/`conversation_credits_spent`, which are independent, possibly-overlapping sums rather than a partition of the total. If no grouping is specified, all data is aggregated into a single total row. Requires platform administration role (admin or owner).

```json
{"openapi":"3.1.0","info":{"title":"Ibexa Agentic Marketing Platform","version":"0.1.0"},"security":[{"OAuth2PasswordBearer":[]}],"components":{"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"/api/v1/login/access-token"}}}},"schemas":{"UsageGrouping":{"type":"string","enum":["TOTAL","DAY","MONTH","YEAR"],"title":"UsageGrouping","description":"Time-period granularity for aggregated execution usage."},"AgentUsageAggregateResponseSchema":{"properties":{"items":{"items":{"$ref":"#/components/schemas/AgentUsagePeriodSchema"},"type":"array","title":"Items"},"credits":{"items":{"$ref":"#/components/schemas/CreditExecutionUsagePeriodSchema"},"type":"array","title":"Credits"}},"type":"object","required":["items","credits"],"title":"AgentUsageAggregateResponseSchema","description":"Aggregated execution usage response."},"AgentUsagePeriodSchema":{"properties":{"period":{"type":"string","title":"Period","description":"Period label (e.g. '2024-01-15', '2024-01', '2024')"},"agent_id":{"type":"integer","title":"Agent Id","description":"Agent ID"},"tokens_input":{"type":"integer","title":"Tokens Input"},"tokens_output":{"type":"integer","title":"Tokens Output"},"tokens_cache_read":{"type":"integer","title":"Tokens Cache Read"},"tokens_cache_write":{"type":"integer","title":"Tokens Cache Write"},"tokens_audio_input":{"type":"integer","title":"Tokens Audio Input"},"tokens_audio_output":{"type":"integer","title":"Tokens Audio Output"},"cost_amount":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Cost Amount"},"cost_currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cost Currency"}},"type":"object","required":["period","agent_id","tokens_input","tokens_output","tokens_cache_read","tokens_cache_write","tokens_audio_input","tokens_audio_output","cost_currency"],"title":"AgentUsagePeriodSchema","description":"Aggregated token and cost usage for a single time period and agent."},"CreditExecutionUsagePeriodSchema":{"properties":{"period":{"type":"string","title":"Period","description":"Period label (e.g. '2024-01-15', '2024-01', '2024')"},"credits_spent":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Credits Spent"},"execution_credits_spent":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Execution Credits Spent"},"conversation_credits_spent":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Conversation Credits Spent"}},"type":"object","required":["period","credits_spent","execution_credits_spent","conversation_credits_spent"],"title":"CreditExecutionUsagePeriodSchema","description":"Credits spent on AGENT_EXECUTION consumption for a single time period.\n\nCredits carry no currency, so unlike `AgentUsagePeriodSchema`/\n`OrgUsagePeriodSchema` (which may have multiple rows per period, one per\ncurrency) this is always at most one row per period.\n\n`execution_credits_spent` and `conversation_credits_spent` are independent\nsums (rows attributed to an execution, and rows attributed to a\nconversation, respectively) — not a mutually exclusive split of\n`credits_spent`. A triggered execution running inside a conversation counts\ntoward both, so the two do not in general add up to `credits_spent`."}}},"paths":{"/api/v1/agents/{agent_id}/usage":{"get":{"tags":["agents","public"],"summary":"Get Agent Usage","description":"Get aggregated execution cost, token, and credit usage for an agent.\n\nGroups results by the requested time period (day, month, or year). Returns\ntoken/cost usage (`items`) and AGENT_EXECUTION credit spend (`credits`) as\nparallel lists matched by `period` — not merged into one row, since `items`\nmay have multiple rows per period (one per currency) while credits carry no\ncurrency dimension. Each `credits` entry also splits out\n`execution_credits_spent`/`conversation_credits_spent`, which are\nindependent, possibly-overlapping sums rather than a partition of the total.\nIf no grouping is specified, all data is aggregated into a single total row.\nRequires platform administration role (admin or owner).","operationId":"agents-get_agent_usage","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"integer","title":"Agent Id"}},{"name":"group","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/UsageGrouping"},{"type":"null"}],"description":"Time grouping granularity. If omitted, all data is aggregated into a single total.","title":"Group"},"description":"Time grouping granularity. If omitted, all data is aggregated into a single total."},{"name":"daterange","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Date range as 'start,end' (ISO 8601 dates). Either part can be omitted, e.g. '2024-01-01,2024-12-31', '2024-01-01,' or ',2024-12-31'. A single date without a comma (e.g. '2024-01-01') is also accepted and sets date_from with an open-ended date_to.","title":"Daterange"},"description":"Date range as 'start,end' (ISO 8601 dates). Either part can be omitted, e.g. '2024-01-01,2024-12-31', '2024-01-01,' or ',2024-12-31'. A single date without a comma (e.g. '2024-01-01') is also accepted and sets date_from with an open-ended date_to."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentUsageAggregateResponseSchema"}}}},"401":{"description":"User not authenticated","content":{"application/json":{}}},"403":{"description":"User lacks permission","content":{"application/json":{}}},"404":{"description":"Resource not found or user has no permission to access it","content":{"application/json":{}}}}}}}}
```