Skip to content
unzoi docs

GET /account

GET https://api.unzoi.com/account

This key's plan and usage.

Plan, per-minute rate, monthly quota and month-to-date usage from the durable counters, whether the key hard-caps, and how far back it may query. Equivalent to the `account_status` MCP tool.

Where you stand, as a body rather than as headers. Cheap, and worth calling once at startup so your client knows its own budget instead of discovering the limits by hitting them.

Response

Field Type Description
attribution string
hard_cap boolean Whether this key stops at its quota instead of billing overage.
history_days integer
metered_billing boolean
period_start integer
plan string
quota integer Included monthly requests; 0 = unlimited.
quota_remaining integer
rate_per_min integer
tenant string
usage_this_period integer

Reading it

  • usage_this_period comes from the durable counters, not from an in-memory tally, so every replica reports the same number and it matches the invoice.
  • quota of 0 means unlimited, not blocked. A handful of bespoke accounts carry it.
  • hard_cap decides what happens at the quota: true stops, false bills overage. Only the free tier hard-caps by default, because there is no card on file.
  • history_days of null means the full archive. Otherwise it is how far back you may query, enforced on every request — Archive depth.
  • period_start is the unix timestamp of the current quota month, so you can work out the reset without waiting for a 429.

Example

curl -s https://api.unzoi.com/account -H "x-api-key: $UNZOI_KEY"
{
  "tenant": "acme",
  "plan": "build",
  "rate_per_min": 600,
  "usage_this_period": 12483,
  "quota": 50000,
  "quota_remaining": 37517,
  "period_start": 1785542400,
  "hard_cap": false,
  "history_days": 365,
  "metered_billing": true,
  "attribution": "Data derived from the GDELT Project (https://www.gdeltproject.org/)."
}

An agent can ask the same question over MCP with account_status, which returns the same figures.