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 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/bitrixgpt-5.5",
        "calls": 63017,
        "pctOfLimit": 10.9
      },
      {
        "modelId": "bitrix/bitrixgpt-5.5-thinking",
        "calls": 1240,
        "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 Bitrix24 account administrator can enable pacing on the /ai page of the Vibecode dashboard. 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 behavior on a tripped window is configured by the Bitrix24 account administrator and reported in the pacing.mode field:

The `pacing` field in the response

Current pacing state is returned in data.pacing: its fields are described in "Response fields" and its values are shown in "Response example" above. The field is null when pacing is off for the account — neither the platform nor the admin has enabled it.

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 in the platform enforcement demo mode and with mode: "ignore" — the 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. The body comes in the { "success": false, "error": { ... } } envelope. Fields of the error object:

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 rate of spend within a monthly quota that is not yet exhausted; 402 signals that the quota itself is fully exhausted. See the 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 its call count, 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: recalculated 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 — enough for quota monitoring, so polling more often makes no sense.

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

When pacing is triggered, model calls return 429 ai_pacing_limited. Distinct from 402 ai_quota_exhausted — pacing limits the rate 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