---
title: "Read your own usage"
method: GET
path: "/prod/usage"
---

# Read your own usage

`GET /prod/usage`

## Request

- Base URL: `https://api.usezn.com`
- URL: `https://api.usezn.com/prod/usage`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Monthly totals for the last 12 months with calls, the last 30 UTC days (daily) and the current-month quota. It is what the dashboard reads. Send a full API key (zn_...) or a dashboard sign-in token as the bearer token. The response always describes the account that owns the credential: no query parameter, body or header can point it at another account. Reading usage does not count as a call and does not change the key's last-used time. The path includes the stage: it is served at /prod/usage, not at /usage. This endpoint does not send RateLimit headers.

## Response `200`

Usage of the caller's account.

- UsageResponse
  - `usage` UsageMonth[], required: One entry per month with calls, newest first, up to 12.
    - `userId` string, required: The account the usage belongs to (the key owner or the signed-in user).
    - `month` string, required: Calendar month, UTC.
    - `calls` integer, required: Calls billed in the month.
    - `blocked` integer, required
    - `allowed` integer, required
    - `latencyP50` number, required: Median server-side latency in ms (0 when unknown).
    - `latencyP99` number, required: 99th percentile latency in ms (0 when unknown).
    - `blockedByRules` integer, nullable, required: Blocks decided by the deterministic rules. null for months before decidedByTrackedSince.
    - `blockedByModel` integer, nullable, required: Blocks decided by the model. null for months before decidedByTrackedSince.
    - `decidedByComplete` boolean, required: true when every call of the month is in the rules/model split.
  - `decidedByTrackedSince` string, required: Date the rules/model split of blocks started (2026-10-14).
  - `daily` UsageDay[], required: Last 30 UTC days, oldest first, ending today; days without calls are zeros.
    - `date` string, required: UTC day.
    - `blocked` integer, required
    - `allowed` integer, required
  - `dailyComplete` boolean, required: false when the history was too large to read in full, so the oldest days may be undercounted.
  - `currentMonth` UsageCurrentMonth, required
    - `userId` string, required: The account the usage belongs to (the key owner or the signed-in user).
    - `month` string, required: Calendar month, UTC.
    - `calls` integer, required: Calls billed in the month.
    - `blocked` integer, required
    - `allowed` integer, required
    - `latencyP50` number, required: Median server-side latency in ms (0 when unknown).
    - `latencyP99` number, required: 99th percentile latency in ms (0 when unknown).
    - `blockedByRules` integer, nullable, required: Blocks decided by the deterministic rules. null for months before decidedByTrackedSince.
    - `blockedByModel` integer, nullable, required: Blocks decided by the model. null for months before decidedByTrackedSince.
    - `decidedByComplete` boolean, required: true when every call of the month is in the rules/model split.
    - `breakdown` object, required: Calls of the month by the path that decided them.
      - `rules` integer, required
      - `advanced` integer, required
      - `deep` integer, required
    - `deepInvoked` integer, required
    - `callsUsed` integer, required: Calls used this month.
    - `callsLimit` integer, required: Monthly call limit of the plan (the personal limit, also for Team members; see org).
    - `quotaModel` 'single', required
    - `quotaOverrideUntil` string, nullable, required: End of a temporary larger limit, or null.
    - `standardUsed` integer, required: Deprecated mirror of callsUsed.
    - `standardLimit` integer, required: Deprecated mirror of callsLimit.
    - `deepUsed` integer, required: Deprecated mirror of callsUsed.
    - `deepLimit` integer, required: Deprecated mirror of callsLimit.
    - `neuralUsed` integer, required: Deprecated mirror of callsUsed.
    - `neuralLimit` integer, required: Deprecated mirror of callsLimit.
    - `deprecatedFields` string[], required: Names of the deprecated fields in this object.
    - `tier` 'free' | 'pro' | 'scale' | 'team' | 'internal', required
    - `plan` string, required: Plan name stored for the account (free when none).
    - `planEndsAt` string, date-time, nullable, required: End of an active plan grant; the account moves to free then. null otherwise.
    - `zdr` boolean, required: true (zero data retention) unless the account opted in as a contributor.
    - `org` object, nullable, required: Pooled quota of the Team organization the account belongs to, or null.
      - `id` string, required
      - `seats` integer, required
      - `used` integer, required
      - `limit` integer, required
      - `overageCalls` integer, required
      - `overageCapUsd` number, required

## Other responses

- `401`: A malformed, unknown or revoked API key (error: Invalid API key), or a missing or invalid sign-in token (error: Unauthorized).
- `403`: An analysis-only API key (key_scope), or a dashboard session with an unverified email (email_not_verified).
- `405`: An API key was used with a method other than GET.
- `500`: Usage could not be read.

## Changes

- **2026-10-20** `2e48398b21da`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/usezn/apis/usezn-api/changes/prod/usage/get.md)

---

[API](https://skmtc.dev/usezn/apis/usezn-api.md) · [All operations](https://skmtc.dev/usezn/apis/usezn-api/llms.txt) · [OpenAPI document](https://skmtc.dev/usezn/apis/usezn-api/revisions/2e48398b21da?raw)