# Get usage

`GET /v1/usage`

Needs an API key.

Summarise your organization's calls over the last `days` UTC days, today included.

`days` is 7, 30 or 90. Calls made by every key of the organization count, and so do those made from the console.

## Example request

cURL:

```bash
curl "https://api.voxoria.ai/v1/usage?days=30" \
  -H "Authorization: Bearer $VOXORIA_API_KEY"
```

Python:

```python
import os

import httpx

response = httpx.get(
    "https://api.voxoria.ai/v1/usage",
    params={"days": 30},
    headers={"Authorization": f"Bearer {os.environ['VOXORIA_API_KEY']}"},
)
print(response.json())
```

TypeScript:

```ts
const response = await fetch("https://api.voxoria.ai/v1/usage?days=30", {
  headers: {
    Authorization: `Bearer ${process.env.VOXORIA_API_KEY}`,
  },
});
console.log(await response.json());
```

## Query parameters

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `days` | integer | No | `30` | How many UTC days to cover, today included. One of `7`, `30`, `90`. |

## Response

### 200

Your workspace's calls over the window.

Your organization's calls over a window of days, with money as decimal strings in USD.

Days are UTC calendar days. The window is today (UTC) and the days before it, so its last day is still filling; `totals.previous` covers the same number of whole days immediately before the window. A call counts on the day it was created.

`daily` has one entry per day of the window, oldest first, including days with no calls. `by_tool` and `by_api_key` list the most charged first, then the most called, and are capped.

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| `totals` | object | No | The window's totals. |
| `totals.calls` | integer | No | Calls made. |
| `totals.succeeded` | integer | No | Calls that succeeded. |
| `totals.failed` | integer | No | Calls that failed. |
| `totals.pending` | integer | No | Calls still running. |
| `totals.charged_usd` | string | No | What the calls cost you. |
| `totals.previous` | object | No | The same totals for the window of equal length just before this one. |
| `totals.previous.calls` | integer | No | Calls made. |
| `totals.previous.succeeded` | integer | No | Calls that succeeded. |
| `totals.previous.failed` | integer | No | Calls that failed. |
| `totals.previous.pending` | integer | No | Calls still running. |
| `totals.previous.charged_usd` | string | No | What the calls cost you. |
| `daily` | array of object | No | One entry per day of the window, oldest first. |
| `daily.date` | string | No | The UTC day. Format `date`. |
| `daily.calls` | integer | No | Calls made. |
| `daily.succeeded` | integer | No | Calls that succeeded. |
| `daily.failed` | integer | No | Calls that failed. |
| `daily.charged_usd` | string | No | What the calls cost you. |
| `by_tool` | array of object | No | The window's calls by tool, most charged first. |
| `by_tool.tool` | string | No | The tool called. |
| `by_tool.calls` | integer | No | Calls made. |
| `by_tool.succeeded` | integer | No | Calls that succeeded. |
| `by_tool.failed` | integer | No | Calls that failed. |
| `by_tool.charged_usd` | string | No | What the calls cost you. |
| `by_api_key` | array of object | No | The window's calls by API key, most charged first. |
| `by_api_key.api_key` | object | Yes | Null for calls made without a key, such as from the console's playground. |
| `by_api_key.api_key.id` | string | No | The API key's ID. |
| `by_api_key.api_key.label` | string | No | The API key's label. |
| `by_api_key.calls` | integer | No | Calls made. |
| `by_api_key.charged_usd` | string | No | What the calls cost you. |

### Example 200 response

```json
{
  "totals": {
    "calls": 128,
    "succeeded": 125,
    "failed": 2,
    "pending": 1,
    "charged_usd": "2.6750",
    "previous": {
      "calls": 96,
      "succeeded": 94,
      "failed": 2,
      "pending": 0,
      "charged_usd": "2.0116"
    }
  },
  "daily": [
    {
      "date": "2026-01-05",
      "calls": 6,
      "succeeded": 6,
      "failed": 0,
      "charged_usd": "0.1284"
    }
  ],
  "by_tool": [
    {
      "tool": "google.serp.organic",
      "calls": 128,
      "succeeded": 125,
      "failed": 2,
      "charged_usd": "2.6750"
    }
  ],
  "by_api_key": [
    {
      "api_key": {
        "id": "ak_6pW2rN9tK4xB7mQ3vL8cYd",
        "label": "production"
      },
      "calls": 128,
      "charged_usd": "2.6750"
    }
  ]
}
```

## Errors

| Status | Body | Description |
| --- | --- | --- |
| 400 | [Refused request](/docs/call-response.md#refused-request) | The request was refused. |
| 401 | [Refused request](/docs/call-response.md#refused-request) | The API key is missing, wrong or revoked (`INVALID_AUTH_TOKEN`). |
| 422 | [Invalid request](/docs/call-response.md#invalid-request) | The request is not valid (`VALIDATION`). |
| 429 | [Refused request](/docs/call-response.md#refused-request) | Too many requests with this API key (`RATE_LIMITED`). |