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

# Get Usage

> Get API usage analytics and cost tracking.

Retrieve usage analytics including request counts, token consumption, cost breakdown by mode/model, and latency percentiles.

## Authentication

Requires a Bearer token. See [Authentication](/api-reference/authentication).

## Query Parameters

<ParamField query="from" type="string">
  Start date (ISO 8601, e.g., `"2026-04-01"`).
</ParamField>

<ParamField query="to" type="string">
  End date (ISO 8601, e.g., `"2026-04-14"`).
</ParamField>

<ParamField query="scope" type="string">
  `"user"` (default when outside a team) or `"org"` (default when inside
  a team). When `"org"`, the response reflects the team's shared credit
  pool, transactions across every member, and the actor’s display name /
  email on each row. Requires the `viewUsage` permission in the active
  team.
</ParamField>

## Request Examples

<CodeGroup>
  ```bash curl theme={null}
  curl "https://www.hitheo.ai/api/v1/usage?from=2026-04-01&to=2026-04-14&scope=org" \
    -H "Authorization: Bearer $THEO_API_KEY"
  ```

  ```typescript SDK theme={null}
  const usage = await theo.usage({ from: "2026-04-01", to: "2026-04-14", scope: "org" });
  ```
</CodeGroup>

## Response

Returns usage data including:

* **Total requests** by day/week/month
* **Cost breakdown** by mode, model, and skill
* **Model distribution** — which engines handled your requests
* **Latency percentiles** — p50, p95, p99 response times
* **Cache hit rate** — percentage of requests served from semantic cache

## Endpoint

`GET /api/v1/usage`

Requires authentication via Bearer token. See [Authentication](/api-reference/authentication).