Get a usage breakdown

GET/v1/analytics/breakdown

Get a usage breakdown.

Groups the requests matching the filters by one dimension and returns each group's requests, errors, tokens, cost, cost saved and average latency, highest cost first. Requests with no value for the dimension (no virtual key, for example) are left out.

With workspace_id, requires access to that workspace: an organization owner or admin, a member of the workspace, an organization-scoped va_ key with the admin role, or a va_ key scoped to the workspace. Without it, requires an organization owner or admin, or an organization-scoped va_ key with the admin role. Fails with 400 for an unknown dimension or a date-time without an offset.

Authorization

AuthorizationBearer va_
A platform API key (va_...), created under Settings > API keys. Scoped to an organization or one workspace, with an admin or member role. Used by the management API.

Query parameters

dimensionstringrequired
what to group by: provider, model, organization, user_id, virtual_key_slug or cache_status
start_timestring
only requests at or after this time (ISO 8601 date-time with offset)
end_timestring
only requests before this time (ISO 8601 date-time with offset)
organizationstring
the organization's slug
workspace_idstring<uuid>
only this workspace's requests (UUID)
providerstring
only requests to this provider, as stored: upper case with underscores, e.g. OPENAI
limitinteger<int32>
the most groups to return: default 20, at most 100

Responses

200application/json

dimensionstring
The dimension the requests are grouped by, as requested.
entriesobject[]
The groups, highest total_cost_usd first. Requests with no value for organization, user_id, virtual_key_slug or cache_status are left out of those breakdowns.
Child attributes
- dimension_valuestring
  The group's value of the dimension, e.g. a provider or a model id.
- request_countinteger<int64>
  How many requests are in the group.
- error_countinteger<int64>
  How many of them ended with a status of 400 or above.
- total_cost_usdnumber<double>
  What they cost, in USD (cache hits cost 0).
- total_cost_saved_usdnumber<double>
  What cache hits in the group saved, in USD.
- total_tokensinteger<int64>
  Input plus output tokens.
- avg_duration_msnumber<double>
  The average request duration, in milliseconds.

VectorAxis is built by GK Labs, a member of NVIDIA Inception.