Skip to main content

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 sendRecordedNotes
The API keytenant_idAlways the key's tenant.
The API keyuser_idOn 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 headeragent_idThe 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 fieldnothingAccepted and discarded.
metadata body fieldnothingAccepted and discarded: not forwarded to the provider, not written, not logged.
X-Request-ID headernothingNot forwarded by the public API gateway.
A session idnothingThe 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 -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_..."

Read usage back​

RouteWhat the numbers coverFields
GET /public/v1/usage?period=7dThe key owner's own usage as a user, over 1d, 7d or 30dtotal_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=24hThe whole tenantRequests, tokens, total_cost_usd, unpriced_requests and latency percentiles
GET /public/v1/analytics/cost?period=7dThe whole tenant, one row per agent idagent_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.

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.

The same figures elsewhere

Describes the platform as of .

Was this page helpful?