Get a usage time series

GET/v1/analytics/timeseries

Get a usage time series.

Returns one metric per time bucket over the requests matching the filters. Buckets are aligned to tz (local midnight for day) and every bucket in the window is returned, an empty one as 0. The window runs from start_time (default: the first retained log) to end_time (default now); it may hold at most 5000 buckets. With split_by=model, series also holds one series per model for the series_limit models with the most requests, plus one other series for the rest.

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 metric, granularity, time zone or split_by, a date-time without an offset, or a window of more than 5000 buckets.

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

metricstringrequired
what to chart per bucket: requests, tokens, cost (USD), cost_saved (USD saved by cache hits), latency (average duration in milliseconds), error_rate or cache_hit_rate (each 0 to 1)
granularitystring
the bucket size: hour, day (default) or week
tzstring
the IANA time zone buckets are aligned to, e.g. America/Toronto; default UTC. Fixed offsets such as +05:30 are refused
start_timestring
start of the window, inclusive (ISO 8601 date-time with offset)
end_timestring
end of the window, exclusive (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
modelstring
only requests for this model id
split_bystring
model to add a series per model; omit for the total only
series_limitinteger<int32>
with split_by=model, how many models get their own series: default 6, 1 to 10

Responses

200application/json

metricstring
The metric charted, as requested.
granularitystring
The bucket size: hour, day or week.
pointsobject[]
The metric per bucket, oldest first, over every request matching the filters. Empty buckets are included as 0.
Child attributes
- timestampstring<date-time>
  The start of the bucket (ISO 8601 date-time).
- valuenumber<double>
  The metric's value in the bucket; 0 for a bucket with no requests.
seriesobject[]
With split_by=model: one series per model for the models with the most requests, then one other series for every other model. Absent otherwise.
Child attributes
- namestring
  The model id; null for the other series.
- otherboolean
  True for the series that sums every model without a series of its own.
- pointsobject[]
  The metric per bucket for this model, on the same buckets as the total.
  Child attributes
  - timestampstring<date-time>
    The start of the bucket (ISO 8601 date-time).
  - valuenumber<double>
    The metric's value in the bucket; 0 for a bucket with no requests.

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