Запрос аналитики
Отчёт о расходах и запросах с группировкой по ключу, модели или пользователю приложения.
Обновлено
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, если есть ещё группы. Сузьте период или фильтры; курсора нет. |
Расходы группируются по времени проводки, статистика запросов по времени завершения. Платные ошибки и разрывы соединения входят в расходы. Возвраты не уменьшают исходное списание. Для сверки используйте точные строки и десятичную арифметику.
Пример ответа
Все идентификаторы и суммы в примерах условные.
Пример запроса
Загрузите ключ в переменную окружения на сервере. TypeScript использует встроенный fetch в Node.js, Python только стандартную библиотеку.
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());Ошибки
| HTTP | Ошибка | Причина |
|---|---|---|
401 | Unauthorized | Отсутствующий, недействительный, отключённый, отозванный или истёкший ключ. Заголовок X-Org-Id также отклоняется. |
403 | Forbidden | Неверный тип ключа или недостаточно прав в рабочем пространстве. |
400 | Bad Request | Неверные или неизвестные параметры. |
429 | Too Many Requests | Превышен лимит запросов аналитики: 2 в секунду, 30 в минуту; также действуют общие ограничения сервиса. |
503 | Service Unavailable | Аналитика временно недоступна; повторите с меньшим периодом. |
Пример ошибки авторизации:
{
"error": {
"code": "invalid_api_key",
"message": "Invalid API key",
"metadata": {}
}
}Пример ошибки метода:
{
"message": "Analytics temporarily unavailable; retry with a narrower time range",
"error": "Service Unavailable",
"statusCode": 503
}Далее
При 429 учитывайте заголовок Retry-After. Лимит применяется к рабочему пространству для каждого метода.