# Биллинг

Модель оплаты — предоплаченный баланс в рублях. Списание происходит по факту
использованных токенов, без подписок и минимальных платежей.

## Как считается стоимость

Оплачивается фактическое использование: и входные, и выходные токены. Стоимость зависит от
выбранной модели — тарифы указаны в каталоге [Моделей](https://agentapi.ru/models).

Списание происходит в рублях после выполнения запроса. Точную сумму по каждому запросу
видно в [транзакциях](#транзакции).

## Сколько израсходовал запрос

Количество токенов приходит в поле `usage` ответа:

```json
{
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 71,
    "total_tokens": 95
  }
}
```

При стриминге `usage` приходит в последнем кадре перед `data: [DONE]`.

Рублёвую сумму списания смотрите в транзакциях — она появляется там после запроса.

## Списание при стриминге

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

Если клиент оборвал соединение до конца ответа, запрос может остаться несписанным.

## Баланс

```
GET https://api.agentapi.ru/billing/balance
```

Требует JWT (не API-ключ), см. [Аутентификация](https://agentapi.ru/docs/authentication).

```bash
curl https://api.agentapi.ru/billing/balance \
  -H "Authorization: Bearer $JWT"
```

```json
{ "balance": 1500.5 }
```

Баланс проверяется перед каждым запросом: при `balance <= 0` приходит
`400 Negative or zero balance`. Баланс может уйти в минус после списания за уже
выполненный запрос — блокируется только следующий.

## Транзакции

```
GET https://api.agentapi.ru/billing/transactions?limit=50&offset=0
```

```json
{
  "transactions": [
    {
      "id": "8c3f1a95-2d47-4e18-b6a0-9f5e2c7d3b81",
      "type": "debit",
      "amount": "0.035000",
      "currency": "RUB",
      "description": "Chat completion: openai/gpt-4.1",
      "promptTokens": 24,
      "completionTokens": 71,
      "totalTokens": 95,
      "model": "openai/gpt-4.1",
      "createdAt": "2026-07-27T09:15:42.108Z"
    }
  ],
  "total": 428
}
```

Тип `debit` — списание за использование, `credit` — пополнение. Поле `amount` — сумма
в рублях, `model` — модель, за которую списано.

## Статистика

```
GET https://api.agentapi.ru/billing/stats?startDate=2026-07-01&endDate=2026-07-27
```

```json
{
  "totalSpent": 214.87,
  "totalRequests": 1043,
  "averageCost": 0.206
}
```

Расход по дням:

```
GET https://api.agentapi.ru/stats/usage?period=30d
```

`period` — `7d`, `30d` или `90d`.

```json
{
  "summary": {
    "totalTokens": 1842905,
    "totalCost": 214.87,
    "currency": "RUB",
    "period": "30d"
  },
  "daily": [
    { "date": "2026-07-26", "tokens": 84120, "cost": 9.74, "requests": 47 },
    { "date": "2026-07-27", "tokens": 12508, "cost": 1.43, "requests": 9 }
  ]
}
```

За всё время:

```
GET https://api.agentapi.ru/stats/lifetime
```

```json
{ "totalTokens": 14820355, "totalCost": 1734.02 }
```

Статистика агрегируется **по аккаунту**. Разбивки по отдельным ключам нет — если нужно
разделять расходы по проектам, используйте поле `metadata` или `session_id` в запросах
и считайте на своей стороне.

## Пополнение

Через интерфейс [профиля](https://agentapi.ru/profile) (YooKassa). Лимиты — от 100 ₽ до 100 000 ₽ за платёж.

Пополнение необходимо и для **создания** ключа: при нулевом балансе создание вернёт
`403 Insufficient balance to create an API key`.

## Как сократить расходы

- **Выбирайте модель под задачу.** Разница в цене между флагманскими и компактными
  моделями — порядок и больше. Цены за токен видны в каталоге [Моделей](https://agentapi.ru/models).
- **Ограничивайте `max_tokens`.** Оплачивается и ввод, и вывод.
- **Следите за длиной контекста.** В многоходовом диалоге вся история пересылается
  заново на каждом шаге — обрезайте старые сообщения.
- **Прогоните репрезентативные запросы** и посмотрите транзакции и статистику, прежде чем
  выводить фичу в продакшн.