---
title: "Get usage & cost"
method: GET
path: "/v1/usage"
tags: ["Usage"]
---

# Get usage & cost

`GET /v1/usage`

## Request

- Base URL: `https://api.roark.ai`
- URL: `https://api.roark.ai/v1/usage`
- Auth: HTTP bearer

Report billable usage and cost for the organization over a time window, broken down by project (highest spend first). Pass `from`/`to` as ISO 8601 timestamps; optionally pass `projectId` to scope the report to one project. Amounts are billable spend only (what we absorb is never included). Authenticated by either an organization API key with the `usage:read` permission (any project in the organization), or a project API key with the `billing:read` permission (that key's own project only; any other `projectId` is a 403).

## Query parameters

- `from` string, date-time, required: Start of the window (inclusive), ISO 8601.
- `to` string, date-time, required: End of the window (exclusive), ISO 8601. Must be after `from`, and the window may not exceed 366 days.
- `projectId` string, uuid: Limit the report to a single project. Omit for the whole organization.

## Response `200`

The usage & cost report for the window

- object
  - `data` UsageReport, required
    - `from` string, required: The resolved window start, echoed back as ISO 8601.
    - `to` string, required: The resolved window end, echoed back as ISO 8601.
    - `currency` 'usd', required
    - `totalUsdMicros` integer, required: Total billable spend across the organization (or the single project) in micro-dollars.
    - `totalUsd` number, required: The same total in US dollars.
    - `projects` UsageProjectCost[], required: Per-project billable spend, highest first. Only projects with spend in the window appear.
      - `projectId` string, uuid, required
      - `projectName` string, nullable, required: Null only if the project no longer exists in this organization.
      - `amountUsdMicros` integer, required: Billable spend in integer micro-dollars (1,000,000 = $1). The exact value.
      - `amountUsd` number, required: The same billable spend in US dollars. For display; use amountUsdMicros to reconcile.
      - `breakdown` UsageCostType[], required: This project's spend split by cost type, highest first. Sums to amountUsdMicros.
        - `source` 'SIM_PLATFORM_FEE' | 'SIM_TTS' | 'SIM_STT' | 'SIM_LLM' | 'SIM_TELEPHONY' | 'METRIC' | 'TRANSCRIPTION' | 'INTERNAL_LLM' | 'INTERNAL_STT' | 'PHONE_NUMBER', required: The cost source, e.g. SIM_PLATFORM_FEE, SIM_LLM, SIM_TTS, SIM_STT, SIM_TELEPHONY, METRIC, or TRANSCRIPTION. These are the granular sources behind the Billing screen categories (SIM_* roll up into "Simulation").
        - `surface` 'SIMULATION' | 'POST_CALL', required: Whether this cost came from a SIMULATION or a production call (POST_CALL).
        - `amountUsdMicros` integer, required: Billable spend for this type, in micro-dollars.
        - `amountUsd` number, required: The same figure in US dollars.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `500`: Internal Server Error

## Changes

> 188 revisions in range; 1 not diffed.

- **2026-10-26** `0fb1c3b1940a`: 1 warning
  - added the new `PHONE_NUMBER` enum value to the `data/projects/items/breakdown/items/source` response property for the response status `200`
- **2026-10-02** `e32b31fc8f98`: 1 info
  - added the required property `data/projects/items/breakdown` to the response with the `200` status
- **2026-10-02** `e76cbe417402`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/usage/get.md)

---

[API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) - [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roarkhq/apis/roark-analytics-api/revisions/efc3377249d1?raw)