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

GET /v1/ai/quota

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

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

#Параметры

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

#Примеры

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

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

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

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

#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-приложение

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": 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,
        "tokensIn": 58000000,
        "tokensOut": 43000000,
        "audioSeconds": 0,
        "pctOfLimit": 10.9
      },
      {
        "modelId": "bitrix/bitrixgpt-5.5",
        "calls": 1240,
        "tokensIn": 800000,
        "tokensOut": 350000,
        "audioSeconds": 0,
        "pctOfLimit": 1.2
      }
    ]
  }
}

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

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

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

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

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

{
  "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 секунд.

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

Когда пейсинг активен и суточный или недельный лимит пробит, запросы к чат-комплишенам, эмбеддингам и расшифровке аудио отвечают 429:

{
  "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
  }
}

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

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

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

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

{
  "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"
  }
}

#Ошибки

Полный список общих ошибок API — Ошибки.

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

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

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

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

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

При исчерпании квоты вызовы моделей отвечают 402 ai_quota_exhausted. Подробнее — в описании ошибок чата. Чтобы предупредить пользователя заранее, опрашивайте pctUsed и exhausted до вызова модели, а не дожидайтесь отказа.

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

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

• Расписание выгодных часов
• Статистика использования
• Список моделей
• AI Router