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

# Overview

> Programmatic access to spend, usage, tokens, and latency

The Usage API lets you query your Sail usage from scripts, CLIs, or dashboards,
the same data shown on the dashboard in [app.sailresearch.com](https://app.sailresearch.com).
It covers two families:

* **Billing & cost**: combined spend, an Inference and Sailboxes product split,
  Sailbox line-item spend, credit balance, burn rate, days remaining, per-model
  cost rankings, per-API-key inference usage, and inference token counters.
* **Operational activity & latency**: request counts and time series, recent
  requests, task activity, and turn/trajectory latency distributions.

## Base URL

```
https://api.sailresearch.com
```

## Authentication

All requests require a Bearer API key in the `Authorization` header.

<Note>
  This is the same API key you use for the inference API at
  `api.sailresearch.com`. Create or manage keys from the [Sail
  dashboard](https://app.sailresearch.com).
</Note>

<CodeGroup>
  ```python theme={null}
  import requests

  headers = {"Authorization": "Bearer YOUR_SAIL_API_KEY"}
  params = {"bucket_size": "1h", "environment": "all"}
  resp = requests.get(
      "https://api.sailresearch.com/v2/usage",
      headers=headers,
      params=params,
  )
  print(resp.json())
  ```

  ```bash theme={null}
  curl -s -H "Authorization: Bearer $SAIL_API_KEY" \
    "https://api.sailresearch.com/v2/usage?bucket_size=1h&environment=all" | jq
  ```
</CodeGroup>

## Product-aware spend

Use the summary endpoint to read combined spend and its exact product split:

```bash theme={null}
curl -s -H "Authorization: Bearer $SAIL_API_KEY" \
  "https://api.sailresearch.com/v2/usage/summary?range=30d" | \
  jq '{period_spend, product_spend, sailbox_spend}'
```

`product_spend` always has exactly two buckets, `inference` and `sailboxes`,
which add up to `period_spend`. Inference token, model, completion-window, and
latency metrics exclude Sailbox usage. See [Usage API endpoints](/usage-endpoints#product-accounting)
for the full accounting contract and field definitions.

<Card title="Endpoints" icon="code" href="/usage-endpoints" horizontal>
  Full reference for every usage route: parameters, response shapes, error
  formats, and headers.
</Card>

<Info>
  Usage data may have a slight delay and is not real-time. Billing-derived
  fields (spend, balance, per-API-key usage, token counters) are sourced from
  metered billing data and can lag the most recent minutes more than the
  operational activity and latency endpoints.
</Info>

<Note>
  Monetary fields are fractional USD cents (floats), and token fields are raw
  token counts. See [Endpoints](/usage-endpoints) for the exact units per field.
</Note>