# Usage (/api-v2/usage)



Every generation records one usage event with the customer-facing metrics: tokens, realized reuse and its evidence level, the full QoS outcome, the resolved routing, and the amount charged. This endpoint reads them back, with a rolled-up summary and an optional grouped breakdown. See [reuse metrics](/concepts/reuse-metrics) and [QoS](/concepts/qos).

Realized reuse is not the same as reuse opportunity. A handle is not a cache hit; this surface reports what was actually captured, with an evidence level on every number.

All requests require a bearer API key. See [authentication](/api-reference/authentication).

## Read usage [#read-usage]

`GET /v2/usage`

<ParamField query="group_by" type="string">
  Add an aggregated breakdown along one dimension: `provider`, `model`, `profile`, `region`, or `day`.
</ParamField>

```bash
curl "https://api.zumik.ai/v2/usage?group_by=provider" \
  -H "Authorization: Bearer $ZUMIK_API_KEY"
```

```json
{
  "object": "usage",
  "project_id": "prj_01jy7n0a4c8m2t6v9q3wrxk7bd",
  "summary": {
    "request_count": 124,
    "input_tokens": 2261760,
    "output_tokens": 39680,
    "cached_tokens": 1854720,
    "realized_reused_tokens": 1854720,
    "realized_reuse_ratio": 0.82,
    "charged_micros": 1284000,
    "avg_latency_ms": 1620
  },
  "group_by": "provider",
  "breakdown": [
    {
      "key": "openai",
      "request_count": 90,
      "input_tokens": 1640000,
      "output_tokens": 28800,
      "realized_reused_tokens": 1345000,
      "charged_micros": 930000
    }
  ],
  "data": [
    {
      "id": "trc_01jy7nkl45o7p8q9r0s1t2u3vw",
      "object": "usage_event",
      "project_id": "prj_01jy7n0a4c8m2t6v9q3wrxk7bd",
      "created_at": "2026-06-15T16:25:55Z",
      "requested_model": "code.fast",
      "alias_release_id": "alr_01jy7nhi23m5n6o7p8q9r0s1tu",
      "resolved_provider": "openai",
      "resolved_model": "gpt-4o",
      "region": "us",
      "execution_profile": "managed_provider",
      "execution_mode": "live",
      "input_tokens": 18240,
      "output_tokens": 320,
      "total_tokens": 18560,
      "cached_tokens": 14980,
      "realized_reused_tokens": 14980,
      "reuse_evidence_level": "provider_reported",
      "cache_tier": "provider",
      "qos_class": "interactive",
      "qos_admission": "admitted",
      "qos_completion": "completed",
      "target_met": true,
      "deadline_met": true,
      "degraded": false,
      "fallback_used": false,
      "reason_code": null,
      "ttft_ms": 312,
      "latency_ms": 1840,
      "charged_micros": 10350
    }
  ]
}
```

<ResponseField name="object" type="string">
  Always `usage`.
</ResponseField>

<ResponseField name="project_id" type="string">
  The owning project.
</ResponseField>

<ResponseField name="summary" type="object">
  Rolled-up totals across all matching events.

  <Expandable title="summary">
    <ResponseField name="request_count" type="integer">
      Number of generations.
    </ResponseField>

    <ResponseField name="input_tokens" type="integer">
      Total input tokens.
    </ResponseField>

    <ResponseField name="output_tokens" type="integer">
      Total output tokens.
    </ResponseField>

    <ResponseField name="cached_tokens" type="integer">
      Total provider-reported cached tokens.
    </ResponseField>

    <ResponseField name="realized_reused_tokens" type="integer">
      Total realized reused tokens.
    </ResponseField>

    <ResponseField name="realized_reuse_ratio" type="number">
      Realized reused tokens over input tokens.
    </ResponseField>

    <ResponseField name="charged_micros" type="integer">
      Total charged in micro-USD.
    </ResponseField>

    <ResponseField name="avg_latency_ms" type="integer">
      Mean latency across events.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="group_by" type="string">
  The dimension the breakdown is grouped by, when requested.
</ResponseField>

