Plans and limits
What each plan allows, what each call costs in credits and what a limit looks like.
Every key belongs to a plan. A plan sets your monthly credits, how many requests you can make a minute, which leagues you can read and whether you can read recorded history, opening and closing prices, the stream and the derived endpoints. Every plan reads every bookmaker we deliver except bet365, which is on Pro and Business only.
| Plan | Price | Credits a month | Requests a minute | Leagues | History | Opening and closing | Stream | Derived endpoints |
|---|---|---|---|---|---|---|---|---|
| Developer (free) | Free | 1,000 | 10 | MLB, NFL, AFL, NRL, NBA, NBL and English Premier League | No | No | No | No |
| Starter | US$39 a month or US$374.40 a year | 30,000 | 60 | Every league | Yes | No | No | No |
| Pro | US$99 a month or US$950.40 a year | 5,000,000 | 300 | Every league | Yes | Yes | Yes | Yes |
| Business | US$249 a month or US$2,390.40 a year | 20,000,000 | 600 | Every league | Yes | Yes | Yes | Yes |
Platform plans for bigger volume are on enquiry. A free Pro trial lasts 7 days or 1,000 credits, whichever comes first. Prices and billing are on the pricing page. If you subscribed before 18 November 2026 you keep your plan, or move to the new price if it is lower. Existing Rookie keys keep every bookmaker, every league, recorded history and 5,000,000 credits a month.
How credits are counted
Usage is counted in credits. An odds call costs one credit for each market it returns in each region it is billed for. Lists that carry no prices are free, and so is any call that returns no data.
| Call | Credits |
|---|---|
/v1/sports, /leagues, /bookmakers, /markets, /teams, /players, /events, /events/{id}, /events/lookup, /racing/races, /racing/races/{id} | Free (the rate limit still applies) |
/v1/odds for a league, featured markets (the default) | Featured markets returned × regions, once per page of up to 25 events |
/v1/odds with any other market, markets=all or alternates=true | Unique markets returned in each event × regions, summed over the events |
/v1/events/{id}/odds | Unique markets returned × regions |
snapshots=opening,closing on either odds call (Pro and Business) | 5 × the odds cost |
/v1/results | 1; 2 with starts_after or starts_before |
/v1/odds/history (paid plans) | 10 × unique markets returned × regions |
/v1/history/files (the list) | 1 |
/v1/history/files/{league}/{day} (one league-day file) | 100 |
/v1/racing/races/{id}/odds | 1 per region; 5 per region with snapshots= |
/v1/racing/races/{id}/history | 10 |
/v1/stream/odds (Pro and Business) | Each update delivered costs what the same odds call costs; unchanged ticks are free |
| Derived endpoints: arbitrage, +EV, middles, low hold, closing line value, steam moves (Pro and Business) | 10 a call |
| Fair odds (Pinnacle devig, Pro and Business) | 5 a call |
| Any call that returns no data | 0 |
Featured markets. With no markets=, an odds call returns the featured markets only: winner, result, handicap, total_points, total_goals, total_runs, total_games, total_rounds, total_sets and total_maps (each sport has its own total). On /v1/odds they are charged once per page of up to 25 events, however many events come back. Ask for markets=all to get every market, charged per event.
Regions billed. Regions are the catalogue's own keys (au, nz, us, ca, uk, ie, eu and intl). A call naming bookmakers in bookmakers= is billed one region for every 10 bookmakers named. Otherwise it is billed the number of regions named in regions=. With neither, it is billed one region for every 10 bookmakers returned.
Credits reset at 00:00 UTC on the first of each month and do not carry over. Your account shows the month so far, day by day.
Worked examples
GET /v1/odds?league=nbareturns the featured markets (winner, handicap,total_points) for every listed game, with prices from 12 bookmakers: 3 markets × 2 regions (12 bookmakers is two groups of ten) = 6 credits, whether 5 games come back or 25.- The same call with
regions=au: 3 markets × 1 region = 3 credits. GET /v1/events/{id}/odds?markets=all&bookmakers=sportsbet,tabfor one game that returns 40 markets: 40 markets × 1 region (two bookmakers named) = 40 credits.GET /v1/odds/historyfor one game, one market andbookmakers=sportsbet: 10 × 1 × 1 = 10 credits.GET /v1/results?league=aflis 1 credit; withstarts_after=it is 2.
Headers
Every response says where your month stands:
| Header | Meaning |
|---|---|
x-credits-used | Credits used this month, including this call |
x-credits-remaining | Credits left this month (absent on a key that is not metered) |
x-credits-last | What this call cost |
x-credits-reset | When the allowance starts again, as an ISO time (00:00 UTC on the first of next month) |
x-requests-used, x-requests-remaining, x-requests-last | The same three counts under the names other odds APIs use, so existing code reads them unchanged |
x-credits-truncated | 1 when a first call of the month was cut down to fit the allowance (see below) |
What happens at a limit
- Requests a minute. The request after your limit gets
429with the title "Rate limit reached" and aRetry-Afterheader in seconds. Wait that long, then retry. - Monthly credits. A call that costs more credits than you have left gets
429with the title "Monthly allowance reached" and nothing is charged. Free lists keep answering. The allowance starts again at 00:00 UTC on the first of next month, or straight away on a larger plan. - The first call of the month is never refused. If it alone costs more than the whole allowance, it is served cut down: events are dropped from the end until it fits, the response carries
x-credits-truncated: 1, andmeta.noticesays what was cut and charged. - Leagues. A request naming a league outside your plan gets
403with the title "Plan restriction". - History, snapshots, stream and derived endpoints. Recorded history needs a paid plan; opening and closing prices, the stream and the derived endpoints need Pro or Business. Other plans get
403with the title "Plan restriction".
A refused call is application/problem+json, with the usual type and instance (see Errors) and four fields of its own:
{
"title": "Monthly allowance reached",
"status": 429,
"detail": "This call costs 40 credits and 12 of your 30000 are left this month. The allowance resets at 2026-12-01T00:00:00.000Z. Ask for fewer markets, regions or bookmakers, or choose a larger plan.",
"credits_needed": 40,
"credits_remaining": 12,
"credits_allowance": 30000,
"credits_reset": "2026-12-01T00:00:00.000Z"
}
A Developer key asking for a league outside the free plan:
curl -sS "https://api.sockodds.com/v1/odds?league=nhl&limit=1" \
-H "Authorization: Bearer $SOCKODDS_API_KEY"const response = await fetch("https://api.sockodds.com/v1/odds?league=nhl&limit=1", {
headers: { Authorization: `Bearer ${process.env.SOCKODDS_API_KEY}` },
});
console.log(JSON.stringify(await response.json(), null, 2));import json, os, urllib.error, urllib.request
request = urllib.request.Request(
"https://api.sockodds.com/v1/odds?league=nhl&limit=1",
headers={"Authorization": "Bearer " + os.environ["SOCKODDS_API_KEY"]},
)
try:
with urllib.request.urlopen(request) as response:
print(json.dumps(json.load(response), indent=2))
except urllib.error.HTTPError as error:
print(json.dumps(json.load(error), indent=2))Example response · sample prices, not real odds
{
"type": "https://api.sockodds.com/problems/403",
"title": "Plan restriction",
"status": 403,
"detail": "This league is not in your plan.",
"instance": "/v1/odds?league=nhl&limit=1"
}Error responses follow Errors.
Keep calls small
- Name your markets.
markets=winner,handicapcosts 2 per region;markets=allcosts every market in every event. - Name your regions or bookmakers.
regions=aubills one region. Naming up to 10 bookmakers inbookmakers=bills one region however many regions they span. - Ask for a league, not one event at a time. Featured markets for a whole league cost the same as for one event. Page with
limit=and followlinks.next; an empty page is free. - Use the stream on Pro.
/v1/stream/oddscharges only for updates that change something; unchanged ticks are free, so it is cheaper than polling. - Keep history windows tight. History costs ten times the live price per market. Ask for the markets and bookmakers you need, and use the daily files (100 credits a league-day) for bulk history instead of many small windows.
- Watch the headers. Read
x-credits-lastwhile you build, andx-credits-remainingbefore a big job.