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

Key usage stats

GET /v1/ai/credentials/:id/usage

Returns aggregated usage statistics for a specific BYOK key: total request count, token consumption, and a per-model breakdown. The period is configured via a query parameter.

Parameters

Parameter Type Required Default Description
Parameterid (path) Typestring Requiredyes Default— DescriptionKey ID from GET /v1/ai/credentials
Parameterdays (query) Typenumber Requiredno Default30 DescriptionPeriod in days. Valid 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/credentials/cred_abc123def456/usage?days=7" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

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

JavaScript — personal key

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

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

JavaScript — OAuth application

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

const { data } = await res.json()
console.log('Completion tokens:', data.completionTokens)

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.requests Typenumber DescriptionTotal number of requests through this key over the period
Fielddata.promptTokens Typenumber DescriptionSum of input tokens
Fielddata.completionTokens Typenumber DescriptionSum of response tokens
Fielddata.totalTokens Typenumber DescriptionSum of all tokens
Fielddata.byModel Typearray DescriptionBreakdown of successful requests by model, sorted by descending call count
Fielddata.byModel[].modelId Typestring DescriptionModel ID
Fielddata.byModel[].calls Typenumber DescriptionNumber of requests to this model
Fielddata.byModel[].promptTokens Typenumber DescriptionInput tokens by model
Fielddata.byModel[].completionTokens Typenumber DescriptionResponse tokens by model

Response example

JSON 
{
  "success": true,
  "data": {
    "period": {
      "days": 7,
      "since": "2026-04-20T11:30:00.000Z"
    },
    "requests": 142,
    "promptTokens": 45200,
    "completionTokens": 18300,
    "totalTokens": 63500,
    "byModel": [
      {
        "modelId": "openai/gpt-4o-mini",
        "calls": 98,
        "promptTokens": 28000,
        "completionTokens": 11000
      },
      {
        "modelId": "openai/gpt-4o",
        "calls": 44,
        "promptTokens": 17200,
        "completionTokens": 7300
      }
    ]
  }
}

Error response example

404 not_found — the key was not found or belongs to another user:

JSON 
{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Credential not found"
  }
}

Errors

HTTP Code Description
HTTP404 Codenot_found DescriptionA key with this id was not found or does not belong to you
HTTP403 Codescope_missing DescriptionThe API key lacks the vibe:ai scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not provided

Full list of common API errors — Errors.

Known specifics

Only successful calls in byModel. The per-model breakdown counts only records with the SUCCESS status. The overall counters (requests, promptTokens, etc.) include all statuses — successful, failed, partially successful.

Grouping by (userId, providerId). Key-level statistics are derived from logs filtered by the combination of "your userId" + "the key's providerId" + credentialScope: USER. If you reconnected a key for the same provider, the older records are included in the new statistics, because they are matched by provider rather than by the key's id.

Difference from GET /v1/ai/usage. This endpoint shows statistics for a single BYOK key only. The general /v1/ai/usage shows all calls made with the current API key, including platform models and PORTAL credentials, not just USER BYOK.

See also