# Query analytics

Source: https://provod.ai/en/docs/analytics-query

**`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.


**Response JSON**


```json
{
  "data": {
    "data": [
      {
        "date__day": "2026-11-01T00:00:00.000Z",
        "external_user": "customer-42",
        "model": "example/model",
        "total_usage": 0.0125,
        "total_usage_exact": "0.01250000",
        "request_count": 1,
        "error_count": 0
      }
    ],
    "metadata": {
      "currency": "RUB",
      "query_time_ms": 12,
      "row_count": 1,
      "truncated": false
    }
  }
}
```



## Request example

Load the key into a server environment variable. TypeScript uses Node.js fetch; Python uses only the standard library.




TypeScript



Python



cURL




```typescript
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());
```



```python
import json
import os
from urllib.request import Request, urlopen

payload = {
    "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
}
request = Request(
    "https://api.provod.ai/v1/analytics/query",
    method="POST",
    headers={
        "Authorization": f"Bearer {os.environ['MANAGEMENT_API_KEY']}",
        "Content-Type": "application/json",
    },
    data=json.dumps(payload).encode(),
)
with urlopen(request) as response:
    print(json.load(response))
```



```bash
curl --fail-with-body --silent --show-error -X POST \
  "https://api.provod.ai/v1/analytics/query" \
  -H "Authorization: Bearer ${MANAGEMENT_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
  "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
}'
```



## 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:

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key",
    "metadata": {}
  }
}
```

Operation error example:

```json
{
  "message": "Analytics temporarily unavailable; retry with a narrower time range",
  "error": "Service Unavailable",
  "statusCode": 503
}
```

## Next steps

* [Management keys](/en/docs/management-keys)
* [Generation charges](/en/docs/generation-metadata)

On `429`, honor the `Retry-After` header. Limits are scoped to the workspace for each operation.
