Получить использование по Key

GET /api/open/v1/usage/keys

Параметры запроса

Параметр	Где	Тип	Обязательный	По умолчанию	Описание
`start_timestamp`	query	integer	Нет	См. ниже	Время начала (включительно), unix-секунды
`end_timestamp`	query	integer	Нет	См. ниже	Время окончания (включительно), unix-секунды
`group_by`	query	string	Нет	`key_name`	Способ группировки: `key_name` — группировка по имени Key на момент запроса, Key с одинаковым именем объединяются в одну строку; `key_id` — одна строка на каждый Key
`key_id`	query	integer	Нет	—	Фильтр по ID Key, положительное целое число; для нескольких значений повторяйте параметр или разделяйте запятыми. ID другого пользователя вернёт пустой результат
`key_name`	query	string	Нет	—	Точное имя Key на момент запроса; для нескольких значений повторяйте параметр. Запятые не поддерживаются, так как имена могут их содержать
`p`	query	integer	Нет	`1`	Номер страницы, от 1 до 1000000
`page_size`	query	integer	Нет	`10`	Элементов на странице, от 1 до 1000
`sort_by`	query	string	Нет	`total_tokens`	Поле сортировки: `key_count` (только при `group_by=key_name`), `prompt_tokens`, `completion_tokens`, `total_tokens`, `amount`, `remain_amount` или `used_percent`
`order`	query	string	Нет	`desc`	Направление: `asc` или `desc`

Правила временного диапазона:

Оба параметра опущены: последние 30 дней.
Только start_timestamp: 30 дней вперёд, но не позже текущего времени.
Только end_timestamp: 30 дней назад.
Диапазон может составлять не более 366 дней.

Явно переданные неверные p / page_size возвращают 400; см. Пагинация.

Каждый параметр с несколькими значениями принимает не более 50 значений; при превышении возвращается 400 invalid_request.

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

curl "https://www.routeapi.ai/api/open/v1/usage/keys?start_timestamp=1726400000&end_timestamp=1729000000&sort_by=total_tokens&order=desc&p=1&page_size=20" \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY"

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

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "key_name": "bot",
        "key_count": 2,
        "prompt_tokens": 5000,
        "completion_tokens": 1000,
        "total_tokens": 6000,
        "amount": 0.20,
        "remain_amount": 5.00,
        "used_total_amount": 3.20,
        "total_amount": 8.20,
        "unlimited": false,
        "used_percent": 39.02
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20,
    "start_timestamp": 1726400000,
    "end_timestamp": 1729000000
  }
}

При group_by=key_id каждая строка соответствует одному Key, содержит key_id и не содержит key_count:

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "key_id": 12,
        "key_name": "bot",
        "prompt_tokens": 3000,
        "completion_tokens": 600,
        "total_tokens": 3600,
        "amount": 0.12,
        "remain_amount": 2.50,
        "used_total_amount": 1.80,
        "total_amount": 4.30,
        "unlimited": false,
        "used_percent": 41.86
      },
      {
        "key_id": 15,
        "key_name": "bot",
        "prompt_tokens": 2000,
        "completion_tokens": 400,
        "total_tokens": 2400,
        "amount": 0.08,
        "remain_amount": null,
        "used_total_amount": 1.40,
        "total_amount": null,
        "unlimited": true,
        "used_percent": null
      }
    ],
    "total": 2,
    "page": 1,
    "page_size": 20,
    "start_timestamp": 1726400000,
    "end_timestamp": 1729000000
  }
}

Поля ответа

