For AI agents: markdown of this page — /docs-content-en/ai/consumption/usage.md documentation index — /llms.txt

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 except DISABLED_REDIRECT)
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 DescriptionVibe credits charged over the period
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 DescriptionVibe credits charged for the model
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 DescriptionVibe credits charged for the call
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).

A call to a disabled model counts once. A request to a disabled model goes to its replacement model, and recentCalls shows two records: DISABLED_REDIRECT for the requested model, with no tokens and no cost, and the record of the call itself for the replacement model. The totals, byModel and byScope counters count only the second one.

Cost in Vibe credits. The cost field is the Vibe credits charged for the calls. Calls covered by the company AI quota or a Cowork subscription yield cost: 0. Over-quota calls count at the amount actually debited. Calls paid from the wallet count at the catalog price, with debits made once a day. The debit can be lower when an agent free token allowance applies. BYOK yields cost: 0. To estimate consumption volume, use calls and tokens. Model prices are available 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