لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/ai/consumption.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Usage and limits

How many AI resources have been spent, how much of the Bitrix24 account monthly quota is already used, and during which hours the quota drains slower.

Usage statistics are counted per API key: tokens, cost and a per-model breakdown for the selected period. The quota is counted per Bitrix24 account: a single monthly limit shared by all of its keys. Off-peak is the discount schedule that makes that quota drain slower during certain hours of the week.

Scope: vibe:ai

Usage statistics

GET /v1/ai/usage

Returns aggregated AI usage statistics for the current API key: overall metrics for the period, a per-model breakdown, the last 10 calls, and a grouping by credential type (PLATFORM, PORTAL, USER).

Parameters

Parameter Type Required Default Description
Parameterdays (query) Typenumber Requiredno Default30 DescriptionPeriod in days. Allowed range: 1..90. Values outside the range are automatically clamped to the bounds

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/ai/usage?days=7" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/ai/usage?days=7" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

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

const { data } = await res.json()
console.log(`Over ${data.period.days} days: ${data.totals.calls} calls, ${data.totals.totalTokens} tokens`)
data.byModel.forEach((m) => console.log(`  ${m.modelId}: ${m.calls} requests, ${m.cost} Vibe credits`))

JavaScript — OAuth application

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

const { data } = await res.json()
console.log('Cost over 30 days:', data.totals.cost, 'Vibe credits')

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.period.days Typenumber DescriptionActual period in days (after clamping to 1..90)
Fielddata.period.since Typestring DescriptionStart of the period in ISO 8601
Fielddata.totals.calls Typenumber DescriptionTotal number of calls for the period (all statuses)
Fielddata.totals.promptTokens Typenumber DescriptionSum of input tokens
Fielddata.totals.completionTokens Typenumber DescriptionSum of response tokens
Fielddata.totals.totalTokens Typenumber DescriptionSum of all tokens
Fielddata.totals.cost Typenumber DescriptionTotal cost in Vibe credits
Fielddata.byModel Typearray DescriptionBreakdown of successful calls by model, sorted by call count descending
Fielddata.byModel[].modelId Typestring DescriptionModel ID
Fielddata.byModel[].calls Typenumber DescriptionNumber of calls
Fielddata.byModel[].promptTokens Typenumber DescriptionInput tokens
Fielddata.byModel[].completionTokens Typenumber DescriptionResponse tokens
Fielddata.byModel[].totalTokens Typenumber DescriptionSum of tokens
Fielddata.byModel[].cost Typenumber DescriptionCost in Vibe credits
Fielddata.byModel[].audioSeconds Typenumber DescriptionSeconds of transcribed audio (Whisper). For text models — 0
Fielddata.recentCalls Typearray DescriptionThe last 10 calls of any status
Fielddata.recentCalls[].modelId Typestring DescriptionModel ID
Fielddata.recentCalls[].promptTokens Typenumber DescriptionInput tokens
Fielddata.recentCalls[].completionTokens Typenumber DescriptionResponse tokens
Fielddata.recentCalls[].cost Typenumber DescriptionCost of the call in Vibe credits
Fielddata.recentCalls[].status Typestring DescriptionStatus: SUCCESS, ERROR, INCOMPLETE, FALLBACK_ORIGIN, DISABLED_REDIRECT
Fielddata.recentCalls[].createdAt Typestring DescriptionCall time in ISO 8601
Fielddata.recentCallsDataSince Typestring | null DescriptionPer-call history boundary in ISO 8601: recentCalls contains no calls older than it. null means the key's whole history is available
Fielddata.byScope Typeobject DescriptionBreakdown by credential type, keys: PLATFORM, PORTAL, USER
Fielddata.byScope.<scope>.calls Typenumber DescriptionNumber of calls through this credential type
Fielddata.byScope.<scope>.promptTokens Typenumber DescriptionInput tokens
Fielddata.byScope.<scope>.completionTokens Typenumber DescriptionResponse tokens

Response example

JSON 
{
  "success": true,
  "data": {
    "period": {
      "days": 7,
      "since": "2026-04-20T11:30:00.000Z"
    },
    "totals": {
      "calls": 142,
      "promptTokens": 45200,
      "completionTokens": 18300,
      "totalTokens": 63500,
      "cost": 12.5
    },
    "byModel": [
      {
        "modelId": "bitrix/bitrixgpt-5.5",
        "calls": 98,
        "promptTokens": 28000,
        "completionTokens": 11000,
        "totalTokens": 39000,
        "cost": 0,
        "audioSeconds": 0
      },
      {
        "modelId": "openai/gpt-4o",
        "calls": 44,
        "promptTokens": 17200,
        "completionTokens": 7300,
        "totalTokens": 24500,
        "cost": 12.5,
        "audioSeconds": 0
      }
    ],
    "recentCalls": [
      {
        "modelId": "bitrix/bitrixgpt-5.5",
        "promptTokens": 120,
        "completionTokens": 85,
        "cost": 0,
        "status": "SUCCESS",
        "createdAt": "2026-04-27T11:30:00.000Z"
      },
      {
        "modelId": "openai/gpt-4o",
        "promptTokens": 350,
        "completionTokens": 200,
        "cost": 0.28,
        "status": "SUCCESS",
        "createdAt": "2026-04-27T09:45:00.000Z"
      }
    ],
    "recentCallsDataSince": null,
    "byScope": {
      "PLATFORM": {
        "calls": 98,
        "promptTokens": 28000,
        "completionTokens": 11000
      },
      "USER": {
        "calls": 44,
        "promptTokens": 17200,
        "completionTokens": 7300
      }
    }
  }
}

Error response example

403 scope_missing — the API key does not have the vibe:ai scope:

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

Errors

HTTP Code Description
HTTP400 Codeno_api_key DescriptionThe request arrived without an API key identifier
HTTP403 Codescope_missing DescriptionThe API key is missing the vibe:ai scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed

Full list of common API errors — Errors.

Known specifics

recentCalls always contains up to 10 entries. They do not depend on the days parameter — these are simply the last 10 calls regardless of whether they fall within the selected period.

Per-call history is kept for a limited time — at least 35 days. If the key is older than that boundary, recentCallsDataSince carries its date: calls before it never appear in recentCalls, so an empty array means "no calls since the boundary", not "no calls ever". The totals, byModel and byScope counters are not affected by the boundary.

byModel counts only SUCCESS. The per-model breakdown does not include failed calls. The overall totals counters cover all calls (including ERROR, INCOMPLETE).

Cost in Vibe credits. The cost field is the cost in Vibe credits (the platform's internal currency), not in your local or regional currency. Models priced at zero in the catalog (most bitrix/*) and BYOK yield cost: 0. Some platform models are paid — the price is taken from the pricing table AiModel.inputPriceVibes / AiModel.outputPriceVibes, viewable via GET /v1/models.

byScope.USER is calls through your BYOK. If you use a connected BYOK key, the statistics fall into byScope.USER. Platform models go into byScope.PLATFORM. If your Bitrix24 account has PORTAL credentials configured, they go into byScope.PORTAL. When there were no calls with a given scope, the key is simply absent from the object.

See also