get_usage 0 credits

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.

Parameters#

No parameters.

REST#

GET /v1/usage · auth: required · metered: false

Request

curl "https://api.veezee.io/v1/usage" \
  -H "Authorization: Bearer $VEEZEE_API_KEY"

MCP#

tools/call

{
  "method": "tools/call",
  "params": {
    "name": "get_usage",
    "arguments": {}
  }
}

Input examples#

Balance check

{}

Output#

Returns a usage envelope. Full field list: /docs/fields#usage.

Errors#

REST returns application/problem+json; MCP returns the same content as an error result. message is written as the next-turn instruction.

Code	HTTP status	Retriable	Meaning
`INVALID_INPUT`	400	no	A parameter failed validation. Check param and message for what to fix.
`NOT_FOUND`	404	no	Nothing matches the given identifier or URL.
`UNAUTHORIZED`	401	no	Invalid, revoked, or unusable API key.
`NOT_ENTITLED`	403	no	This account is not enabled for the platform you called.
`INSUFFICIENT_CREDITS`	402	no	Your balance can't cover this call's quote. Check get_usage or add credits.
`QUOTE_EXCEEDS_MAX_CREDITS`	402	no	The call's quote is higher than the max_credits you set. Nothing was charged.
`IDEMPOTENCY_KEY_REQUIRED`	400	no	This is a metered call; send an Idempotency-Key header.
`IDEMPOTENCY_KEY_REUSED`	409	no	That Idempotency-Key was already used with different arguments. Use a new key for a new call.
`CONCURRENCY_LIMIT`	429	yes	Too many calls in flight for this key's plan. Wait for one to finish.
`RATE_LIMITED`	429	yes	Too many calls per minute for this key's plan. Back off and retry.
`TRIAL_CAP_EXCEEDED`	403	no	A trial-only limit was hit (concurrency, rate, search size, or realtime fetches).
`BUDGET_EXHAUSTED`	503	no	A configured spend budget has been used up.
`UPSTREAM_UNAVAILABLE`	502	yes	LinkedIn data wasn't reachable. Safe to retry.
`PAYLOAD_TOO_LARGE`	413	no	The request or response exceeded the size limit.
`INTERNAL`	500	yes	Something failed on our side. Safe to retry.
`AUTH_REQUIRED`	401	no
`KEY_REQUIRED`	401	no	No API key was sent. Mint one free at POST /v1/keys/mint and retry.

Errors a payment can fix: the offer fields

Errors a payment can fix add fields to the base error shape. INSUFFICIENT_CREDITS, TRIAL_CAP_EXCEEDED, and BUDGET_EXHAUSTED carry upgrade_url (a link to hand to your human) and offer, its machine-readable twin. RATE_LIMITED and CONCURRENCY_LIMIT carry both on trial accounts only, where a paid plan raises the limit.

Fields inside offer:

offer_version: currently 1.
reason: the error code that produced the offer.
currency: "usd".
recommended: the pack to lead with, currently flex.
packs: each pack's pack, mode, price_usd_cents, credits or credits_per_month, and when, a short label for when that pack fits.
rails: currently stripe_checkout.
checkout_url: the same account-bound link as upgrade_url.
resume: how to continue after payment, per code (next paragraph).
refund_policy: the refund terms in plain text.

After payment, follow resume: INSUFFICIENT_CREDITS retries the same call with the same Idempotency-Key; TRIAL_CAP_EXCEEDED and BUDGET_EXHAUSTED retry with a fresh key; the two limit codes clear on their own with back-off, payment only raises the limit. INSUFFICIENT_CREDITS also sets credits_required: the credits the failed call needed. The failed attempt charged nothing.