---
title: "Get usage for the authenticated API key"
method: GET
path: "/api/v1/usage"
tags: ["Account"]
---

# Get usage for the authenticated API key

`GET /api/v1/usage`

## Request

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

Scope is this API key: tasks created by other keys on the same account, and generations started directly in the web console (which use no API key), are not included. For an account-wide view, use the console's usage page.
Hidden historical tasks of this key are included. Other keys and
workspaces cannot be selected. Unknown or repeated query parameters
are rejected.
Dates form a UTC half-open interval [from,to), up to 92 days.
The default to is tomorrow in UTC; omitted from is seven days before to.
Calls are attributed to task creation time. Spend sums only settled
actual charges for those tasks, never pending holds. Late settlement
can change a previous day's spend. These are task usage totals, not
a statement of cash movements or remaining API-key budget.
An additional account-wide token bucket allows a burst of 30 requests
and replenishes 30 tokens per minute, shared by all keys on the account.
Observe Retry-After on 429. This reporting limit fails closed when its
limiter is unavailable. Queries have a five-second server budget;
a timeout returns 503 and suggests retrying a shorter date range.

## Query parameters

- `from` string, date
- `to` string, date

## Response `200`

Current-key usage with exact USD decimal strings and sparse daily/model buckets.

- APIKeyUsageEnvelope
  - `code` integer, required
  - `msg` string, required
  - `request_id` string, required: Correlation identifier. Include it in support requests.
  - `data` APIKeyUsageResponse, required
    - `from` string, date, required
    - `to` string, date, required
    - `currency` 'USD', required
    - `totalCalls` integer, required
    - `totalSpend` string, required: Decimal USD amount encoded as a string to avoid binary floating-point loss.
    - `totalCredits` integer, required: Total settled spend in credits (the same amount as `totalSpend`).
    - `days` UsageDayItem[], required
      - `day` string, date, required
      - `calls` integer, required
      - `succeeded` integer, required
      - `failed` integer, required
      - `spend` string, required: Decimal USD amount encoded as a string to avoid binary floating-point loss.
      - `credits` integer, required: Settled spend in credits (the same amount as `spend`).
    - `models` UsageModelItem[], required
      - `model` string, required: Model call name, `<publisher>/<model>/<task>`.
      - `calls` integer, required
      - `succeeded` integer, required
      - `failed` integer, required
      - `spend` string, required: Decimal USD amount encoded as a string to avoid binary floating-point loss.
      - `credits` integer, required: Settled spend in credits (the same amount as `spend`).

## Other responses

- `400`: Invalid JSON, query, callback URL, model input, or media declaration. Invalid callBackUrl values return code 400 and msg "Invalid callback URL" with request_id. Submitted hosts, IP addresses, and DNS diagnostics are not echoed.
- `401`: Missing, malformed, expired, revoked, or otherwise invalid API key.
- `403`: Account, model, API-key, IP, or region authorization failed.
- `429`: Account-level request limit exceeded.
- `500`: Internal failure. Details are not exposed; report `request_id` to support.
- `503`: HTTP 503 carries one of three business codes. `50301`: no usable deployment or effective customer price exists for the selected model. `503`: a dependency is temporarily unavailable; retry after the `Retry-After` header when it is present. `50302`: a synchronous generation failed upstream and the charge was refunded. Nothing was charged, but send the retry with a **new** `Idempotency-Key`: reusing the original one replays the recorded failure instead of generating again.

---

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