# 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](https://sockodds.com/contact-us/?topic=platform). A free Pro trial lasts 7 days or 1,000 credits, whichever comes first. Prices and billing are on the [pricing page](https://sockodds.com/pricing/). 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](https://sockodds.com/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:

| 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 `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](https://sockodds.com/docs/errors/)) and four fields of its own:

```json
{
  "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:

```bash
curl -sS "https://api.sockodds.com/v1/odds?league=nhl&limit=1" \
  -H "Authorization: Bearer $SOCKODDS_API_KEY"
```

```javascript
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));
```

```python
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):

```json
{
  "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](https://sockodds.com/docs/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.
