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

# Usage & Cost Reporting

> Pull billable usage and cost for your whole organization, broken down per project, over the API or as a CSV

Every bit of billable work in Roark (simulations, metric evaluations, transcription) is attributed to the project that incurred it. You can read that attribution three ways:

* **Billing screen** (Settings → Billing): a per-project and per-type spend breakdown for the current billing period.
* **CSV export**: the "Export CSV" button on that breakdown downloads exactly what you see, grouped by project or by type.
* **API** (`GET /v1/usage`): the same per-project figures over a date range you choose, for feeding a warehouse, a finance report, or a per-team chargeback.

This page covers the API.

## Authentication

`GET /v1/usage` is **organization-scoped**: the per-project breakdown spans every project in your organization, so it is authenticated by an **Organization API key** (the same credential family used for [org provisioning](/documentation/config-as-code/organizations)), not a project key.

The key must carry the **`usage:read`** permission. An org Owner or Admin creates a key under **Settings → Organization → API keys**; new keys are minted with the full organization permission set, so they include `usage:read`.

<Note>
  Cost visibility is a deliberately separate permission from project access. If you are using an organization key created before usage reporting launched, re-mint it so it carries `usage:read`; an older key returns `403` on this endpoint.
</Note>

## Endpoint

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

### Query parameters

| Parameter | Required | Description |
| :- | :- | :- |
| `from` | yes | Start of the window (inclusive), ISO 8601. Example: `2026-09-01T00:00:00Z`. |
| `to` | yes | End of the window (exclusive), ISO 8601. Must be after `from`, and the window may not exceed **366 days**. |
| `projectId` | no | Limit the report to a single project. Omit for the whole organization. |

### Example request

<CodeGroup>
  ```bash curl theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  curl -s "https://api.roark.ai/v1/usage?from=2026-09-01T00:00:00Z&to=2026-10-01T00:00:00Z" \
    -H "Authorization: Bearer $ROARK_ORG_API_KEY"
  ```

  ```bash one project theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  curl -s "https://api.roark.ai/v1/usage?from=2026-09-01T00:00:00Z&to=2026-10-01T00:00:00Z&projectId=7b3c0a1e-1111-2222-3333-444455556666" \
    -H "Authorization: Bearer $ROARK_ORG_API_KEY"
  ```
</CodeGroup>

### Example response

```json theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
{
  "data": {
    "from": "2026-09-01T00:00:00.000Z",
    "to": "2026-10-01T00:00:00.000Z",
    "currency": "usd",
    "totalUsdMicros": 1234567,
    "totalUsd": 1.234567,
    "projects": [
      {
        "projectId": "7b3c0a1e-1111-2222-3333-444455556666",
        "projectName": "Payments (prod)",
        "amountUsdMicros": 900000,
        "amountUsd": 0.9
      },
      {
        "projectId": "9f1a2b3c-aaaa-bbbb-cccc-ddddeeeeffff",
        "projectName": "Support line",
        "amountUsdMicros": 334567,
        "amountUsd": 0.334567
      }
    ]
  }
}
```

### Response fields

* **`totalUsdMicros` / `totalUsd`**: total billable spend across the organization (or the single project, when `projectId` is set) over the window. The total is the sum of `projects`.
* **`projects[]`**: per-project billable spend, highest first. Only projects with spend in the window appear.
* **`projectName`**: the project's current name, or `null` if the project no longer exists.
* **Micros vs dollars**: `amountUsdMicros` is the exact, canonical integer (`1,000,000` = `$1`, the unit the billing ledger stores). Use it to sum and reconcile against an invoice. `amountUsd` is the same figure as a convenience float for display.

<Note>
  Amounts are **billable** spend only. Internal costs Roark absorbs on your behalf are never included, so these figures match what you are charged.
</Note>

## Errors

| Status | Meaning |
| :- | :- |
| `400` | Missing or invalid `from`/`to`, or a window wider than 366 days. |
| `401` | Missing or invalid organization API key. |
| `403` | The organization key does not carry the `usage:read` permission. |

## Paging longer histories

The 366-day ceiling keeps a single request bounded. To report across a longer period, page the window month by month (or quarter by quarter) and sum the `totalUsdMicros` from each response.


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