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 Req. Default Description
days (query) number no 30 Period 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
success boolean Always true on success
data.period.days number Actual period in days (after clamping to 1..90)
data.period.since string Start of the period in ISO 8601
data.totals.calls number Total number of calls for the period (all statuses)
data.totals.promptTokens number Sum of input tokens
data.totals.completionTokens number Sum of response tokens
data.totals.totalTokens number Sum of all tokens
data.totals.cost number Total cost in Vibe credits
data.byModel array Breakdown of successful calls by model, sorted by call count descending
data.byModel[].modelId string Model ID
data.byModel[].calls number Number of calls
data.byModel[].promptTokens number Input tokens
data.byModel[].completionTokens number Response tokens
data.byModel[].totalTokens number Sum of tokens
data.byModel[].cost number Cost in Vibe credits
data.byModel[].audioSeconds number Seconds of transcribed audio (Whisper). For text models — 0
data.recentCalls array The last 10 calls of any status
data.recentCalls[].modelId string Model ID
data.recentCalls[].promptTokens number Input tokens
data.recentCalls[].completionTokens number Response tokens
data.recentCalls[].cost number Cost of the call in Vibe credits
data.recentCalls[].status string Status: SUCCESS, ERROR, INCOMPLETE, FALLBACK_ORIGIN, DISABLED_REDIRECT
data.recentCalls[].createdAt string Call time in ISO 8601
data.byScope object Breakdown by credential type, keys: PLATFORM, PORTAL, USER
data.byScope.<scope>.calls number Number of calls through this credential type
data.byScope.<scope>.promptTokens number Input tokens
data.byScope.<scope>.completionTokens number Response 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"
      }
    ],
    "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
400 no_api_key The request arrived without an API key identifier
403 scope_missing The API key is missing the vibe:ai scope
401 MISSING_API_KEY The 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.

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