## 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

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

### curl — OAuth application

```bash
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](/docs/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`](/docs/ai/models/list).

**`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

- [Per-key statistics](/docs/ai/credentials/usage)
- [Model list](/docs/ai/models/list)
- [AI Router](/docs/ai)