# Запрос аналитики

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

**`POST /v1/analytics/query`**

Сгруппируйте фактические расходы и статистику завершённых запросов по ключу, модели или пользователю приложения.

## Авторизация

`Authorization: Bearer <MANAGEMENT_API_KEY>`: управляющий ключ выбранного рабочего пространства.

Рабочее пространство определяется ключом. Заголовок `X-Org-Id` не поддерживается.

## Тело запроса

`Content-Type: application/json`


| Поле                 | Тип                     | Описание                                                                                                                                                   |
| -------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `metrics`            | string\[] · обязательно | От 1 до 8 уникальных метрик. Значения ниже.                                                                                                                |
| `dimensions`         | string\[]               | До 2 уникальных измерений; по умолчанию \[].                                                                                                               |
| `granularity`        | string                  | hour, day, week, month. Без поля данные суммируются за весь период.                                                                                        |
| `time_range`         | object                  | start включительно, end исключительно; даты ISO с часовым поясом. От начала до конца не более 93 дней. По умолчанию последние 30 дней до текущего момента. |
| `filters`            | object\[]               | До 20; по умолчанию \[]. Все фильтры соединяются через AND.                                                                                                |
| `filters[].field`    | string                  | Поддерживаемое измерение.                                                                                                                                  |
| `filters[].operator` | string                  | eq, neq, in, not\_in.                                                                                                                                      |
| `filters[].value`    | string \| string\[]     | eq/neq: строка до 256 символов. in/not\_in: от 1 до 100 таких строк.                                                                                       |
| `limit`              | integer                 | От 1 до 10000; по умолчанию 1000. Максимум строк ответа.                                                                                                   |
| `order_by`           | object                  | field должен входить в выбранные metrics или dimensions; direction: asc или desc. По умолчанию порядок группировки.                                        |


## Метрики и измерения


| Поле                                           | Тип    | Описание                                                                                           |
| ---------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------- |
| `total_usage`                                  | number | Фактические расходы, включая связанные проверки guardrail; также возвращается total\_usage\_exact. |
| `request_count, error_count`                   | number | Завершённые запросы и ошибки. Ошибочные запросы тоже могут быть платными.                          |
| `total_prompt_tokens, total_completion_tokens` | number | Зафиксированные входные и выходные токены.                                                         |
| `total_reasoning_tokens, total_cached_tokens`  | number | Зафиксированные токены рассуждений и кеша.                                                         |
| `avg_latency`                                  | number | Средняя длительность запроса в секундах.                                                           |


Измерения: `model`, `external_user`, `generation_id`, `api_key_hash`, `api_key_id`, `user_id`, `user`, `workspace_id`, `workspace`.

`api_key_id` возвращает тот же хеш, что и `api_key_hash`. `user` и `workspace` являются псевдонимами `user_id` и `workspace_id`. `external_user` берётся из поля `user` запроса Chat Completions или Responses; это ID пользователя вашего приложения, а не участника рабочего пространства. Старые запросы могут содержать null.

## Ответ · 200


| Поле                                                            | Тип       | Описание                                                                          |
| --------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------- |
| `data.data`                                                     | object\[] | Строки с выбранными измерениями и числовыми метриками. Измерения могут быть null. |
| `data.data[].date__hour / date__day / date__week / date__month` | string    | Начало периода в ISO UTC; только при заданной granularity.                        |
| `data.data[].total_usage_exact`                                 | string    | Точная строка с 8 знаками после запятой, если выбрана total\_usage.               |
| `data.metadata.currency`                                        | string    | Валюта total\_usage и total\_usage\_exact.                                        |
| `data.metadata.query_time_ms`                                   | number    | Время выполнения в миллисекундах.                                                 |
| `data.metadata.row_count`                                       | number    | Количество возвращённых строк.                                                    |
| `data.metadata.truncated`                                       | boolean   | true, если есть ещё группы. Сузьте период или фильтры; курсора нет.               |


Расходы группируются по времени проводки, статистика запросов по времени завершения. Платные ошибки и разрывы соединения входят в расходы. Возвраты не уменьшают исходное списание. Для сверки используйте точные строки и десятичную арифметику.

### Пример ответа

Все идентификаторы и суммы в примерах условные.


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



## Пример запроса

Загрузите ключ в переменную окружения на сервере. TypeScript использует встроенный fetch в Node.js, Python только стандартную библиотеку.




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
}'
```



## Ошибки


| HTTP  | Ошибка              | Причина                                                                                                             |
| ----- | ------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `401` | Unauthorized        | Отсутствующий, недействительный, отключённый, отозванный или истёкший ключ. Заголовок `X-Org-Id` также отклоняется. |
| `403` | Forbidden           | Неверный тип ключа или недостаточно прав в рабочем пространстве.                                                    |
| `400` | Bad Request         | Неверные или неизвестные параметры.                                                                                 |
| `429` | Too Many Requests   | Превышен лимит запросов аналитики: 2 в секунду, 30 в минуту; также действуют общие ограничения сервиса.             |
| `503` | Service Unavailable | Аналитика временно недоступна; повторите с меньшим периодом.                                                        |


Пример ошибки авторизации:

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

Пример ошибки метода:

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

## Далее

* [Управляющие ключи](/ru/docs/management-keys)
* [Стоимость запроса](/ru/docs/generation-metadata)

При `429` учитывайте заголовок `Retry-After`. Лимит применяется к рабочему пространству для каждого метода.
