Get Organization Usage

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:

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

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

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"])

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

{
  "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.

Overview

Models

Predictions

Billing

Content Safety

Webhooks

OpenAPI Reference

Get Organization Usage

Endpoint

Authentication

Query Parameters

Code Examples

Response

Response Fields

Rate Limit

Error Responses

​Endpoint

​Authentication

​Query Parameters

​Code Examples

​Response

​Response Fields

​Rate Limit

​Error Responses

Endpoint

Authentication

Query Parameters

Code Examples

Response

Response Fields

Rate Limit

Error Responses