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

# Баланс платформы и расход

> Как пополнить баланс платформы, где смотреть расход по ключам и как ограничить траты потолками.

Запросы к ИИ-бухгалтеру по ключу и автоматизации оплачиваются с баланса платформы. Вы пополняете его с карты заранее, а потом с него списывается цена каждого вызова модели. Когда баланс пуст, платные запросы получают отказ, пока его не пополнят.

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

## Пополнить баланс

Пополняет владелец или администратор организации: **Платформа → Баланс и оплата**, кнопка **Пополнить**. Сумма сразу списывается с основной карты организации. Карты здесь те же, что для подписки. Если карты ещё нет, сначала нажмите **Привязать карту** на этой же странице. Границы суммы за раз и за сутки написаны под полем суммы.

По ключу API баланс пополнить нельзя, это делает только человек в кабинете. Прочитать баланс по ключу можно:

```sh theme={null}
curl "$TUNGO_API/v1/workspaces/$WS/platform/account" -H "x-api-key: $TUNGO_KEY"
```

В ответе `balance_tiyn` — баланс в тиынах, 1 ₸ = 100 тиын. Поле `blocked_reason` говорит, почему запросы сейчас не пройдут: `balance` — баланс закончился, `cap` — достигнут месячный потолок, `disabled` — платформа выключена.

Чтобы не следить за балансом вручную, включите «Автопополнение» на той же странице. Вы задаёте порог, сумму пополнения и предел за месяц. Когда баланс опускается ниже порога, сумма сама списывается с карты организации.

> [!WARNING]
>
> Если на момент сохранения баланс уже ниже порога, автопополнение спишет деньги с карты сразу. Экран предупредит об этом и покажет сумму до того, как вы нажмёте **Сохранить и списать**.

## Сколько стоит запрос

Цена считается по токенам: всё, что отправлено модели, и всё, что она ответила. У каждой модели своя цена за 1 млн токенов. Действующие цены отдаёт открытый адрес, ключ для него не нужен:

```sh theme={null}
curl "$TUNGO_API/v1/usage-rates"
```

Поля `input_per_mtok_tiyn` и `output_per_mtok_tiyn` — цена за 1 млн токенов на входе и на выходе, в тиынах. Те же цены показаны в разделе «Цены моделей».

Один ответ ИИ-бухгалтера — это обычно несколько вызовов модели, поэтому заранее точную цену назвать нельзя. Оценку сверху даёт бесплатный запрос подсчёта: см. [Сделать первый запрос](https://docs.tungo.kz/platform/first-request.md). Настоящая цена приходит в ответе: поле `usage.cost_tiyn`, а в потоке событий — `cost_tiyn` у события `done`.

Запросы на чтение денег не стоят: списки компаний, документы, расход, состояние 1С. Платными являются только вызовы модели.

## Где смотреть расход

В разделе «Расход» видно, сколько потратил каждый ключ за месяц: запросы, токены и сумма. Таблицу можно скачать в CSV. В разделе «Журнал запросов» перечислены все запросы по ключам с кодом ответа. Что было внутри запроса, журнал не хранит. Пополнения и списания по порядку показывает «История баланса» на странице «Баланс и оплата».

То же доступно по API:

* `GET /v1/api-key/usage` — расход ключа, которым сделан запрос.
* `GET /v1/workspaces/{ws}/platform/usage` — расход организации по дням, ключам, моделям и компаниям.
* `GET /v1/workspaces/{ws}/platform/ledger` — движения баланса.
* `GET /v1/workspaces/{ws}/platform/requests` — журнал запросов по ключам.

Без параметров расход считается с начала текущего месяца по времени Алматы. Ключ на все компании видит расход всей организации. Ключ на часть компаний видит только свой расход и свои строки журнала.

## Потолки расхода

Потолок — это верхняя граница трат за календарный месяц по времени Алматы. Потолков два, и действуют они одновременно.

Потолок организации задаётся на странице «Баланс и оплата», в поле «Потолок трат за месяц». Он общий для всех ключей и автоматизаций. Когда траты доходят до него, платные запросы получают 402 с кодом `platform_cap_reached` до начала следующего месяца.

Потолок ключа задаётся при выпуске ключа или позже через «Изменить», тоже в поле «Потолок трат за месяц». Он ограничивает один ключ. При достижении приходит 402 с кодом `key_cap_reached`. Этот же отказ приходит чуть раньше, когда остаток потолка меньше оценки одного вызова модели: так ключ не выходит за свою границу.

В обоих случаях в ошибке есть поле `resets_at` — когда потолок обнулится сам. Чтобы продолжить раньше, поднимите потолок. Пустое поле означает «без потолка».

На той же странице есть выключатель «Платформа включена». Если его выключить, все вызовы по ключам и автоматизации сразу останавливаются с кодом `platform_disabled`. Включить обратно можно там же.

## Когда баланс пуст

Платный запрос получает 402 с кодом `platform_balance_exhausted`, вызов модели не делается. Повторять такой запрос бесполезно, пока баланс не пополнят. Исключение одно: если включено автопополнение, оно запускается в этот момент, и запрос стоит повторить чуть позже.

Баланс может уйти в небольшой минус. Цена вызова известна только после ответа модели, поэтому последний вызов иногда стоит больше остатка. Минус не превышает цены одного вызова и гасится следующим пополнением.

О деньгах можно узнавать заранее по вебхукам: событие `platform.balance_low` приходит, когда баланс опустился ниже порога, `platform.balance_exhausted` — когда он кончился, `platform.cap_threshold_reached` — когда траты месяца подошли к потолку организации.

## Что дальше

* [Ошибки и ограничения](https://docs.tungo.kz/platform/errors-and-limits.md): все отказы из-за денег и что с ними делать.
* [Получать события (вебхуки)](https://docs.tungo.kz/platform/webhooks.md): подписаться на события о балансе.
* [Привязать, сменить или удалить карту](https://docs.tungo.kz/billing/card.md): с какой карты списываются пополнения.


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