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

# Get usage

> Usage statistics for the authenticated key — totals plus breakdowns by model, provider, and mode.

<Note>
  **GET** `https://api.prysm1.com/v1/usage` · Requires authentication
</Note>

Returns aggregated usage for the authenticated key: total requests, tokens, and cost,
broken down by model, provider, and mode, with the most recent calls.

## Authorization

<ParamField header="Authorization" type="string" required>
  Your secret key as a bearer token: `Bearer prysm_sk_...`
</ParamField>

## Response

<ResponseField name="user_id" type="string">The account this key belongs to.</ResponseField>
<ResponseField name="plan" type="string">Plan ID: `free` | `personal` | `pro` | `corporate`.</ResponseField>
<ResponseField name="plan_display" type="string">Human-readable plan name (e.g. `"Pro"`).</ResponseField>

<ResponseField name="limits" type="object">
  Current plan limits and live consumption counters — useful for building dashboards or checking
  headroom before an API call.

  | Field                      | Type                   | Description                                                       |
  | -------------------------- | ---------------------- | ----------------------------------------------------------------- |
  | `daily_requests`           | `integer \| null`      | Max requests per 24h. `null` = unlimited.                         |
  | `rpm`                      | `integer`              | Max requests per minute.                                          |
  | `daily_requests_used`      | `integer`              | Requests made in the last 24h.                                    |
  | `daily_requests_remaining` | `integer \| null`      | Headroom left today. `null` = unlimited.                          |
  | `model_access.type`        | `"all" \| "allowlist"` | Whether all models are accessible or only a subset.               |
  | `model_access.models`      | `string[] \| null`     | Explicit allowlist (Free plan only); `null` for all-access plans. |
</ResponseField>

<ResponseField name="total_requests" type="integer">Total requests made (all time).</ResponseField>
<ResponseField name="total_tokens" type="integer">Total tokens (input + output).</ResponseField>
<ResponseField name="total_cost_usd" type="number">Total spend, USD.</ResponseField>

<ResponseField name="by_model" type="object">
  Per-model breakdown, keyed by model ID — each with `requests`, `tokens`, `cost_usd`.
</ResponseField>

<ResponseField name="by_provider" type="object">
  Per-provider breakdown, same shape as `by_model`.
</ResponseField>

<ResponseField name="by_mode" type="object">
  Per-mode breakdown (`quality` / `balanced` / `agility` / `direct`), same shape.
</ResponseField>

<ResponseField name="recent" type="object[]">
  The most recent requests (newest first).
</ResponseField>

<RequestExample>
  ```python Python theme={null}
  from prysm import Prysm

  client = Prysm()
  print(client.usage())
  ```

  ```typescript Node theme={null}
  import { Prysm } from "@prysmai/sdk";

  const client = new Prysm();
  console.log(await client.usage());
  ```

  ```bash cURL theme={null}
  curl https://api.prysm1.com/v1/usage \
    -H "Authorization: Bearer $PRYSM_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "user_id": "usr_demo",
    "plan": "free",
    "plan_display": "Free",
    "limits": {
      "daily_requests": 1000,
      "rpm": 10,
      "daily_requests_used": 128,
      "daily_requests_remaining": 872,
      "model_access": {
        "type": "allowlist",
        "models": ["gemini-2.5-flash-lite", "gpt-5-nano", "mistral-nemo"]
      }
    },
    "total_requests": 128,
    "total_tokens": 512340,
    "total_cost_usd": 0.2145,
    "by_model": {
      "mistral-nemo": { "requests": 90, "tokens": 360000, "cost_usd": 0.0072 }
    },
    "by_provider": {
      "mistral": { "requests": 90, "tokens": 360000, "cost_usd": 0.0072 }
    },
    "by_mode": {
      "balanced": { "requests": 100, "tokens": 420000, "cost_usd": 0.0084 }
    },
    "recent": []
  }
  ```
</ResponseExample>

<Tip>
  Use [`GET /v1/savings`](/api-reference/savings) to compute estimated savings versus an
  all-premium baseline in one call — or call `client.savings()` in the
  [Python](/sdks/python) and [Node](/sdks/node) SDKs for the same result.
</Tip>