GET /account

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

This key's plan and usage.

Plan, credits a minute, the monthly allocation and credits used this month, whether the key stops at its allocation, and how far back it may query. Free: costs 0 credits. Equivalent to the `account_status` MCP tool. Free: 0 credits.

Where you stand, as a body rather than as headers. Free — it costs 0 credits — 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	Required source attribution for any use of these results.
credits_charged	integer	What reading this cost: always 0.
credits_limit	integer	Credits included this calendar month; 0 = unlimited.
credits_per_minute	integer	Credits a minute the plan allows.
credits_remaining	integer	Credits left this month; null when unlimited.
credits_reset_secs	integer	Seconds until the monthly allocation renews.
credits_used	integer	Credits charged so far this month.
hard_cap	boolean	Whether this key stops at its allocation instead of billing overage.
history_days	integer	How far back this plan may query; null = the full archive.
metered_billing	boolean	Whether overage is billed rather than capped.
period_start	integer	Unix timestamp the current period began (the start of this month, UTC).
plan	string	Plan id, e.g. free, build.
tenant	string	The tenant this key belongs to.

Reading it

credits_used is the durable counters plus this replica's charged calls, so every replica reports the same number and it matches the invoice. It counts credits: a plain search adds 1, and a call that made the index do more adds what it reported.
credits_limit of 0 means unlimited, not blocked, and credits_remaining is then null. A handful of bespoke accounts carry it.
hard_cap decides what happens at the allocation: true refuses a call whose worst case the credits left cannot cover, false bills overage. Only the free tier hard-caps by default, because there is no card on file.
credits_per_minute is the per-minute limit, in the same credits.
history_days of null means the full archive. Otherwise it is how far back you may query, enforced on every request — Archive depth.
credits_reset_secs is how long until the allocation renews, and period_start the unix timestamp the current month began.

Example

curl -s https://api.unzoi.com/account -H "x-api-key: $UNZOI_KEY"

{
  "tenant": "acme",
  "plan": "build",
  "credits_per_minute": 600,
  "credits_limit": 50000,
  "credits_used": 12483,
  "credits_remaining": 37517,
  "credits_reset_secs": 394200,
  "period_start": 1785542400,
  "hard_cap": false,
  "credits_charged": 0,
  "history_days": 365,
  "metered_billing": true,
  "attribution": "Data derived from the GDELT Project (https://www.gdeltproject.org/)."
}

What a call cost

This endpoint says where you stand; every response says what it cost. A priced answer carries credits_charged, and every authenticated REST response carries the figure as x-credits-charged — 0 on this one. Watch the header to track spend between calls here.

curl -s -D - -o /dev/null -G "https://api.unzoi.com/stories" -H "x-api-key: $UNZOI_KEY" \
  --data-urlencode "entity_id=organization:asml" \
  --data-urlencode "from=2026-08-01" | grep -iE '^x-credits-(charged|used):'

x-credits-charged: 2
x-credits-used: 12485

Two credits: the stories page, and the lookup that resolved the id. Add estimate=true to see that before running it. Credits and overage lists what each kind of call costs.

An agent can ask the same question over MCP with account_status, which is free too and adds calls_this_session and credits_this_session. Over MCP there are no headers; each tool result carries credits_charged instead.