Rate Limits by Plan — Requests and Objects
Based on your plan, your key is limited to a number of requests per minute. Exceed it and you receive a 429 with a Retry-After header until the minute resets.
Request limits
- Lite plan: 10 requests per minute
- Base plan: 60 requests per minute
- Platform plan: 600 requests per minute
Object limits
There is no monthly object cap on any plan. Objects served are counted per day and reported in /account/usage for your own tracking. Each response counts as a minimum of 1 object.
How the counter works
The counter is atomic. The limit is enforced by the increment itself, so 60 simultaneous requests on a 10/min key serve exactly 10 — it cannot be raced open. A rejected request is still counted for the minute (so hammering is never free) but is never billed: usage billing is a separate meter charged only after a request is served.
Every response carries x-ratelimit-limit and x-ratelimit-remaining. Windows are fixed epoch minutes.
Strategies to avoid rate limiting
- Avoid frequent calls to endpoints whose data rarely changes (teams, players, stats) — cache them.
- Poll at the source cadence (~2 minutes), not faster.
- Use query params to focus on only the data you need.
- Check
/account/usage.
Response filtering notice
When your key's plan causes data to be filtered from a response (league scope, bookmaker cap, fair odds), the response carries a notice field saying what was withheld:
{
"success": true,
"data": [...],
"nextCursor": "afl_2026-09-12_brisbane_lions_vs_adelaide_crows",
"notice": "Response is missing 3 events and 15 bookmaker odds. Upgrade your API key to access all data from this query."
}Checking your rate limit usage
fetch("https://api.sockodds.com/v2/account/usage", { headers: { "X-Api-Key": "YOUR_TOKEN" } });{
"success": true,
"data": [
{
"keyID": "5fb8c85833e6dcf5",
"customerID": null,
"email": "you@example.com",
"isActive": true,
"tier": "base",
"rateLimits": {
"per-minute": {
"max-requests": 60,
"current-requests": 1,
"max-entities": null,
"current-entities": null
},
"per-day": {
"max-requests": null,
"current-requests": 12,
"max-entities": null,
"current-entities": 240
}
}
}
]
}