Plans and limits

What each plan allows, what each call costs in credits and what a limit looks like.

Updated

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.

PlanPriceCredits a monthRequests a minuteLeaguesHistoryOpening and closingStreamDerived endpoints
Developer (free)Free1,00010MLB, NFL, AFL, NRL, NBA, NBL and English Premier LeagueNoNoNoNo
StarterUS$39 a month or US$374.40 a year30,00060Every leagueYesNoNoNo
ProUS$99 a month or US$950.40 a year5,000,000300Every leagueYesYesYesYes
BusinessUS$249 a month or US$2,390.40 a year20,000,000600Every leagueYesYesYesYes

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.

CallCredits
/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=trueUnique markets returned in each event × regions, summed over the events
/v1/events/{id}/oddsUnique markets returned × regions
snapshots=opening,closing on either odds call (Pro and Business)5 × the odds cost
/v1/results1; 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}/odds1 per region; 5 per region with snapshots=
/v1/racing/races/{id}/history10
/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 data0

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=nba returns 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,tab for one game that returns 40 markets: 40 markets × 1 region (two bookmakers named) = 40 credits.
  • GET /v1/odds/history for one game, one market and bookmakers=sportsbet: 10 × 1 × 1 = 10 credits.
  • GET /v1/results?league=afl is 1 credit; with starts_after= it is 2.

Headers

Every response says where your month stands:

HeaderMeaning
x-credits-usedCredits used this month, including this call
x-credits-remainingCredits left this month (absent on a key that is not metered)
x-credits-lastWhat this call cost
x-credits-resetWhen 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-lastThe same three counts under the names other odds APIs use, so existing code reads them unchanged
x-credits-truncated1 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 429 with the title "Rate limit reached" and a Retry-After header in seconds. Wait that long, then retry.
  • Monthly credits. A call that costs more credits than you have left gets 429 with 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, and meta.notice says what was cut and charged.
  • Leagues. A request naming a league outside your plan gets 403 with 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 403 with 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,handicap costs 2 per region; markets=all costs every market in every event.
  • Name your regions or bookmakers. regions=au bills one region. Naming up to 10 bookmakers in bookmakers= 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 follow links.next; an empty page is free.
  • Use the stream on Pro. /v1/stream/odds charges 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-last while you build, and x-credits-remaining before a big job.
Need help?FAQ · Email support

Search across the SockOdds documentation and catalogue.