# Usage & Cost

`GET /api/usage`

Base URLs: `https://eu.whitecircle.com`, `https://us.whitecircle.com`

OpenAPI: [latest/openapi.json](https://whitecircle.com/docs/latest/openapi.json)

Retrieve your workspace's usage and cost for a time window — the same per-request-type breakdown shown in the dashboard, available with your API key. Use it to reconcile billing or power an internal usage dashboard.

Usage is aggregated across every Environment in the workspace; it is not scoped to a single Environment or API key.

## Choosing a Window

Set the window with a `period` (trailing days, `1`–`365`, default `30`) **or** an explicit `from`/`to` range — never both. `from` and `to` are inclusive, must be sent together with `from` no later than `to` or today, and can span at most 365 days. Set them to the same day to read a single day's usage.

## Cost

Each request type returns a `count` and a `cost_micros`.

> [!NOTE]
> Costs are integers in **micro-USD** — millionths of one US dollar — so amounts stay exact. Divide by 1,000,000 to convert to dollars: `250000` is `$0.25`. Each category's `cost_micros` is its `count` times your workspace's configured price for that category; unpriced categories (including `video` and `website` artifacts) return a `0` cost.

## Next Steps

- **[Check One Event](https://whitecircle.com/docs/latest/events/check-event.md)**: Submit Events that this usage counts.
- **[Policies](https://whitecircle.com/docs/latest/first-steps/policies.md)**: See how each checked Event maps to a request type.

## Authorizations

- `Authorization` (`string`, header, required): API Key required. Format: Bearer wc-your-api-key.

## Headers

- `whitecircle-version` (`string`, required): API Version. Example: `"2026-06-01"`.

## Query Parameters

- `period` (`integer<int32> | null`, optional): Trailing window in days (1–365). Mutually exclusive with `from`/`to`. Defaults to 30. Required range: `1 <= x <= 365`.
- `from` (`string<date> | null`, optional): Inclusive start day (YYYY-MM-DD). Requires `to`. Mutually exclusive with `period`.
- `to` (`string<date> | null`, optional): Inclusive end day (YYYY-MM-DD). Requires `from`. Mutually exclusive with `period`.

## Request example

```bash
curl --request GET \
  --url 'https://eu.whitecircle.com/api/usage' \
  --header "Authorization: Bearer $WHITECIRCLE_API_KEY" \
  --header 'whitecircle-version: 2026-06-01'
```

## Response

### 200

Success

`application/json`

- `from` (`string<date>`, required): Inclusive first day covered (YYYY-MM-DD).
- `to` (`string<date>`, required): Inclusive last day covered (YYYY-MM-DD).
- `message` (`object`, required)
- `message.count` (`integer<int64>`, required): Number of checks in this category. Required range: `x >= 0`.
- `message.cost_micros` (`integer<int64>`, required): Cost in millionths of one USD (divide by 1,000,000 for dollars).
- `artifact` (`object`, required)
- `artifact.image` (`object`, required)
- `artifact.image.count` (`integer<int64>`, required): Number of checks in this category. Required range: `x >= 0`.
- `artifact.image.cost_micros` (`integer<int64>`, required): Cost in millionths of one USD (divide by 1,000,000 for dollars).
- `artifact.video` (`object`, required): Video artifact checks are counted but not billed.
- `artifact.video.count` (`integer<int64>`, required): Number of checks in this category. Required range: `x >= 0`.
- `artifact.video.cost_micros` (`integer<int64>`, required): Cost in millionths of one USD (divide by 1,000,000 for dollars).
- `artifact.website` (`object`, required): Website artifact checks are counted but not billed.
- `artifact.website.count` (`integer<int64>`, required): Number of checks in this category. Required range: `x >= 0`.
- `artifact.website.cost_micros` (`integer<int64>`, required): Cost in millionths of one USD (divide by 1,000,000 for dollars).
- `tool` (`object`, required)
- `tool.count` (`integer<int64>`, required): Number of checks in this category. Required range: `x >= 0`.
- `tool.cost_micros` (`integer<int64>`, required): Cost in millionths of one USD (divide by 1,000,000 for dollars).
- `agent` (`object`, required)
- `agent.count` (`integer<int64>`, required): Number of checks in this category. Required range: `x >= 0`.
- `agent.cost_micros` (`integer<int64>`, required): Cost in millionths of one USD (divide by 1,000,000 for dollars).
- `function` (`object`, required)
- `function.count` (`integer<int64>`, required): Number of checks in this category. Required range: `x >= 0`.
- `function.cost_micros` (`integer<int64>`, required): Cost in millionths of one USD (divide by 1,000,000 for dollars).
- `reasoning` (`object`, required)
- `reasoning.count` (`integer<int64>`, required): Number of checks in this category. Required range: `x >= 0`.
- `reasoning.cost_micros` (`integer<int64>`, required): Cost in millionths of one USD (divide by 1,000,000 for dollars).
- `total_micros` (`integer<int64>`, required): Total cost across all categories, in millionths of one USD.

**Example**

```json
{
  "from": "2026-05-03",
  "to": "2026-06-01",
  "message": {
    "count": 1280,
    "cost_micros": 12800
  },
  "artifact": {
    "image": {
      "count": 340,
      "cost_micros": 34000
    },
    "video": {
      "count": 12,
      "cost_micros": 0
    },
    "website": {
      "count": 5,
      "cost_micros": 0
    }
  },
  "tool": {
    "count": 210,
    "cost_micros": 2100
  },
  "agent": {
    "count": 64,
    "cost_micros": 1280
  },
  "function": {
    "count": 88,
    "cost_micros": 880
  },
  "reasoning": {
    "count": 41,
    "cost_micros": 410
  },
  "total_micros": 51470
}
```

### 400

Bad Request
