Attribute usage
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
- Python
- TypeScript
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_..."
import requests
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")
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-IDis 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.
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
metadataare nowhere: they are discarded. Put what you need to find later in the agent id, or keep it on your side against the responseid.
The same figures elsewhere