## AI-квота компании

`GET /v1/ai/quota`

Возвращает состояние месячной AI-квоты портала, к которому привязан API-ключ: процент израсходованного лимита, дату сброса и разбивку по моделям — сколько запросов пришлось на каждую модель и какую долю месячного лимита она израсходовала.

Квота — портальная: лимит общий для всей компании, а не per-ключ. Абсолютные значения лимита (в Вайбах) API не раскрывает — только проценты.

## Параметры

Без параметров.

## Примеры

### curl — личный ключ

```bash
curl "https://vibecode.bitrix24.tech/v1/ai/quota" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth-приложение

```bash
curl "https://vibecode.bitrix24.tech/v1/ai/quota" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — личный ключ

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/ai/quota', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log(`Квота использована на ${data.pctUsed}%, сброс ${data.resetAt}`)
data.byModel.forEach((m) => {
  console.log(`  ${m.modelId}: ${m.calls} запросов, ${m.pctOfLimit ?? 0}% лимита`)
})
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/ai/quota', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
console.log(`Квота использована на ${data.pctUsed}%, сброс ${data.resetAt}`)
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | Всегда `true` при успехе |
| `data.pctUsed` | number | Процент израсходованной месячной квоты. Честное значение — не обрезается на 100: перерасход показывается как есть (например, `150`) |
| `data.exhausted` | boolean | `true`, когда квота исчерпана |
| `data.resetAt` | string \| null | Дата сброса квоты в `ISO 8601` (скользящее 30-дневное окно). `null`, пока по порталу не было ни одного тарифицируемого AI-вызова |
| `data.pacing` | object \| null | Состояние равномерного расходования квоты (пейсинг). `null`, если пейсинг выключен для портала — не включён ни платформой, ни администратором (см. «Равномерное расходование (pacing)» ниже) |
| `data.pacing.mode` | string | Режим реакции на превышение окна: `wallet`, `block` или `ignore` |
| `data.pacing.active` | boolean | `true`, только если превышение окна прямо сейчас приведёт к `429`: энфорсмент включён на платформе и режим не `ignore`. `false` — режим наблюдения или `ignore`: окна только информируют, блокировок и списаний нет |
| `data.pacing.day.pctUsed` | number | Расход суточного окна в процентах от его собственного лимита (не от месячной квоты) |
| `data.pacing.day.resetAt` | string | Момент сброса суточного окна в `ISO 8601` |
| `data.pacing.week.pctUsed` | number | Расход недельного окна в процентах от его собственного лимита |
| `data.pacing.week.resetAt` | string | Момент сброса недельного окна в `ISO 8601` |
| `data.period.start` | string | Начало текущего окна квоты в `ISO 8601` |
| `data.byModel` | array | Разбивка по моделям за текущее окно, сортировка по убыванию количества вызовов |
| `data.byModel[].modelId` | string | ID модели |
| `data.byModel[].calls` | number | Количество успешных вызовов |
| `data.byModel[].pctOfLimit` | number \| null | Доля месячного лимита, израсходованная этой моделью, в процентах (один знак после запятой). `null`, когда у портала нет положительного лимита |

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

```json
{
  "success": true,
  "data": {
    "pctUsed": 12,
    "exhausted": false,
    "resetAt": "2026-07-31T18:50:39.633Z",
    "pacing": {
      "mode": "wallet",
      "active": false,
      "day": { "pctUsed": 42, "resetAt": "2026-07-10T21:00:00.000Z" },
      "week": { "pctUsed": 18, "resetAt": "2026-07-13T21:00:00.000Z" }
    },
    "period": { "start": "2026-07-01T18:50:39.633Z" },
    "byModel": [
      {
        "modelId": "bitrix/openai/gpt-oss-120b",
        "calls": 63017,
        "pctOfLimit": 10.9
      },
      {
        "modelId": "bitrix/bitrixgpt-5.5",
        "calls": 1240,
        "pctOfLimit": 1.2
      }
    ]
  }
}
```

## Равномерное расходование (pacing)

Пейсинг — дополнительные суточный и недельный лимиты расхода AI-квоты, каждый в процентах от общего месячного лимита. Платформа может включать пейсинг для портала по умолчанию (без действий администратора); раскатка поэтапная, поэтому не каждый портал уже покрыт. Администратор портала может включить пейсинг сам в кабинете `/ai`; если портал под платформенным default-on — только ужесточить лимиты: ослабить их или выключить пейсинг нельзя, пока портал управляется платформенными настройками по умолчанию. Пейсинг не меняет саму месячную квоту — он сглаживает пики, не позволяя потратить весь месячный лимит за один день или час.

Режим реакции на превышение окна настраивается администратором и приходит в поле `pacing.mode`:

| Режим | Поведение при превышении окна |
|-------|-------------------------------|
| `wallet` | Вызов проходит как оплачиваемое превышение лимита — списывается с денежного баланса портала, при наличии средств и свободного часового лимита превышений |
| `block` | Вызов отклоняется `429` до сброса окна — оплачиваемое превышение недоступно |
| `ignore` | Окно считается для мониторинга, вызовы не блокируются |

### Поле `pacing` в ответе

Текущее состояние пейсинга отдаётся в `data.pacing` (см. «Поля ответа» выше) — `null`, если пейсинг выключен для портала (не включён ни платформой, ни администратором):

