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

# Usage Data API

> Pull your organization's daily usage and cost data programmatically

For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](https://docs.parallel.ai/llms-full.txt). You may also fetch any page as Markdown by appending `.md` to its URL or sending `Accept: text/markdown`.

For Search and Extract, use `/v1/search` and `/v1/extract` for all new integrations and agent tool calls. Use `/v1beta/search` and `/v1beta/extract` only when maintaining an existing integration that already uses them. The request bodies changed too: on `/v1/extract`, `full_content`, `fetch_policy` and `excerpt_settings` go inside `advanced_settings`, and sending the v1beta top-level `excerpts`, `full_content` and `fetch_policy` to `/v1/extract` returns a 422. Do not substitute `/v1` for the documented FindAll or Ingest endpoint paths.

The **usage endpoint** returns your organization's billed usage as daily line items, broken out by product, processor, app, and API key. It serves the same data as the Usage page in the Parallel Platform, so you can feed spend dashboards and finance pipelines without exporting CSVs by hand.

```
GET https://api.parallel.ai/account/service/v1/usage?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD
Authorization: Bearer {accessToken}
```

Authentication uses the Account API's OAuth flow with the `usage:read` scope, and the calling user must be an **admin** of the organization. See [Account API authentication](https://docs.parallel.ai/integrations/account-api.md) for the full flow; request `usage:read` as the scope. The endpoint reference lives in the **Account API** tab.

## Request

| Parameter | Type | Notes |
| - | - | - |
| `start_date` | UTC date, inclusive | Must be within the last 365 days |
| `end_date` | UTC date, exclusive | Window of at most 365 days |
| `interval` | string, optional | `daily` (default) or `monthly`: one span per UTC calendar month, clamped to the window |

## Response

One span per UTC day (or per calendar month with `interval=monthly`), each containing billed line items:

```json theme={"system"}
{
  "usage": [
    {
      "start_time": "2026-10-14T00:00:00Z",
      "end_time": "2026-10-15T00:00:00Z",
      "line_items": [
        {
          "product": "Task API v1",
          "api_key_id": "0132d760-ad18-4612-ab7e-9ec11ffedfdb",
          "api_key_name": "prod-enrichment-key",
          "app_name": "prod-enrichment",
          "processor": "core",
          "quantity": 1250,
          "total_cost_cents": 3125,
          "currency": "USD"
        }
      ]
    }
  ]
}
```

`total_cost_cents` is the total cost of the line item in cents, with quantity already applied. Fractional cents can occur.

## Recommended pattern: daily incremental pulls

Pull one day at a time on a schedule and store results on your side. The API serves the last 365 days:

```bash theme={"system"}
# Portable (GNU/BSD/macOS, Python 3.9+); one invocation so the dates cannot straddle midnight
read -r START END <<< "$(python3 -c "import datetime as d; t = d.datetime.now(d.timezone.utc).date(); print((t - d.timedelta(days=1)).isoformat(), t.isoformat())")"
curl -s "https://api.parallel.ai/account/service/v1/usage?start_date=$START&end_date=$END" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

For month-level reporting, pass `interval=monthly` to receive one span per UTC calendar month, clamped to the requested window:

```bash theme={"system"}
curl -s "https://api.parallel.ai/account/service/v1/usage?start_date=2026-10-01&end_date=2026-11-01&interval=monthly" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Good to know

* **Cost figures are usage before credits or commit drawdowns are applied**, so monthly sums can differ from your invoice total if your plan includes credits or commits. Completed days are stable; the current day updates as usage lands.
* `api_key_id` is `null` on line items not attributed to a specific API key. `api_key_name` is `null` in that case and when the key has since been deleted or rotated.
* The rate limit is 10 requests per minute per organization. A scheduled daily pull is the intended usage.
* Requests with windows larger than 365 days, a start date older than 365 days, or an unknown `interval` return `422`.