#Company AI quota

GET /v1/ai/quota

Returns the monthly AI quota state of the Bitrix24 account the API key is bound to: the percentage of the limit consumed, the reset date, and a per-model breakdown — how many requests and tokens each model accounted for and what share of the monthly limit it consumed.

The quota is account-wide: the limit is shared across the whole Bitrix24 account, not per key. The API does not expose the absolute limit values (in Vibe credits) — percentages only.

#Parameters

None.

#Examples

#curl — personal key

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

#curl — OAuth application

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

#JavaScript — personal key

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

const { data } = await res.json()
console.log(`Quota used: ${data.pctUsed}%, resets at ${data.resetAt}`)
data.byModel.forEach((m) => {
  console.log(`  ${m.modelId}: ${m.calls} requests, ${m.pctOfLimit ?? 0}% of the limit`)
})

#JavaScript — OAuth application

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

const { data } = await res.json()
console.log(`Quota used: ${data.pctUsed}%, resets at ${data.resetAt}`)

#Response fields

#Response example

{
  "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 (day/week smoothing)

Pacing is a pair of extra daily and weekly limits on AI-quota spend, each expressed as a percentage of the overall monthly limit. The platform can enable pacing for an account by default (no admin action required); the rollout is staged, so not every account is covered yet. The account admin can enable pacing themselves from the /ai cabinet page; if the account is under the platform default-on — they can only tighten the limits: loosening them or turning pacing off is not possible while the account is managed by the platform defaults. Pacing does not change the monthly quota itself — it smooths out spikes, preventing the whole monthly limit from being spent in a single day or hour.

The enforcement behavior on a tripped window is configured by the admin and reported in the pacing.mode field:

#The `pacing` field in the response

Current pacing state is returned in data.pacing (see "Response fields" above) — null when pacing is off for the account (not enabled by the platform or the admin):

{
  "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 means tripping a window does not trigger a 429 — an informational mode: window limits are shown in the response but never reject requests (429 is impossible in this state). This happens both under platform-enforcement demo mode and under mode: "ignore" — the default mode the platform applies to accounts under default-on. active: true means tripping a window will reject a call right now. Like the rest of the GET /v1/ai/quota response, pacing state is cached — the status can lag by up to 30 seconds.

#Error when a window is exceeded

When pacing is active and the daily or weekly limit is tripped, calls to chat completions, embeddings, and audio transcription respond with 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
  }
}

#How to react

• Honor Retry-After and resetAt. Retrying before that time will not help — the quota won't become available any sooner.
• In wallet mode, read overageDenied. A 429 in this mode does not mean "pacing blocks calls outright" — it means "paid overage was specifically refused." wallet_empty, for instance, signals that the account's money balance needs a top-up.
• This is not the same as 402 ai_quota_exhausted. Pacing limits the SPEED of spend within a monthly quota that is not yet exhausted; 402 signals that the quota itself is fully exhausted. See chat error reference for 402.

#Error response example

403 scope_missing — the API key lacks the vibe:ai scope:

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

#Errors

The full list of common API errors — Errors.

#Known specifics

pctOfLimit is computed over the quota program's models. A model outside the quota program (with no pricing policy configured) appears in byModel with call and token counters, but its pctOfLimit is 0 — it does not consume the quota.

The breakdown excludes Cowork traffic. Calls billed against a personal Cowork/Code subscription do not consume the company quota and are not included in the breakdown.

The sum of pctOfLimit may differ from pctUsed. pctUsed is read from the quota ledger and reflects the billing conditions at call time (including the off-peak discount when it is active), whereas pctOfLimit is a peak estimate: a recompute over the window against the current pricing policies, without discounts. If policies change mid-window, the values can diverge.

The response is cached for 30 seconds. Counters update with a delay of up to 30 seconds — sufficient for quota monitoring, polling more often makes no sense.

When the quota is exhausted, model calls return 402 ai_quota_exhausted. For details, see the error reference of chat. To warn the user in advance, poll pctUsed and exhausted before calling the model rather than waiting for a rejection.

When pacing trips, model calls return 429 ai_pacing_limited. Distinct from 402 ai_quota_exhausted — pacing limits the speed of spend within a quota that is not yet exhausted. See "Pacing (day/week smoothing)" above.

#See also

• Off-peak schedule
• Usage statistics
• Model list
• AI Router