```json
{
  "mode": "wallet",
  "active": false,
  "day": { "pctUsed": 42, "resetAt": "2026-07-10T21:00:00.000Z" },
  "week": { "pctUsed": 18, "resetAt": "2026-07-13T21:00:00.000Z" }
}
```

`active: false` означает, что превышение окна не приводит к `429` — это информационный режим: лимиты окон показываются в ответе, но не отклоняют запросы (`429` в этом состоянии невозможен). Так бывает и в демо-режиме платформенного энфорсмента, и при `mode: "ignore"` — режиме, который платформа применяет к порталам под default-on. `active: true` — превышение окна прямо сейчас приведёт к отказу в вызове. Как и весь ответ `GET /v1/ai/quota`, состояние пейсинга кэшируется — статус запаздывает до 30 секунд.

### Ошибка при превышении окна

Когда пейсинг активен и суточный или недельный лимит пробит, запросы к [чат-комплишенам](/docs/ai/chat/completions), [эмбеддингам](/docs/ai/embeddings) и [расшифровке аудио](/docs/ai/audio/transcriptions) отвечают `429`:

```json
{
  "success": false,
  "error": {
    "code": "ai_pacing_limited",
    "type": "rate_limit_exceeded",
    "message": "AI pacing window exceeded for this portal. Wait for the window reset or adjust pacing settings in the cabinet.",
    "reason": "day_window",
    "overageDenied": "wallet_empty",
    "resetAt": "2026-07-11T00:00:00.000Z",
    "retryAfter": 3600
  }
}
```

| Поле | Тип | Описание |
|------|-----|----------|
| `reason` | string | Какое окно пробито: `day_window` или `week_window` |
| `overageDenied` | string \| null | Причина отказа в оплачиваемом превышении лимита. Присутствует в ответе всегда: `wallet_empty` — не хватает средств на балансе портала, `breaker` — сработал часовой предохранитель расхода сверх квоты, `wallet_off` — портал не может расходовать сверх лимита. `null` — в режиме `block`, где оплачиваемое превышение недоступно в принципе |
| `resetAt` | string | Момент, когда окно сбросится и вызовы снова начнут проходить, в `ISO 8601` |
| `retryAfter` | number | То же время в секундах — совпадает со значением заголовка ответа `Retry-After` |

### Как реагировать

- **Соблюдайте `Retry-After` и `resetAt`.** Повторный вызов раньше указанного времени ничего не ускорит — квота не станет доступнее.
- **В режиме `wallet` смотрите `overageDenied`.** `429` в этом режиме означает не «пейсинг запрещает вызовы вообще», а «отказано именно в оплачиваемом превышении лимита» — например, `wallet_empty` сигнализирует, что стоит пополнить баланс портала.
- **Это не то же самое, что `402 ai_quota_exhausted`.** Пейсинг ограничивает скорость расхода в рамках ещё не исчерпанной месячной квоты. Ошибка `402` — сигнал о полном исчерпании самой квоты. Подробнее про `402` — в [описании ошибок чата](/docs/ai/chat/completions).

## Пример ответа при ошибке

`403 scope_missing` — у API-ключа нет скоупа `vibe:ai`:

```json
{
  "error": {
    "message": "API key does not have the vibe:ai scope required for AI endpoints. Add vibe:ai scope to your API key in portal settings.",
    "type": "invalid_request_error",
    "code": "scope_missing"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 403 | `scope_missing` | API-ключу не хватает скоупа `vibe:ai` |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Ключ не найден или отозван |
| 429 | `rate_limit_exceeded` | Превышен лимит запросов к AI-эндпоинтам. Время до сброса — в заголовке `Retry-After` |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

**`pctOfLimit` считается по моделям программы квоты.** Модель, не входящая в программу квоты (для неё не настроена тарифная политика), присутствует в `byModel` со счётчиком вызовов, но её `pctOfLimit` равен `0` — она не расходует квоту.

**Разбивка не включает Cowork-трафик.** Вызовы, тарифицируемые персональной подпиской Cowork/Code, не расходуют квоту компании и в разбивку не входят.

**Сумма `pctOfLimit` может отличаться от `pctUsed`.** `pctUsed` читается из леджера квоты и отражает условия тарификации на момент вызова (включая скидку «выгодных часов», если она активна), а `pctOfLimit` — пиковая оценка: пересчёт по текущим тарифным политикам за окно, без учёта скидок. При смене политик в середине окна значения могут расходиться.

**Ответ кэшируется на 30 секунд.** Счётчики обновляются с задержкой до 30 секунд — для мониторинга квоты этого достаточно, опрашивать чаще нет смысла.

**При исчерпании квоты вызовы моделей отвечают `402 ai_quota_exhausted`.** Подробнее — в описании ошибок [чата](/docs/ai/chat). Чтобы предупредить пользователя заранее, опрашивайте `pctUsed` и `exhausted` до вызова модели, а не дожидайтесь отказа.

**При срабатывании пейсинга вызовы моделей отвечают `429 ai_pacing_limited`.** Отдельно от `402 ai_quota_exhausted` — пейсинг ограничивает скорость расхода ещё не исчерпанной квоты. Подробнее — в разделе «Равномерное расходование (pacing)» выше.

## Смотрите также

- [Расписание выгодных часов](/docs/ai/consumption/off-peak)
- [Статистика использования](/docs/ai/consumption/usage)
- [Список моделей](/docs/ai/models/list)
- [AI Router](/docs/ai)