[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-ai\u002Fconsumption\u002Fquota":3,"docs-tabs-ai\u002Fconsumption\u002Fquota":6},{"content":4,"lastmod":5},"\n## AI-квота компании\n\n`GET \u002Fv1\u002Fai\u002Fquota`\n\nВозвращает состояние месячной AI-квоты портала, к которому привязан API-ключ: процент израсходованного лимита, дату сброса и разбивку по моделям — сколько запросов и токенов пришлось на каждую модель и какую долю месячного лимита она израсходовала.\n\nКвота — портальная: лимит общий для всей компании, а не per-ключ. Абсолютные значения лимита (в Вайбах) API не раскрывает — только проценты.\n\n## Параметры\n\nБез параметров.\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fai\u002Fquota\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fai\u002Fquota\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fai\u002Fquota', {\n  headers: { 'X-Api-Key': 'YOUR_API_KEY' },\n})\n\nconst { data } = await res.json()\nconsole.log(`Квота использована на ${data.pctUsed}%, сброс ${data.resetAt}`)\ndata.byModel.forEach((m) => {\n  console.log(`  ${m.modelId}: ${m.calls} запросов, ${m.pctOfLimit ?? 0}% лимита`)\n})\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fai\u002Fquota', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { data } = await res.json()\nconsole.log(`Квота использована на ${data.pctUsed}%, сброс ${data.resetAt}`)\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|----------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data.pctUsed` | number | Процент израсходованной месячной квоты. Честное значение — не обрезается на 100: перерасход показывается как есть (например, `150`) |\n| `data.exhausted` | boolean | `true`, когда квота исчерпана |\n| `data.resetAt` | string \\| null | Дата сброса квоты в `ISO 8601` (скользящее 30-дневное окно). `null`, пока по порталу не было ни одного тарифицируемого AI-вызова |\n| `data.pacing` | object \\| null | Состояние равномерного расходования квоты (пейсинг). `null`, если пейсинг выключен для портала — не включён ни платформой, ни администратором (см. «Равномерное расходование (pacing)» ниже) |\n| `data.pacing.mode` | string | Режим реакции на превышение окна: `wallet`, `block` или `ignore` |\n| `data.pacing.active` | boolean | `true`, только если превышение окна прямо сейчас приведёт к `429`: энфорсмент включён на платформе и режим не `ignore`. `false` — режим наблюдения или `ignore`: окна только информируют, блокировок и списаний нет |\n| `data.pacing.day.pctUsed` | number | Расход суточного окна в процентах от его собственного лимита (не от месячной квоты) |\n| `data.pacing.day.resetAt` | string | Момент сброса суточного окна в `ISO 8601` |\n| `data.pacing.week.pctUsed` | number | Расход недельного окна в процентах от его собственного лимита |\n| `data.pacing.week.resetAt` | string | Момент сброса недельного окна в `ISO 8601` |\n| `data.period.start` | string | Начало текущего окна квоты в `ISO 8601` |\n| `data.byModel` | array | Разбивка по моделям за текущее окно, сортировка по убыванию количества вызовов |\n| `data.byModel[].modelId` | string | ID модели |\n| `data.byModel[].calls` | number | Количество успешных вызовов |\n| `data.byModel[].tokensIn` | number | Токены входа |\n| `data.byModel[].tokensOut` | number | Токены ответа |\n| `data.byModel[].audioSeconds` | number | Секунды расшифрованного аудио (Whisper). Для текстовых моделей — `0` |\n| `data.byModel[].pctOfLimit` | number \\| null | Доля месячного лимита, израсходованная этой моделью, в процентах (один знак после запятой). `null`, когда у портала нет положительного лимита |\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"pctUsed\": 12,\n    \"exhausted\": false,\n    \"resetAt\": \"2026-07-31T18:50:39.633Z\",\n    \"pacing\": {\n      \"mode\": \"wallet\",\n      \"active\": false,\n      \"day\": { \"pctUsed\": 42, \"resetAt\": \"2026-07-10T21:00:00.000Z\" },\n      \"week\": { \"pctUsed\": 18, \"resetAt\": \"2026-07-13T21:00:00.000Z\" }\n    },\n    \"period\": { \"start\": \"2026-07-01T18:50:39.633Z\" },\n    \"byModel\": [\n      {\n        \"modelId\": \"bitrix\u002Fopenai\u002Fgpt-oss-120b\",\n        \"calls\": 63017,\n        \"tokensIn\": 58000000,\n        \"tokensOut\": 43000000,\n        \"audioSeconds\": 0,\n        \"pctOfLimit\": 10.9\n      },\n      {\n        \"modelId\": \"bitrix\u002Fbitrixgpt-5.5\",\n        \"calls\": 1240,\n        \"tokensIn\": 800000,\n        \"tokensOut\": 350000,\n        \"audioSeconds\": 0,\n        \"pctOfLimit\": 1.2\n      }\n    ]\n  }\n}\n```\n\n## Равномерное расходование (pacing)\n\nПейсинг — дополнительные суточный и недельный лимиты расхода AI-квоты, каждый в процентах от общего месячного лимита. Платформа может включать пейсинг для портала по умолчанию (без действий администратора); раскатка поэтапная, поэтому не каждый портал уже покрыт. Администратор портала может включить пейсинг сам в кабинете `\u002Fai`; если портал под платформенным default-on — только ужесточить лимиты: ослабить их или выключить пейсинг нельзя, пока портал управляется платформенными настройками по умолчанию. Пейсинг не меняет саму месячную квоту — он сглаживает пики, не позволяя потратить весь месячный лимит за один день или час.\n\nРежим реакции на превышение окна настраивается администратором и приходит в поле `pacing.mode`:\n\n| Режим | Поведение при превышении окна |\n|-------|-------------------------------|\n| `wallet` | Вызов проходит как оплачиваемое превышение лимита — списывается с денежного баланса портала, при наличии средств и свободного часового лимита превышений |\n| `block` | Вызов отклоняется `429` до сброса окна — оплачиваемое превышение недоступно |\n| `ignore` | Окно считается для мониторинга, вызовы не блокируются |\n\n### Поле `pacing` в ответе\n\nТекущее состояние пейсинга отдаётся в `data.pacing` (см. «Поля ответа» выше) — `null`, если пейсинг выключен для портала (не включён ни платформой, ни администратором):\n\n```json\n{\n  \"mode\": \"wallet\",\n  \"active\": false,\n  \"day\": { \"pctUsed\": 42, \"resetAt\": \"2026-07-10T21:00:00.000Z\" },\n  \"week\": { \"pctUsed\": 18, \"resetAt\": \"2026-07-13T21:00:00.000Z\" }\n}\n```\n\n`active: false` означает, что превышение окна не приводит к `429` — это информационный режим: лимиты окон показываются в ответе, но не отклоняют запросы (`429` в этом состоянии невозможен). Так бывает и в демо-режиме платформенного энфорсмента, и при `mode: \"ignore\"` — режиме, который платформа применяет к порталам под default-on. `active: true` — превышение окна прямо сейчас приведёт к отказу в вызове. Как и весь ответ `GET \u002Fv1\u002Fai\u002Fquota`, состояние пейсинга кэшируется — статус запаздывает до 30 секунд.\n\n### Ошибка при превышении окна\n\nКогда пейсинг активен и суточный или недельный лимит пробит, запросы к [чат-комплишенам](\u002Fdocs\u002Fai\u002Fchat\u002Fcompletions), [эмбеддингам](\u002Fdocs\u002Fai\u002Fembeddings) и [расшифровке аудио](\u002Fdocs\u002Fai\u002Faudio\u002Ftranscriptions) отвечают `429`:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ai_pacing_limited\",\n    \"type\": \"rate_limit_exceeded\",\n    \"message\": \"AI pacing window exceeded for this portal. Wait for the window reset or adjust pacing settings in the cabinet.\",\n    \"reason\": \"day_window\",\n    \"overageDenied\": \"wallet_empty\",\n    \"resetAt\": \"2026-07-11T00:00:00.000Z\",\n    \"retryAfter\": 3600\n  }\n}\n```\n\n| Поле | Тип | Описание |\n|------|-----|----------|\n| `reason` | string | Какое окно пробито: `day_window` или `week_window` |\n| `overageDenied` | string \\| null | Причина отказа в оплачиваемом превышении лимита. Присутствует в ответе всегда: `wallet_empty` — не хватает средств на балансе портала, `breaker` — сработал часовой предохранитель расхода сверх квоты, `wallet_off` — портал не может расходовать сверх лимита. `null` — в режиме `block`, где оплачиваемое превышение недоступно в принципе |\n| `resetAt` | string | Момент, когда окно сбросится и вызовы снова начнут проходить, в `ISO 8601` |\n| `retryAfter` | number | То же время в секундах — совпадает со значением заголовка ответа `Retry-After` |\n\n### Как реагировать\n\n- **Соблюдайте `Retry-After` и `resetAt`.** Повторный вызов раньше указанного времени ничего не ускорит — квота не станет доступнее.\n- **В режиме `wallet` смотрите `overageDenied`.** `429` в этом режиме означает не «пейсинг запрещает вызовы вообще», а «отказано именно в оплачиваемом превышении лимита» — например, `wallet_empty` сигнализирует, что стоит пополнить баланс портала.\n- **Это не то же самое, что `402 ai_quota_exhausted`.** Пейсинг ограничивает скорость расхода в рамках ещё не исчерпанной месячной квоты. Ошибка `402` — сигнал о полном исчерпании самой квоты. Подробнее про `402` — в [описании ошибок чата](\u002Fdocs\u002Fai\u002Fchat\u002Fcompletions).\n\n## Пример ответа при ошибке\n\n`403 scope_missing` — у API-ключа нет скоупа `vibe:ai`:\n\n```json\n{\n  \"error\": {\n    \"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.\",\n    \"type\": \"invalid_request_error\",\n    \"code\": \"scope_missing\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|----------|\n| 403 | `scope_missing` | API-ключу не хватает скоупа `vibe:ai` |\n| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |\n| 401 | `INVALID_API_KEY` | Ключ не найден или отозван |\n| 429 | `rate_limit_exceeded` | Превышен лимит запросов к AI-эндпоинтам. Время до сброса — в заголовке `Retry-After` |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**`pctOfLimit` считается по моделям программы квоты.** Модель, не входящая в программу квоты (для неё не настроена тарифная политика), присутствует в `byModel` со счётчиками вызовов и токенов, но её `pctOfLimit` равен `0` — она не расходует квоту.\n\n**Разбивка не включает Cowork-трафик.** Вызовы, тарифицируемые персональной подпиской Cowork\u002FCode, не расходуют квоту компании и в разбивку не входят.\n\n**Сумма `pctOfLimit` может отличаться от `pctUsed`.** `pctUsed` читается из леджера квоты и отражает условия тарификации на момент вызова (включая скидку «выгодных часов», если она активна), а `pctOfLimit` — пиковая оценка: пересчёт по текущим тарифным политикам за окно, без учёта скидок. При смене политик в середине окна значения могут расходиться.\n\n**Ответ кэшируется на 30 секунд.** Счётчики обновляются с задержкой до 30 секунд — для мониторинга квоты этого достаточно, опрашивать чаще нет смысла.\n\n**При исчерпании квоты вызовы моделей отвечают `402 ai_quota_exhausted`.** Подробнее — в описании ошибок [чата](\u002Fdocs\u002Fai\u002Fchat). Чтобы предупредить пользователя заранее, опрашивайте `pctUsed` и `exhausted` до вызова модели, а не дожидайтесь отказа.\n\n**При срабатывании пейсинга вызовы моделей отвечают `429 ai_pacing_limited`.** Отдельно от `402 ai_quota_exhausted` — пейсинг ограничивает скорость расхода ещё не исчерпанной квоты. Подробнее — в разделе «Равномерное расходование (pacing)» выше.\n\n## Смотрите также\n\n- [Расписание выгодных часов](\u002Fdocs\u002Fai\u002Fconsumption\u002Foff-peak)\n- [Статистика использования](\u002Fdocs\u002Fai\u002Fconsumption\u002Fusage)\n- [Список моделей](\u002Fdocs\u002Fai\u002Fmodels\u002Flist)\n- [AI Router](\u002Fdocs\u002Fai)\n","2026-07-10",{}]