Query analytics
Aggregate spending and requests by key, model or application user.
Last updated on
POST /v1/analytics/query
Aggregate actual spending and terminal request statistics by key, model or application user.
Authentication
Authorization: Bearer <MANAGEMENT_API_KEY>: a management key bound to the workspace.
The credential determines the workspace. X-Org-Id is unsupported.
Request body
Content-Type: application/json
| Field | Type | Description |
|---|---|---|
metrics | string[] · required | 1–8 unique metric names. See supported values below. |
dimensions | string[] | Up to 2 unique dimensions; default []. |
granularity | string | hour, day, week, month. Omit to aggregate the whole period. |
time_range | object | start inclusive, end exclusive; ISO timestamps with timezone. Increasing, at most 93 days. Default: trailing 30 days up to now. |
filters | object[] | Up to 20; default []. All filters are combined with AND. |
filters[].field | string | A supported dimension. |
filters[].operator | string | eq, neq, in, not_in. |
filters[].value | string | string[] | eq/neq: string up to 256 characters. in/not_in: 1–100 such strings. |
limit | integer | 1–10000; default 1000. Maximum returned rows. |
order_by | object | field must be selected in metrics or dimensions; direction is asc or desc. Default: grouping order. |
Metrics and dimensions
| Field | Type | Description |
|---|---|---|
total_usage | number | Actual usage and linked guardrail charges; also returns total_usage_exact. |
request_count, error_count | number | Terminal requests and errors. Paid errors can contribute spending. |
total_prompt_tokens, total_completion_tokens | number | Recorded input and output tokens. |
total_reasoning_tokens, total_cached_tokens | number | Recorded reasoning and cached tokens. |
avg_latency | number | Average request duration in seconds. |
Dimensions: model, external_user, generation_id, api_key_hash, api_key_id, user_id, user, workspace_id, workspace.
api_key_id returns the same hash as api_key_hash. user and workspace alias user_id and workspace_id. external_user comes from the user field in Chat Completions or Responses: it identifies your application user, not a workspace member. Historical requests may contain null.
Response · 200
| Field | Type | Description |
|---|---|---|
data.data | object[] | Rows containing selected dimensions and numeric metrics. Dimensions may be null. |
data.data[].date__hour / date__day / date__week / date__month | string | ISO UTC bucket start, present only when granularity is supplied. |
data.data[].total_usage_exact | string | Eight-place decimal, returned when total_usage is selected. |
data.metadata.currency | string | Currency for total_usage and total_usage_exact. |
data.metadata.query_time_ms | number | Query duration in milliseconds. |
data.metadata.row_count | number | Number of returned rows. |
data.metadata.truncated | boolean | True when more groups exist. Narrow the range or filters; there is no cursor. |
Spending is grouped by ledger posting time; request statistics by terminal recording time. Paid failures and disconnects contribute spending. Refunds do not reduce original charges. Use exact decimal strings and decimal arithmetic for reconciliation.
Response example
Identifiers and amounts in these examples are illustrative.
Request example
Load the key into a server environment variable. TypeScript uses Node.js fetch; Python uses only the standard library.
const response = await fetch("https://api.provod.ai/v1/analytics/query", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MANAGEMENT_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"metrics": [
"total_usage",
"request_count",
"error_count"
],
"dimensions": [
"external_user",
"model"
],
"granularity": "day",
"time_range": {
"start": "2026-11-01T00:00:00Z",
"end": "2026-11-08T00:00:00Z"
},
"filters": [
{
"field": "external_user",
"operator": "eq",
"value": "customer-42"
}
],
"limit": 1000
}),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
console.log(await response.json());Errors
| HTTP | Error | Cause |
|---|---|---|
401 | Unauthorized | Missing, invalid, disabled, revoked or expired key. The X-Org-Id header is also rejected. |
403 | Forbidden | Wrong key kind or insufficient workspace access. |
400 | Bad Request | Invalid or unknown parameters. |
429 | Too Many Requests | Analytics rate limit exceeded: 2 per second, 30 per minute; service-wide limits also apply. |
503 | Service Unavailable | Analytics temporarily unavailable; retry with a narrower range. |
Authentication error example:
{
"error": {
"code": "invalid_api_key",
"message": "Invalid API key",
"metadata": {}
}
}Operation error example:
{
"message": "Analytics temporarily unavailable; retry with a narrower time range",
"error": "Service Unavailable",
"statusCode": 503
}Next steps
On 429, honor the Retry-After header. Limits are scoped to the workspace for each operation.