<ResponseField name="breakdown" type="array">
  Per-group rows sorted by request count, each with `key`, `request_count`, `input_tokens`, `output_tokens`, `realized_reused_tokens`, and `charged_micros`. Omitted when no `group_by` is set.
</ResponseField>

<ResponseField name="data" type="array">
  The most recent usage events, newest first (capped per response). See the event fields below.
</ResponseField>

### Usage event fields [#usage-event-fields]

<ResponseField name="id" type="string">
  The event id; equals the generation's trace id, prefixed 

  `trc_`

  .
</ResponseField>

<ResponseField name="object" type="string">
  Always 

  `usage_event`

  .
</ResponseField>

<ResponseField name="created_at" type="string">
  RFC 3339 timestamp.
</ResponseField>

<ResponseField name="requested_model" type="string">
  The model alias requested.
</ResponseField>

<ResponseField name="alias_release_id" type="string">
  The 

  `alr_...`

   release that served the routing, or 

  `null`

  .
</ResponseField>

<ResponseField name="resolved_provider" type="string">
  The provider the request resolved to.
</ResponseField>

<ResponseField name="resolved_model" type="string">
  The concrete model.
</ResponseField>

<ResponseField name="region" type="string">
  The execution region.
</ResponseField>

<ResponseField name="execution_profile" type="string">
  `managed_provider`

  , 

  `byok`

  , or 

  `subscription`

  .
</ResponseField>

<ResponseField name="execution_mode" type="string">
  `live`

   or 

  `placeholder`

  .
</ResponseField>

<ResponseField name="input_tokens" type="integer">
  Input tokens for the generation.
</ResponseField>

<ResponseField name="output_tokens" type="integer">
  Output tokens.
</ResponseField>

<ResponseField name="total_tokens" type="integer">
  Input plus output.
</ResponseField>

<ResponseField name="cached_tokens" type="integer">
  Provider-reported cached tokens.
</ResponseField>

<ResponseField name="realized_reused_tokens" type="integer">
  Tokens actually reused.
</ResponseField>

<ResponseField name="reuse_evidence_level" type="string">
  How much the reuse number is trusted: 

  `provider_reported`

  , 

  `runtime_confirmed`

  , 

  `router_inferred`

  , 

  `trace_estimated`

  , or 

  `unknown`

  .
</ResponseField>

<ResponseField name="cache_tier" type="string">
  Where reuse was served from: 

  `provider`

  , 

  `gpu`

  , 

  `host_ram`

  , 

  `nvme`

  , 

  `remote_kv`

  , or 

  `unknown`

  .
</ResponseField>

<ResponseField name="qos_class" type="string">
  The QoS class: 

  `interactive`

  , 

  `standard`

  , 

  `background`

  , or 

  `batch`

  .
</ResponseField>

<ResponseField name="qos_admission" type="string">
  `admitted`

  , 

  `queued`

  , 

  `rejected`

  , or 

  `expired_before_start`

  .
</ResponseField>

<ResponseField name="qos_completion" type="string">
  `completed`

  , 

  `failed`

  , 

  `cancelled`

  , or 

  `expired_during_execution`

  .
</ResponseField>

<ResponseField name="target_met" type="boolean">
  Whether the TTFT target was met, or 

  `null`

  .
</ResponseField>

<ResponseField name="deadline_met" type="boolean">
  Whether the deadline was met, or 

  `null`

  .
</ResponseField>

<ResponseField name="degraded" type="boolean">
  Whether the request was served degraded.
</ResponseField>

<ResponseField name="fallback_used" type="boolean">
  Whether a fallback profile served it.
</ResponseField>

<ResponseField name="reason_code" type="string">
  A stable reason code when a target was missed, otherwise 

  `null`

  .
</ResponseField>

<ResponseField name="ttft_ms" type="integer">
  Time to first token.
</ResponseField>

<ResponseField name="latency_ms" type="integer">
  Total latency.
</ResponseField>

<ResponseField name="charged_micros" type="integer">
  Amount charged for this generation in micro-USD.
</ResponseField>

## Errors [#errors]

| Status | Code              | When                        |
| ------ | ----------------- | --------------------------- |
| 401    | `invalid_api_key` | Missing or invalid API key. |

See the full table on [errors](/api-reference/errors).