Поле	Тип	Описание
`items[].key_id`	integer	Только при `group_by=key_id`. ID Key, можно использовать в Получить API Key и других эндпоинтах; `0` означает использование без API Key (например, Playground)
`items[].key_name`	string	`group_by=key_name`: имя Key на момент запросов. `group_by=key_id`: текущее имя Key; если Key больше не существует или `key_id` равен `0`, берётся имя из последнего запроса этого Key за диапазон
`items[].key_count`	integer	Только при `group_by=key_name`. Количество разных Key с этим именем, имевших потребление за диапазон
`items[].prompt_tokens`	integer	Всего входных токенов в этой строке
`items[].completion_tokens`	integer	Всего выходных токенов в этой строке
`items[].total_tokens`	integer	Сумма входных и выходных токенов
`items[].amount`	number	Потраченная сумма для этой строки (за вычетом возвратов) в валюте сайта, два знака после запятой
`items[].remain_amount`	number \| null	Текущая оставшаяся доступная сумма Key, не зависит от временного диапазона. При `group_by=key_name` — сумма по всем Key с этим именем. Равен `null` для безлимитного Key, при `key_id` равном `0` или если Key больше не существует
`items[].used_total_amount`	number \| null	Суммарно израсходованная сумма с момента создания Key, не зависит от временного диапазона; для безлимитного Key возвращается как обычно. Равен `null`, если `key_id` равен `0` или Key больше не существует
`items[].total_amount`	number \| null	Общая сумма Key, равна `remain_amount` + `used_total_amount`; также `null`, если `remain_amount` равен `null`
`items[].unlimited`	boolean	Является ли Key безлимитным. При `group_by=key_name` равен `true`, если хотя бы один Key с этим именем безлимитный
`items[].used_percent`	number \| null	Доля использованной общей квоты: `used_total_amount` / `total_amount` × 100, округлено до двух знаков (например, `16.67` означает 16,67%). `null`, если `total_amount` равен `null` или `0`
`total`	integer	Общее количество строк: при `group_by=key_name` — количество имён, при `group_by=key_id` — количество Key (включая строку с `key_id` равным `0`)
`page`	integer	Текущий номер страницы
`page_size`	integer	Фактическое количество элементов на странице
`start_timestamp`	integer	Фактическое время начала
`end_timestamp`	integer	Фактическое время окончания

Ошибки

HTTP	code	Сценарий
400	`invalid_request`	Неверный `group_by`, `sort_by` или `order`, `sort_by=key_count` при `group_by=key_id`, `key_id` не является положительным целым числом, timestamp не является числом или отрицателен, диапазон некорректен, неверные параметры пагинации, или параметр с несколькими значениями содержит более 50 значений
429	—	Превышен лимит запросов на пользователя (по умолчанию 30/минуту); тело может быть пустым

Прочие общие коды ошибок см. в Ошибки и лимиты.

Примечания

Строки сначала сортируются по полю sort_by, а при равенстве — по key_name (при group_by=key_id — по key_id) по возрастанию, поэтому пагинация стабильна.
amount каждой строки округляется отдельно, поэтому сумма строк может отличаться от итога на величину до 0,01.
Имена Key могут повторяться: при group_by=key_name Key с одинаковым именем объединяются в одну строку, а для их различения используйте group_by=key_id (значения Key не возвращаются).
В исторических записях сохраняется имя Key на момент запроса; переименование не переписывает прошлые записи. Поэтому при group_by=key_name использование до и после переименования попадает в две разные строки; фильтр key_name тоже сопоставляется с именем на момент запроса, а group_by=key_id возвращает текущее имя, и они могут различаться.
amount — это расход за временной диапазон; remain_amount, used_total_amount и total_amount — текущие суммы Key на момент запроса, не зависящие от временного диапазона.
При group_by=key_name поля суммы агрегируют Key, которые потребляли под этим именем в пределах диапазона; один и тот же Key, использовавший в диапазоне два имени, учитывается в обеих строках.
При sort_by=remain_amount или sort_by=used_percent строки, где это поле равно null (безлимитный Key, key_id равен 0, Key больше не существует, а для used_percent также общая квота 0), идут последними независимо от значения order.
Сумма amount по всем строкам совпадает с суммой в Использование (без учёта погрешности округления).
Учитываются только логи потребления (биллинга); неудачные запросы не включаются.
Количество токенов указано в исходных единицах, не в миллионах.
Суммы указаны в валюте отображения сайта, см. Получить баланс.
Для экспорта в Excel постранично запрашивайте этот эндпоинт с теми же фильтрами и собирайте массивы items.
Этот эндпоинт делит лимит запросов на пользователя (по умолчанию 30/минуту) с Использование, Логи аккаунта, Экспорт логов и Использование по моделям. См. Ограничения частоты.