> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corti.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# View agent usage

> Learn how to retrieve usage metrics for an agent, including granularity, date ranges, and bucket structure.

This guide shows you how to retrieve usage metrics for an agent using the v2 Agentic API. You will learn about granularity, date ranges, and how to interpret the response.

## Prerequisites

* An existing agent with at least one invocation
* An access token or client credentials

## Get usage

```bash theme={null}
# Replace these with your values
AGENT_ID="<your-agent-id>"
ENVIRONMENT="<eu-or-us>"
TENANT="<your-tenant-name>"
TOKEN="<your-access-token>"

curl "https://api.${ENVIRONMENT}.corti.app/v2/agentic/agents/${AGENT_ID}/usage" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"
```

## Query parameters

| Parameter     | Type      | Description                                                                                                                                                                        |
| ------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `from`        | date-time | Inclusive start of the range (UTC). Defaults to 30 days ago.                                                                                                                       |
| `to`          | date-time | Exclusive end of the range (UTC). Defaults to now.                                                                                                                                 |
| `granularity` | enum      | Bucket size: `minute`, `hour`, `day` (default), or `week`. Only `day` is currently honored; other values are accepted but produce daily buckets (the server always returns `day`). |

```bash theme={null}
curl "https://api.${ENVIRONMENT}.corti.app/v2/agentic/agents/${AGENT_ID}/usage?from=2026-05-19T00:00:00Z&to=2026-05-21T00:00:00Z&granularity=day" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"
```

## Response structure

The response contains range-wide `totals` and an array of `buckets`:

```json theme={null}
{
  "granularity": "day",
  "from": "2026-05-19T00:00:00Z",
  "to": "2026-05-21T00:00:00Z",
  "totals": {
    "invocations": 15,
    "uniqueContexts": 6
  },
  "buckets": [
    {
      "periodStart": "2026-05-19T00:00:00Z",
      "periodEnd": "2026-05-20T00:00:00Z",
      "invocations": 12,
      "uniqueContexts": 5
    },
    {
      "periodStart": "2026-05-20T00:00:00Z",
      "periodEnd": "2026-05-21T00:00:00Z",
      "invocations": 3,
      "uniqueContexts": 2
    }
  ]
}
```

## Interpreting metrics

| Metric           | Description                                       |
| ---------------- | ------------------------------------------------- |
| `invocations`    | Number of agent invocations in the period         |
| `uniqueContexts` | Number of distinct contexts invoked in the period |

For per-task token and credit accounting, see the `$usage` field in the [task metadata](/agentic/task-lifecycle#task-metadata-and-usage).

## Next steps

* Learn how to [export traces](/agentic/guides/export-traces) for detailed observability
* Read about the [task lifecycle](/agentic/task-lifecycle) for per-task usage data
* Learn how to [submit feedback](/agentic/guides/submit-feedback) on task results