Metering rules
What a plan limits, how it is counted, and how a refusal reads. These are the rules the API enforces, and GET /v1/usage reports where you stand against them.
What counts as a MIC
- A MIC counts once you request it. The charge counts the venues you asked for, even when several MICs are answered by the same calendar internally (through the operating MIC or the country). Which venues share a calendar is Diurn's business and does not affect billing.
- Product schedules are included with their MIC. Taking a MIC as a slot gives every product schedule under it; a product query never uses another slot.
- Invalid MICs, errors and 4xx responses do not use a slot.
MIC caps
- Daily cap: the number of unique MICs requested in any rolling 24 hours. A rolling window rather than a reset at UTC midnight, which would be arbitrary for anyone outside the US.
- Monthly cap: the number of unique MICs requested in any rolling 30 days. It is set a little above the daily cap, so you can swap a market now and then but not rotate through a different set each day.
- Asking again for a MIC already in a window is free, and keeps it in the window from that request.
- Any endpoint returning data for a MIC counts toward both caps, including
/status,/next-openand/next-close.
Forward horizon and history depth
- Both are measured from the date of the request (UTC):
from ≥ today − historyandto ≤ today + horizon. The horizon rolls, so its length does not depend on when in the year you ask. - A request outside the plan's window is refused, not trimmed: a trimmed answer looks like data that does not exist. The refusal says which dates are allowed.
Free and unmetered
GET /v1/venues and GET /v1/venues/{mic} (the ISO 10383 records), GET /v1/usage, GET /health, GET /openapi.json, and error responses. Every other endpoint needs a key.
Request rates
Separate from the caps, and only there to protect the service: requests a minute, per key. The multi-venue endpoints have a tenth of it.
| Free | 10 |
| Starter | 60 |
| Plus | 120 |
| Pro | 600 |
| Enterprise | 3,000 |
On every metered response
Diurn-MICs-DayandDiurn-MICs-Month: used/limit in the rolling windows, e.g.3/5(3/allon an uncapped plan).RateLimit-Limit,RateLimit-Remaining,RateLimit-Reset: the request rate.
When a limit is reached
The refusal states the limit, the usage and when it eases, in a form a script or an agent can act on rather than retry. A MIC cap and the request rate answer 429; dates outside the window, an endpoint or provenance the plan does not include answer 403; no key, or an inactive one, 401.
{
"error": "mic_cap_exceeded",
"message": "XHKG would be unique MIC number 6 in 24 hours; the Starter plan allows 5",
"limit": { "kind": "mics_day", "used": 5, "max": 5 },
"mics_in_use": ["ARCX", "XLON", "XNAS", "XNYS", "XTKS"],
"resets_at": "2026-11-10T14:02:11Z",
"upgrade": "https://diurn.io/pricing"
}The same shape carries mics_month and rate; an out_of_window refusal carries the allowed from and to instead.
GET /v1/usage
{
"plan": "starter",
"mics_day": { "used": 3, "max": 5, "mics": ["XLON", "XNAS", "XNYS"],
"window": "rolling_24h", "resets_at": "2026-11-10T09:12:40Z" },
"mics_month": { "used": 6, "max": 8, "window": "rolling_30d",
"resets_at": "2026-11-21T16:03:02Z" },
"venue_days": null,
"horizon": { "from": "2021-11-09", "to": "2027-11-09" },
"rate": { "per_minute": 60, "bulk_per_minute": 6 }
}Plans and prices are on the pricing page.