---
title: "Check credits and recent charges"
method: GET
path: "/v1/usage"
---

# Check credits and recent charges

`GET /v1/usage`

## Request

- Base URL: `https://api.veezee.io`
- URL: `https://api.veezee.io/v1/usage`
- Auth: HTTP bearer

Check your balance, plan, limits, and the last 10 charges (receipt ids included). Costs 0 credits and is exempt from the per-minute rate limit, so call it first to check your budget before running data tools, and any time after. Works the same on a trial key, a paid key, or an OAuth-connected account. The response includes upgrade_url (give it to your human when credits or plan limits block you; purchases credit this account directly with no login) and manage_url (give it to your human to change or cancel a paid plan in the Stripe billing portal). Trial accounts also get a claim_url that attaches an email so the account can be recovered if the key is lost. Not for fetching platform data.

## Response `200`

usage envelope (schema_version 2)

- UsageEnvelope
  - `entity` 'usage', required
  - `platform` 'linkedin' | 'reddit' | 'x', nullable, required
  - `canonical_url` string, nullable, required
  - `data_as_of` string, nullable, required
  - `schema_version` '2', required
  - `common` object, required
    - `plan` 'trial' | 'payg' | 'flex' | 'production', required
    - `platforms` string[], required: Platforms this account's key may call. Grants are explicit; write to hello@veezee.io to enable more.
    - `balance_remaining` integer, required
    - `free_tier` object, nullable, required: Present on trial keys: the shared per-IP day budget this key actually spends (balance_remaining stays 0 on the free tier; other callers on the same IP draw from the same pool). Null on paid plans.
      - `credits_per_ip_day` integer, required
      - `used_today` integer, required
      - `remaining_today` integer, required
      - `resets` string, required: UTC midnight when the day budget resets. ISO 8601.
    - `realtime_ops_used` integer, required
    - `realtime_ops_limit` integer, nullable, required: Null means unlimited (paid plans).
    - `concurrent_limit` integer, required
    - `recent_receipts` object[], required: Up to the last 10 charges.
      - `receipt_id` string, required
      - `tool` string, required
      - `credits_charged` integer, required
      - `created_at` string, required
    - `claim_url` string, nullable, required: Present on trial accounts: open to attach an email so the account can be recovered if the key is lost.
    - `upgrade_url` string, required: Give this link to your human to add credits or upgrade; purchases credit THIS account with no login.
    - `manage_url` string, required: Give this link to your human to change or cancel a paid plan in the Stripe billing portal. Valid at least 24 hours; call get_usage again for a fresh one.
  - `platform_fields` object, required
  - `freshness` object, nullable, required
    - `source_retrieved_at` string, nullable, required: When the data was fetched from the source. ISO 8601.
    - `served_at` string, required
    - `cache_age_seconds` integer, nullable, required
    - `served_from_cache` boolean, required: True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are.
    - `freshness_requested` 'recent' | 'realtime', required
    - `freshness_served` 'recent' | 'realtime' | 'stale', required
  - `usage` object, required
    - `receipt_id` string, nullable, required
    - `credits_quoted` integer, required
    - `credits_charged` integer, required
    - `balance_remaining` integer, nullable, required
    - `free_tier_hint` string: Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key. Near the daily cap on unclaimed keys it also carries a claim link to relay to your human (claiming adds one-time credits).

## Other responses

- `400`: INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED
- `401`: UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED
- `402`: INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS
- `403`: NOT_ENTITLED | TRIAL_CAP_EXCEEDED
- `404`: NOT_FOUND
- `409`: IDEMPOTENCY_KEY_REUSED
- `413`: PAYLOAD_TOO_LARGE
- `429`: CONCURRENCY_LIMIT | RATE_LIMITED
- `500`: INTERNAL
- `502`: UPSTREAM_UNAVAILABLE
- `503`: BUDGET_EXHAUSTED

---

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