# Attribute usage

What a model call records about who made it, which request fields reach the usage record and which are dropped, and how to read usage back through the API.

Every model call through the AI Gateway writes one usage event: the tenant, the user, the agent, the model, the tokens and the cost. Most of the fields an OpenAI-style client sends for attribution never reach it. This page says what does, so the numbers in analytics mean what you think they mean.

**Who can use it:** the model routes need the **Chat** or the **Completions** scope. The usage and analytics routes need the **Read usage and cost** scope.

## What reaches the usage record

| You send | Recorded | Notes |
| --- | --- | --- |
| The API key | `tenant_id` | Always the key's tenant. |
| The API key | `user_id` | On the current build, calls through the public API are recorded against the platform's own service identity, not the key's owner. The key id is never written, so usage cannot be broken down per key. |
| `X-Agent-ID` header | `agent_id` | The one attribution field that works from the public API. Up to 128 characters, any value you choose within your tenant. Budget rules scoped to an agent match on it, so a caller also decides whether such a rule applies to its own traffic. |
| `user` body field | nothing | Accepted and discarded. |
| `metadata` body field | nothing | Accepted and discarded: not forwarded to the provider, not written, not logged. |
| `X-Request-ID` header | nothing | Not forwarded by the public API gateway. |
| A session id | nothing | The record has a session column, but the model routes never fill it; agent turns do. |

The record also carries what the gateway decided: the served model and provider, the tier, whether it was a fallback and from what, the tokens including cached-prompt tokens, the cost, the latency, and a trace id from the platform's tracing.

## Quick start

Tag every call from one integration with an agent id, then read the tenant's spend by agent:

**cURL**

```bash
curl -X POST "https://<your tenant host>/public/v1/chat/completions" \
  -H "Authorization: Bearer kapi_..." \
  -H "X-Agent-ID: invoice-summariser" \
  -H "Content-Type: application/json" \
  -d '{"tier": "fast", "messages": [{"role": "user", "content": "Summarise: invoice 4471, 12 items, due 30 September."}]}'

curl "https://<your tenant host>/public/v1/analytics/cost?period=7d" \
  -H "Authorization: Bearer kapi_..."
```

**Python**

```python

BASE = "https://<your tenant host>/public/v1"
session = requests.Session()
session.headers.update({"Authorization": "Bearer kapi_...", "X-Agent-ID": "invoice-summariser"})

session.post(f"{BASE}/chat/completions", json={
    "tier": "fast",
    "messages": [{"role": "user", "content": "Summarise: invoice 4471, 12 items, due 30 September."}],
}).raise_for_status()

for row in session.get(f"{BASE}/analytics/cost", params={"period": "7d"}).json():
    print(row["agent_id"], row["total_requests"], "requests", row["total_tokens"], "tokens", row["total_cost"], "USD")
```

**TypeScript**

```typescript
const BASE = "https://<your tenant host>/public/v1";
const headers = { Authorization: "Bearer kapi_...", "X-Agent-ID": "invoice-summariser", "Content-Type": "application/json" };

await fetch(`${BASE}/chat/completions`, {
  method: "POST", headers,
  body: JSON.stringify({ tier: "fast", messages: [{ role: "user", content: "Summarise: invoice 4471, 12 items, due 30 September." }] }),
});

const rows = await (await fetch(`${BASE}/analytics/cost?period=7d`, { headers })).json();
for (const row of rows) console.log(row.agent_id, row.total_requests, "requests", row.total_tokens, "tokens", row.total_cost, "USD");
```

## Read usage back

| Route | What the numbers cover | Fields |
| --- | --- | --- |
| `GET /public/v1/usage?period=7d` | The key owner's own usage as a user, over `1d`, `7d` or `30d` | `total_requests`, `total_input_tokens`, `total_output_tokens`, `total_cost_usd` and `models[]` with requests, tokens and cost per model; `data_unavailable` is true when the store could not be read |
| `GET /public/v1/analytics/usage?period=24h` | The whole tenant | Requests, tokens, `total_cost_usd`, `unpriced_requests` and latency percentiles |
| `GET /public/v1/analytics/cost?period=7d` | The whole tenant, one row per agent id | `agent_id`, `agent_name`, `total_cost`, `total_tokens`, `total_requests` |

Because public API calls are recorded against the service identity, the usage route shows the key owner's Work Room and Studio usage and none of the key's API traffic on the current build. To see what an integration spends, give it its own `X-Agent-ID` and read the cost route, which breaks the tenant's spend down by agent id.

## Limits and behaviour

- The gateway writes no request log of its own; the request detail an administrator opens in the AI Gateway's **Logs** dialog, including its **User ID**, **Agent ID** and **Session ID**, is this usage event.
- `X-Agent-ID` is not checked against the tenant's agents. A typo becomes its own row in analytics, and a value that matches a real agent lands in that agent's figures.
- Usage a model has no price for is recorded with a cost of zero and adds nothing to budgets; the analytics route counts such calls in `unpriced_requests`.
- A streamed call is recorded when the stream settles, including when the client disconnected first.
- Prompt tokens served from a provider cache are recorded separately from the rest and priced at the cached rate; see [Prompt caching](/developers/guides/prompt-caching).

## Troubleshooting

- **The usage route returns zeros although the key is busy**: expected on the current build, for the reason above. Read the cost route by agent instead.
- **An integration's calls do not appear under its agent id**: the header was not sent. An OpenAI client library needs it in its default headers; a plain HTTP client needs it on every call.
- **Two integrations share a key and cannot be told apart**: they cannot be separated by key. Give each its own `X-Agent-ID`, or its own key and agent id.
- **Values sent in `metadata` are nowhere**: they are discarded. Put what you need to find later in the agent id, or keep it on your side against the response `id`.

## Related

- [How limits combine](/developers/guides/how-limits-combine)
- The usage record
- Analytics and feedback
- Analytics in the help centre

Source: https://docs.katonic.ai/developers/guides/attribute-usage
