Credits

A credit is a unit of data delivered, not a unit of time or of requests. The rule for the one variable endpoint is:

cost = max(1, ceil(rows_returned / 100))

Every other billable route is a flat 1. Everything else is 0. Three consequences worth holding on to:

• You are billed for what arrived, not for what you asked for. A query matching 40 rows costs 1 credit whether you scoped it tightly or got lucky.
• Errors are free. Credits are debited after a successful response exists and its row count is known. A 4xx or 5xx costs nothing — including too_many_rows, which is decided by a count before any data is read.
• Every request rounds up separately. Two requests of 60 rows cost 2 credits; one request of 120 rows costs 2 as well. The rounding only starts to matter when you chunk aggressively — see the third worked example below.

New accounts receive 2,000 credits — about 200,000 rows — at email verification, not at signup. After that, credits come from a one-off pack; nothing renews and no card is stored. Prices are on the pricing page.

You never have to guess. Two free moves tell you the size of a pull in advance.

"coverage": { "n_countries": 213, "yr_min": 2000, "yr_max": 2024, "latest_year": 2024 }

213 countries × 25 years ≈ 5,325 rows  →  ceil(5325 / 100) = 54 credits

# How many rows before you spend anything: ask for one country, read meta.count.
curl -sS "https://api.worldgovdata.com/v1/data?indicator=wdi.gdp_per_capita_ppp&countries=IND" \
  -H "Authorization: Bearer $WGD_API_KEY" | jq '.meta.count'

Every metered response tells you what it cost and what is left. There is no reason to poll a balance endpoint on a schedule — the answer is already attached to the work you are doing.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: private, no-store
X-Request-Id: 0f3a91c4e2b7
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1785315600
X-Credits-Charged: 2
X-Credits-Remaining: 24998

• Both headers are absent on a request that was never metered — an anonymous call to a free route, for instance.
• X-Credits-Charged: 0 on a 4xx or 5xx is a promise, not a rounding: failed requests genuinely cost nothing.
• Log X-Credits-Remaining from your batch jobs and alert on it falling below a day of headroom. It is the cheapest budget monitor available and it is free.

We never serve on credit. If your balance is below what a request needs, it is refused before the query runs — so an over-budget request costs nothing and leaves nothing half-done.

HTTP/1.1 402 Payment Required

{
  "error": {
    "code": "insufficient_credits",
    "message": "This request needs 1 credit and your balance is 0.",
    "required": 1,
    "balance": 0,
    "top_up_url": "https://worldgovdata.com/account/billing"
  }
}

The body is deliberately actionable. required is what this request needed, balance is what you hold, and top_up_url is where to fix it. A client that gets a bare 402 can only guess whether it is one credit short or a hundred thousand.

• Not a licence. Credits buy delivery, not rights. An indicator whose licence forbids redistribution returns 403 display_only at any balance. See Licensing.
• Not a rate limit. The two ceilings are independent: a full balance does not raise your requests-per-minute, and hitting a 429 does not cost you anything. See Rate limits.
• Not perishable. Credits do not expire, do not reset monthly and are not use-it-or-lose-it.
• Not charged to the portal. Browsing worldgovdata.com in a browser never touches your balance. Only calls you make with your own key do.