> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eachlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Organization Usage

> Report the authenticated organization's spend by API key, model, and day or month.

## Endpoint

```
GET https://api.eachlabs.ai/v1/usage
```

The organization comes from the API key, so a key can read only its own
organization's usage. The report covers every successful execution in the
organization, including executions made without an API key, so totals match
what the organization is billed.

## Authentication

Pass a standard API key as a Bearer token:

```http theme={"dark"}
Authorization: Bearer YOUR_API_KEY
```

## Query Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `start_date` | string | First day of `end_date`'s month | First UTC day of the report, `YYYY-MM-DD`, inclusive. |
| `end_date` | string | Today (UTC) | Last UTC day of the report, `YYYY-MM-DD`, inclusive. A date after today is capped at today. |
| `group_by` | string | none | `api_key`, `model`, or both as a comma-separated list (`api_key,model`). The parameter may also be repeated. |
| `bucket` | string | `none` | `day` or `month` splits rows by UTC day or month; `none` returns totals for the whole range. |

The range may span at most **731 days**, or **92 days** with `bucket=day`; use
`bucket=month` for longer ranges. `end_date` must not be before `start_date`
after capping. A report with more than **50,000 rows** is rejected; narrow the
date range or use a coarser bucket or grouping.

## Code Examples

```bash cURL theme={"dark"}
curl -G https://api.eachlabs.ai/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d start_date=2026-10-01 \
  -d end_date=2026-10-21 \
  -d group_by=api_key,model \
  -d bucket=month
```

```python Python theme={"dark"}
import requests

response = requests.get(
    "https://api.eachlabs.ai/v1/usage",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"start_date": "2026-10-01", "group_by": "api_key", "bucket": "day"},
    timeout=30,
)
response.raise_for_status()

for row in response.json()["rows"]:
    print(row["date"], row["api_key_name"], row["spend_usd"])
```

```javascript JavaScript theme={"dark"}
const params = new URLSearchParams({ start_date: "2026-10-01", group_by: "api_key" });
const response = await fetch(`https://api.eachlabs.ai/v1/usage?${params}`, {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});

if (!response.ok) throw new Error(`Usage request failed: ${response.status}`);
const { total_spend_usd, rows } = await response.json();
console.log(total_spend_usd, rows);
```

## Response

```json theme={"dark"}
{
  "currency": "USD",
  "start_date": "2026-10-01",
  "end_date": "2026-10-21",
  "bucket": "month",
  "group_by": ["api_key", "model"],
  "total_requests": 123,
  "total_spend_usd": 12.34,
  "rows": [
    {
      "date": "2026-10-01",
      "api_key_id": "123",
      "api_key_name": "prod",
      "model": "flux-dev",
      "requests": 100,
      "spend_usd": 10
    },
    {
      "date": "2026-10-01",
      "api_key_id": null,
      "api_key_name": null,
      "model": "flux-dev",
      "requests": 23,
      "spend_usd": 2.34
    }
  ]
}
```

### Response Fields

| Field | Type | Description |
| - | - | - |
| `currency` | string | Always `USD`. |
| `start_date` | string | Resolved first day of the report (`YYYY-MM-DD`, UTC). |
| `end_date` | string | Resolved last day of the report, after capping at today. |
| `bucket` | string | Resolved bucket: `day`, `month`, or `none`. |
| `group_by` | string\[] | Resolved groupings, deduplicated. Empty when none were requested. |
| `total_requests` | integer | Successful executions in the range. |
| `total_spend_usd` | number | Spend in the range, in USD. |
| `rows` | object\[] | One row per bucket and grouping combination, ordered by `date`, then by spend (highest first). |

Each row contains:

| Field | Type | Description |
| - | - | - |
| `date` | string \| null | The row's UTC day, or for `month` buckets the first day of the month, which can be before `start_date`. `null` when `bucket` is `none`. |
| `api_key_id` | string \| null | ID of the API key. `null` when not grouping by `api_key`, or for usage made without an API key. |
| `api_key_name` | string \| null | Name of the API key. `null` whenever `api_key_id` is `null`. |
| `model` | string \| null | Model slug. `null` when not grouping by `model`; the model ID when the slug cannot be resolved. |
| `requests` | integer | Successful executions in the row. |
| `spend_usd` | number | Spend in the row, in USD. |

USD amounts are rounded to six decimal places, so sub-cent prices are preserved.
Each row is rounded independently, so the sum of `spend_usd` can differ from
`total_spend_usd` in the last decimal place.

## Rate Limit

The endpoint allows **1 request per second with burst 3**, keyed by the
authenticated organization in each api-service process. This is a process-local
load guard, not a fleet-wide organizational quota.

A rejected request returns `429 Too Many Requests` with `Retry-After: 1`.

## Error Responses

| Status | Response | Description |
| - | - | - |
| `400` | `{"status":400,"error":"invalid argument: ..."}` | A date is not `YYYY-MM-DD`, `end_date` is before `start_date`, the range exceeds 731 days (92 with `bucket=day`), the report exceeds 50,000 rows, or `group_by` / `bucket` has an unknown value. The message names the problem. |
| `401` | Authentication error | The API key is missing or invalid, or its authenticated organization context is unavailable. |
| `429` | `{"status":429,"error":"too many requests"}` with `Retry-After: 1` | The process-local organization limit was exceeded. |
| `503` | `{"status":503,"error":"service unavailable"}` | Usage data is temporarily unavailable. Retry with bounded backoff. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.