---
title: "Usage meters (credit balance, period consumption)"
method: GET
path: "/v1/usage"
tags: ["usage"]
---

# Usage meters (credit balance, period consumption)

`GET /v1/usage`

## Request

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

## Response `200`

Meters + legacy fields. Same numbers as the dashboard (shared service, reconciles with the credit ledger to the second).

- UsageResponse: Usage meters + legacy dashboard fields (the flat fields are deprecated in favor of meters[]; they remain during the web-client migration).
  - `meters` Meter[], required: Data-driven meter list (§4.6 invariant #1). At launch: credit_seconds (balance) + seconds_processed.period (used/resets_at). Pricing changes add/change rows — never the schema. quota_exceeded errors carry details.meter naming which meter tripped.
    - `meter` string, required
    - `unit` string, required
    - `balance` number: Balance-shaped meters (e.g. credit_seconds).
    - `limit` number, nullable: null = unlimited/PAYG.
    - `used` number: Period-shaped meters.
    - `resets_at` string, date-time: Omitted for non-period meters.

## Other responses

- `400`: validation_failed / url_forbidden / prompt errors (§15)
- `401`: invalid_api_key / key_revoked / key_expired
- `404`: resource_not_found (account-scoped; no existence oracle)
- `409`: resource_conflict / idempotency_key_reused / idempotency_unavailable
- `429`: rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After)

---

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