provod.ai / docs
API

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

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

Обновлено

POST /v1/analytics/query

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

Авторизация

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

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

Тело запроса

Content-Type: application/json

ПолеТипОписание
metricsstring[] · обязательноОт 1 до 8 уникальных метрик. Значения ниже.
dimensionsstring[]До 2 уникальных измерений; по умолчанию [].
granularitystringhour, day, week, month. Без поля данные суммируются за весь период.
time_rangeobjectstart включительно, end исключительно; даты ISO с часовым поясом. От начала до конца не более 93 дней. По умолчанию последние 30 дней до текущего момента.
filtersobject[]До 20; по умолчанию []. Все фильтры соединяются через AND.
filters[].fieldstringПоддерживаемое измерение.
filters[].operatorstringeq, neq, in, not_in.
filters[].valuestring | string[]eq/neq: строка до 256 символов. in/not_in: от 1 до 100 таких строк.
limitintegerОт 1 до 10000; по умолчанию 1000. Максимум строк ответа.
order_byobjectfield должен входить в выбранные metrics или dimensions; direction: asc или desc. По умолчанию порядок группировки.

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

ПолеТипОписание
total_usagenumberФактические расходы, включая связанные проверки guardrail; также возвращается total_usage_exact.
request_count, error_countnumberЗавершённые запросы и ошибки. Ошибочные запросы тоже могут быть платными.
total_prompt_tokens, total_completion_tokensnumberЗафиксированные входные и выходные токены.
total_reasoning_tokens, total_cached_tokensnumberЗафиксированные токены рассуждений и кеша.
avg_latencynumberСредняя длительность запроса в секундах.

Измерения: 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.dataobject[]Строки с выбранными измерениями и числовыми метриками. Измерения могут быть null.
data.data[].date__hour / date__day / date__week / date__monthstringНачало периода в ISO UTC; только при заданной granularity.
data.data[].total_usage_exactstringТочная строка с 8 знаками после запятой, если выбрана total_usage.
data.metadata.currencystringВалюта total_usage и total_usage_exact.
data.metadata.query_time_msnumberВремя выполнения в миллисекундах.
data.metadata.row_countnumberКоличество возвращённых строк.
data.metadata.truncatedbooleantrue, если есть ещё группы. Сузьте период или фильтры; курсора нет.

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

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

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

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

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

На этой странице