Quota & rate limits

One bill, per organization

Platform usage is metered per organization, not per key — every key your org holds draws down one shared monthly budget and they rate-limit together. One key, one bill: AI, maps, and design all debit the same org meter.

The budget resets on a monthly calendar cycle.

What your plan includes

Your organization's plan sets both what a key can reach and the shared monthly token budget:

Plan	API surface	Monthly API tokens	Monthly map loads
Free	Basemaps only — a publishable key with the maps scope and the tile product	n/a (no ai scope)	50,000
Pro	full platform (ai, maps, design; browser + server keys)	5,000,000	50,000
Enterprise	full platform	50,000,000	50,000

Every plan carries the same map-loads allowance — plans differentiate on tokens, API surface, and features. Enterprise volumes above the allowance are granted as per-organization raises, not a bigger plan rung.

Free-plan keys serve basemap embeds, which are metered as map loads rather than tokens. To reach the AI and design surfaces, upgrade at kaleidr.com/billing. Plan changes apply to your existing keys within a few minutes; no re-mint needed — though a key minted on Free is re-scoped when it's next rotated.

The 429 body

A request that would exceed the cap returns 429 Too Many Requests with a body describing the meter and limit (abbreviated — the full detail also carries used, remaining, reset_at, and reset_in_seconds):

{ "detail": { "meter": "b2b.tokens", "tier": "…", "limit": 5000000 } }

For streaming endpoints the cap is also surfaced mid-stream as a quota SSE event so your UI can react before the stream ends.

Going over the allowance

What happens above your allowance depends on your plan, and the two cases are deliberately different.

Free stops at the allowance. A request that would exceed it returns 429 map_load_quota_exceeded. That boundary is the free basemap product.

Pro and Enterprise keep serving. An overage on a paying account is a billing conversation, not an outage, so your embeds do not go dark mid-month — we record the overage and follow up.

That grace is not unlimited. Paid plans stop at five times the allowance with a 429 map_load_hard_stop. No honest embed reaches it; the ceiling exists so that a publishable key someone copied out of your page source cannot run up an unbounded bill in your name. Purchased map-load packs raise the allowance, and the ceiling scales with it.

If you are hitting the soft band regularly, you need more allowance rather than a workaround — contact us.

Basemap access

The designed basemaps are part of your Kaleidr account, not a standalone public tile API: <kaleidr-map> embeds and the SDK authorize through your publishable key (maps scope), and every map load — a shared-map open, a published/embedded view, or an SDK basemap session, roughly 20 tile requests — draws from the shared monthly allowance described above. Direct third-party use of tile.kaleidr.com outside a keyed embed is blocked with a 429 and this body:

{
  "error": "tile_access_restricted",
  "message": "Direct access to tile.kaleidr.com requires a Kaleidr account. Kaleidr-hosted maps and embeds are unaffected — see the docs.",
  "docs": "https://docs.kaleidr.com/platform-api/quota-and-rate-limits"
}

If you need more than the allowance, contact us — higher volumes are granted per organization, and Enterprise can serve from an independent CDN.

Rate limits and concurrency

Two limits sit in front of the quota, and both shed excess with a 429 rather than queueing it:

• Requests per minute, per key — a sliding 60-second window. Each key carries its own rate.
• Concurrent streams, per organization — simultaneous streaming requests across all of your org's keys.

Retry with backoff. A 429 here means "too fast right now"; a 429 carrying a meter in its body means you've hit the monthly cap (above).

Handling it

• Treat 429 as "slow down / upgrade," not "broken." Back off and retry.
• Surface the mid-stream quota event in your UI (remaining budget).
• See Errors for the full status table.