Usage API — credit balance and rate-limit windows

`GET /v1/usage`

Your current credit balance, the individual credit buckets behind it, and usage per rate-limit window. This call is free — it costs no credits and does not count against your limits.

Request

No parameters — only the X-API-Key header.

Examples

curl -H "X-API-Key: gi_live_..." "https://geoinsight.dev/v1/usage"

import requests

r = requests.get("https://geoinsight.dev/v1/usage", headers={"X-API-Key": "gi_live_..."})
print(r.json()["balance"])

const res = await fetch("https://geoinsight.dev/v1/usage", {
  headers: { "X-API-Key": "gi_live_..." },
});
console.log((await res.json()).balance);

Response

{
  "balance": 998000,
  "buckets": [
{ "tier": "pro",  "remaining": 996000, "expires_at": "2027-08-04T12:00:00+00:00" },
{ "tier": "free", "remaining": 2000,   "expires_at": null }
  ],
  "windows": {
"hour": { "name": "hour", "limit": 2000,  "used": 3, "remaining": 1997,  "resetsAt": "2026-08-04T13:00:00.000000Z" },
"day":  { "name": "day",  "limit": 20000, "used": 3, "remaining": 19997, "resetsAt": "…" },
"week": { "name": "week", "limit": 60000, "used": 3, "remaining": 59997, "resetsAt": "…" }
  }
}

Field	Type	Unit	Description
`balance`	integer	credits	Total credits left. Always equals the sum of buckets[].remaining. When this reaches 0 every billable call returns 402.
`buckets`	array	—	Active credit buckets only; expired ones are omitted. Credits are spent from the bucket expiring soonest first.
`buckets[].tier`	string	—	Tier key the bucket came from (free, starter, pro, business, scale, enterprise). Your highest purchased tier sets the rate-limit windows.
`buckets[].remaining`	integer	credits	Credits left in this bucket.
`buckets[].expires_at`	string	ISO 8601	When the bucket expires; null means the credits never expire. Purchased credits are valid 12 months.
`windows`	object	—	Rate-limit windows of your active tier, keyed hour / day / week. Empty {} when you hold no credits, or when window data is momentarily unavailable — in that case requests are still let through.
`windows.<window>.name`	string	—	Window name, matching its key: hour, day or week.
`windows.<window>.limit`	integer	units	Maximum units allowed inside the window.
`windows.<window>.used`	integer	units	Units already consumed in the current window.
`windows.<window>.remaining`	integer	units	Units still available before this window returns 429.
`windows.<window>.resetsAt`	string	ISO 8601	When the window rolls over and used returns to 0. Note this key is camelCase, unlike expires_at above.
`install`	object	—	Present only for install-authenticated requests. This one device's daily budget — separate from the account balance and windows above.
`install.daily_limit`	integer\|null	credits	Per-install cap set on the app, or null when the app has none. When null, the device is bounded only by the account balance.
`install.used`	integer	credits	Credits this install has spent so far in the current UTC day. Free calls like this one do not count.
`install.remaining`	integer\|null	credits	daily_limit minus used, floored at 0. null when there is no per-install limit — so 0 always means exhausted, never unlimited.
`install.resets_at`	string	ISO 8601	Next UTC midnight, when used returns to 0. snake_case, matching the block, unlike the windows above.