> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Запрос использования токенов

> Запрос потребления токенов и стоимости по каждому запросу для всех ваших API-ключей

* Запрос потребления токенов и стоимости по каждому запросу для **всех** ваших API-ключей, либо фильтрация по одному ключу
* Входные, выходные и кешированные токены учитываются отдельно
* Сводный эндпоинт агрегирует итоги по каждому ключу
* Пагинация по курсору, окно времени до 31 дня

Эти эндпоинты читают биллинговые логи и возвращают каждый оплаченный запрос с разбивкой по токенам и стоимостью, а также сводку по ключам. Они дополняют эндпоинт [запроса баланса токена](https://docs.toapis.com/docs/ru/api-reference/account/token-balance.md), который возвращает только суммарный баланс одного ключа.

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

**Authorization** `string` *required*

Эти эндпоинты аутентифицируются как **учётная запись пользователя**, а не как API-ключ.

1. Откройте [страницу настроек аккаунта](https://toapis.com/dashboard/settings) и нажмите **Сгенерировать токен** в карточке «Системный токен доступа», чтобы получить токен доступа (это не `sk-` ключ). Повторная генерация аннулирует предыдущий токен.
2. Передавайте его в заголовке `Authorization` вместе с вашим ID пользователя:

```
Authorization: Bearer YOUR_ACCESS_TOKEN
X-User-Id: YOUR_USER_ID
```

Числовой ID пользователя показан на той же странице настроек.

**X-User-Id** `string` *required*

Ваш числовой ID пользователя. Обязателен вместе с токеном доступа.

## Эндпоинты

```
GET /api/usage/tokens/requests   # детализация по запросам
GET /api/usage/tokens/summary    # сводка по ключам
```

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

Оба эндпоинта принимают одинаковые параметры. Неизвестные или повторяющиеся параметры отклоняются с кодом `422`.

**start\_timestamp** `integer` *required*

Начало окна времени, Unix-метка в секундах (включительно).

**end\_timestamp** `integer` *required*

Конец окна времени, Unix-метка в секундах (не включительно). Должна быть позже `start_timestamp`; окно не более 31 дня.

**token\_id** `integer`

Необязательно. Ограничивает результат одним API-ключом по его числовому ID. Без параметра включаются все ключи.

**page\_size** `integer` (default: 50)

Число строк на странице, `1`–`100`.

**cursor** `string`

Курсор пагинации из `meta.next_cursor` предыдущего ответа. Действителен только для того же эндпоинта, окна времени и фильтра `token_id`, которые его создали.

## Ответ

`GET /api/usage/tokens/requests` возвращает по одной строке на каждый оплаченный запрос, от новых к старым.

**log\_id** `integer`

Внутренний ID лога запроса. Уникален в пределах ответа.

**created\_at** `integer`

Время списания за запрос, Unix-метка в секундах.

**token\_id** `integer`

ID API-ключа, выполнившего запрос.

**token\_name** `string`

Имя API-ключа.

**model\_name** `string`

Модель, обработавшая запрос.

**task\_id** `string`

ID задачи для асинхронных запросов (генерация изображений/видео). Пусто для синхронных запросов.

**prompt\_tokens** `integer`

Оплаченные входные токены.

**completion\_tokens** `integer`

Оплаченные выходные токены.

**cache\_tokens** `integer | null`

Входные токены, прочитанные из кеша (попадания в кеш). `null`, если апстрим не сообщил данные о кеше.

**cache\_creation\_tokens** `integer | null`

Токены, записанные в кеш. `null`, если не сообщались.

**reported\_total\_tokens** `integer | null`

Общее число токенов по данным апстрим-провайдера, если доступно.

**total\_tokens** `integer`

`prompt_tokens + completion_tokens`.

**billing\_phase** `string`

`pre_consumed`, `settled` или `unknown` для логов без подробных биллинговых метаданных.

**quota** `integer`

Потреблённая квота во внутренних единицах платформы.

**cost\_usd** `string`

Стоимость в USD, рассчитанная как `quota / quota_per_usd` (см. `meta`). Возвращается строкой для сохранения точности.

`GET /api/usage/tokens/summary` возвращает по одной строке на каждый API-ключ, упорядоченные по `token_id`.

**token\_id** `integer`

ID API-ключа.

**request\_count** `integer`

Число оплаченных запросов в окне.

**prompt\_tokens** `integer`

Сумма входных токенов этого ключа.

**completion\_tokens** `integer`

Сумма выходных токенов этого ключа.

**total\_tokens** `integer`

`prompt_tokens + completion_tokens`.

**quota** `integer`

Суммарная потреблённая квота этого ключа.

**cost\_usd** `string`

Суммарная стоимость этого ключа в USD.

### Meta

**meta.has\_more** `boolean`

Есть ли следующая страница.

**meta.next\_cursor** `string`

Передайте как `cursor`, чтобы получить следующую страницу. Пусто, когда `has_more` равно `false`.

**meta.quota\_per\_usd** `string`

Число внутренних единиц квоты на 1 USD, использованное для пересчёта `cost_usd`.

**meta.consume\_logging\_enabled** `boolean`

Включено ли логирование потребления. При `false` ответы могут быть пустыми.

**meta.refunds\_included** `boolean`

Сейчас всегда `false` — возвраты не вычитаются.

```bash cURL — детализация по запросам theme={null}
curl --request GET \
  --url 'https://toapis.com/api/usage/tokens/requests?start_timestamp=1759708800&end_timestamp=1760313600&page_size=100' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-User-Id: YOUR_USER_ID'
```

```bash cURL — сводка по одному ключу theme={null}
curl --request GET \
  --url 'https://toapis.com/api/usage/tokens/summary?start_timestamp=1759708800&end_timestamp=1760313600&token_id=45' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-User-Id: YOUR_USER_ID'
```

```python Python — обход всех страниц theme={null}
import requests

API_BASE = 'https://toapis.com'
headers = {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'X-User-Id': 'YOUR_USER_ID',
}
params = {
    'start_timestamp': 1759708800,
    'end_timestamp': 1760313600,
    'page_size': 100,
}

while True:
    r = requests.get(f'{API_BASE}/api/usage/tokens/requests',
                     headers=headers, params=params)
    body = r.json()
    for row in body['data']:
        print(row['created_at'], row['token_name'], row['model_name'],
              row['prompt_tokens'], row['completion_tokens'],
              row['cache_tokens'], row['cost_usd'])
    if not body['meta']['has_more']:
        break
    params['cursor'] = body['meta']['next_cursor']
```

```json 200 - requests theme={null}
{
  "success": true,
  "data": [
    {
      "log_id": 10241024,
      "created_at": 1760001234,
      "token_id": 45,
      "token_name": "prod-backend",
      "model_name": "gpt-5.1",
      "task_id": "",
      "prompt_tokens": 148320,
      "completion_tokens": 2198,
      "cache_tokens": 96000,
      "cache_creation_tokens": 0,
      "reported_total_tokens": 150518,
      "total_tokens": 150518,
      "billing_phase": "settled",
      "quota": 7839,
      "cost_usd": "0.015678"
    }
  ],
  "meta": {
    "start_timestamp": 1759708800,
    "end_timestamp": 1760313600,
    "page_size": 100,
    "has_more": true,
    "next_cursor": "eyJraW5kIjoicmVxdWVzdHMiLC4uLn0",
    "cost_basis": "consume_log_quota",
    "currency": "USD",
    "quota_per_usd": "500000",
    "consume_logging_enabled": true,
    "refunds_included": false,
    "total_tokens_basis": "logged_prompt_plus_completion"
  }
}
```

```json 200 - summary theme={null}
{
  "success": true,
  "data": [
    {
      "token_id": 45,
      "request_count": 87,
      "prompt_tokens": 3200400,
      "completion_tokens": 150220,
      "total_tokens": 3350620,
      "quota": 401234,
      "cost_usd": "0.802468"
    }
  ],
  "meta": {
    "start_timestamp": 1759708800,
    "end_timestamp": 1760313600,
    "page_size": 50,
    "has_more": false,
    "next_cursor": "",
    "cost_basis": "consume_log_quota",
    "currency": "USD",
    "quota_per_usd": "500000",
    "consume_logging_enabled": true,
    "refunds_included": false,
    "total_tokens_basis": "logged_prompt_plus_completion"
  }
}
```

```json 401 theme={null}
{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "user authentication is required"
  }
}
```

```json 422 theme={null}
{
  "success": false,
  "error": {
    "code": "invalid_query",
    "message": "time range must be positive and no longer than 31 days"
  }
}
```

```json 503 theme={null}
{
  "success": false,
  "error": {
    "code": "query_timeout",
    "message": "usage query exceeded the time limit; use a shorter time range"
  }
}
```

## Примечания

* В список попадают только **оплаченные** запросы. Не оплаченные неудачные запросы не отображаются, отдельного флага успеха по запросу нет.
* Стоимость рассчитана по квоте, записанной при списании; по текущему каталогу не пересчитывается, возвраты не вычитаются.
* Эти эндпоинты не раскрывают сами API-ключи, каналы, IP-адреса и содержимое запросов/ответов.
* `cursor` привязан к эндпоинту, окну времени и фильтру `token_id` — не используйте его в других запросах.
* У запросов короткий таймаут; при получении `query_timeout` сократите окно времени и повторите.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.