provod.ai / docs
API

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

FieldTypeDescription
metricsstring[] · required1–8 unique metric names. See supported values below.
dimensionsstring[]Up to 2 unique dimensions; default [].
granularitystringhour, day, week, month. Omit to aggregate the whole period.
time_rangeobjectstart inclusive, end exclusive; ISO timestamps with timezone. Increasing, at most 93 days. Default: trailing 30 days up to now.
filtersobject[]Up to 20; default []. All filters are combined with AND.
filters[].fieldstringA supported dimension.
filters[].operatorstringeq, neq, in, not_in.
filters[].valuestring | string[]eq/neq: string up to 256 characters. in/not_in: 1–100 such strings.
limitinteger1–10000; default 1000. Maximum returned rows.
order_byobjectfield must be selected in metrics or dimensions; direction is asc or desc. Default: grouping order.

Metrics and dimensions

FieldTypeDescription
total_usagenumberActual usage and linked guardrail charges; also returns total_usage_exact.
request_count, error_countnumberTerminal requests and errors. Paid errors can contribute spending.
total_prompt_tokens, total_completion_tokensnumberRecorded input and output tokens.
total_reasoning_tokens, total_cached_tokensnumberRecorded reasoning and cached tokens.
avg_latencynumberAverage 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

FieldTypeDescription
data.dataobject[]Rows containing selected dimensions and numeric metrics. Dimensions may be null.
data.data[].date__hour / date__day / date__week / date__monthstringISO UTC bucket start, present only when granularity is supplied.
data.data[].total_usage_exactstringEight-place decimal, returned when total_usage is selected.
data.metadata.currencystringCurrency for total_usage and total_usage_exact.
data.metadata.query_time_msnumberQuery duration in milliseconds.
data.metadata.row_countnumberNumber of returned rows.
data.metadata.truncatedbooleanTrue 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

HTTPErrorCause
401UnauthorizedMissing, invalid, disabled, revoked or expired key. The X-Org-Id header is also rejected.
403ForbiddenWrong key kind or insufficient workspace access.
400Bad RequestInvalid or unknown parameters.
429Too Many RequestsAnalytics rate limit exceeded: 2 per second, 30 per minute; service-wide limits also apply.
503Service UnavailableAnalytics 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.

On this page