---
title: "Check usage and quota"
method: GET
path: "/v1/usage"
tags: ["Usage"]
---

# Check usage and quota

`GET /v1/usage`

Returns the current plan tier, billing period, spendable wallet,
daily free allowance, and rate limit for the authenticated account.

## Response `200`

Usage information

- UsageResponse
  - `tier` string, required — Current subscription tier, typically `free`, `pro`, or `enterprise`.
  - `plan_code` 'free' | 'pro' | 'enterprise', required — Normalized billing plan code.
  - `period_start` string, date, required — Billing period start date (YYYY-MM-DD).
  - `period_end` string, date, required — Billing period end date (YYYY-MM-DD).
  - `credits_limit` integer, required — Included monthly credits for the current tier.
  - `credits_used` integer, required — Credits used in the current billing period.
  - `credits_remaining` integer, required — Remaining spendable credits in the account wallet.
  - `wallet_balance` integer, required — Total spendable credits currently available.
  - `credit_breakdown` object, required
    - `included_remaining` integer, required — Remaining included subscription credits.
    - `bonus_remaining` integer, required — Remaining bonus credits such as signup or referral credits.
    - `paid_remaining` integer, required — Remaining purchased top-up credits.
  - `expiring_credits` object[], required — Credits that will expire soon, ordered by earliest expiry first.
    - `grant_type` string, required
    - `credits` integer, required
    - `expires_at` string, date-time, required
  - `rate_limit_per_sec` integer, required — Maximum requests per second for this tier.
  - `api_keys_active` integer, required — Number of active API keys.
  - `billing_hold` boolean, required — Whether the billing account is currently blocked pending review.
  - `daily_free_remaining` integer, required — Remaining free searches for the current UTC day.
  - `daily_free_limit` integer, required — Total free searches available per UTC day.

## Other responses

- `401` — Missing or invalid API key.
- `403` — Inactive API key or insufficient credits.
- `429` — Rate limit exceeded.
- `500` — Unexpected server error.

## Changes

- **2026-04-08** `6cccdc178a95` — 4 warning, 12 info
  - added the new `internal_error` enum value to the `error/code` response property for the response status `401`
  - added the new `internal_error` enum value to the `error/code` response property for the response status `403`
  - added the new `internal_error` enum value to the `error/code` response property for the response status `429`
  - added the new `internal_error` enum value to the `error/code` response property for the response status `500`
  - …12 more
- **2026-04-04** `503281cd9fb3` — 17 warning, 4 info
  - the optional response header `x-request-id` removed for the status `200`
  - the optional response header `x-request-id` removed for the status `401`
  - the optional response header `x-request-id` removed for the status `403`
  - the optional response header `x-request-id` removed for the status `429`
  - …17 more

[Change history](https://skmtc.dev/cerul-ai/apis/cerul-api/changes/v1/usage/get.md)

---

[API](https://skmtc.dev/cerul-ai/apis/cerul-api.md) · [All operations](https://skmtc.dev/cerul-ai/apis/cerul-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cerul-ai/cerul-api/revisions/6cccdc178a95/schema)