> 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-status-distribution.md).

# Get Agent Status Distribution

Get execution status distribution for an agent grouped by time period.

Returns per-period counts of executions in each status (PENDING, STARTED, SUCCESS, FAILURE, CANCELED). Groups results by DAY (default), MONTH, YEAR, or TOTAL (single aggregated row with period='total'). Accessible by any member of the agent's organisation. Superusers may query agents in any organisation by providing the `organisation_id` parameter.

```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."},"ExecutionStatusDistributionResponseSchema":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ExecutionStatusPeriodSchema"},"type":"array","title":"Items"}},"type":"object","required":["items"],"title":"ExecutionStatusDistributionResponseSchema","description":"Execution status distribution response grouped by time period."},"ExecutionStatusPeriodSchema":{"properties":{"period":{"type":"string","title":"Period","description":"Period label (e.g. '2024-01-15', '2024-01', '2024')"},"pending":{"type":"integer","title":"Pending"},"started":{"type":"integer","title":"Started"},"success":{"type":"integer","title":"Success"},"failure":{"type":"integer","title":"Failure"},"canceled":{"type":"integer","title":"Canceled"}},"type":"object","required":["period","pending","started","success","failure","canceled"],"title":"ExecutionStatusPeriodSchema","description":"Execution status counts for a single time period."}}},"paths":{"/api/v1/agents/{agent_id}/status":{"get":{"tags":["agents","public"],"summary":"Get Agent Status Distribution","description":"Get execution status distribution for an agent grouped by time period.\n\nReturns per-period counts of executions in each status (PENDING, STARTED,\nSUCCESS, FAILURE, CANCELED). Groups results by DAY (default), MONTH, YEAR,\nor TOTAL (single aggregated row with period='total').\nAccessible by any member of the agent's organisation. Superusers may query\nagents in any organisation by providing the ``organisation_id`` parameter.","operationId":"agents-get_agent_status_distribution","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"integer","title":"Agent Id"}},{"name":"organisation_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Organisation ID. Defaults to the caller's own organisation. Superusers may specify any organisation.","title":"Organisation Id"},"description":"Organisation ID. Defaults to the caller's own organisation. Superusers may specify any organisation."},{"name":"group","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/UsageGrouping"},{"type":"null"}],"description":"Time grouping granularity (DAY, MONTH, YEAR, or TOTAL). Defaults to DAY if omitted. TOTAL collapses all results into a single row with period='total'.","title":"Group"},"description":"Time grouping granularity (DAY, MONTH, YEAR, or TOTAL). Defaults to DAY if omitted. TOTAL collapses all results into a single row with period='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/ExecutionStatusDistributionResponseSchema"}}}},"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":{}}}}}}}}
```