Developer reference

Odds Data API

A single gateway onto our sports odds feed. Bring your own API key, call any endpoint below directly, and we handle connection management and consistent error handling so your integration talks to one predictable API surface.

Base URL

__BASE_URL__

Replace with wherever this API is deployed. Every path below is relative to it.

Authentication

Pass your API key as apiKey on every request.

Response format

Every endpoint returns a plain JSON body with a standard HTTP status code — nothing reshaped, nothing renamed.

Latency

Responses typically return in well under a second, with only a few ms of overhead added by us.

Quick reference

13 endpoints

Every route this API exposes, at a glance. Click a path to jump to its full parameter list and example response.

Method	Endpoint	Description	Usage
GET	/api/languages	Supported language codes	Billable
GET	/api/sports	Supported sports	Billable
GET	/api/bookmakers	Supported bookmakers	Billable
GET	/api/tournaments	Tournaments/leagues for a sport	Billable
GET	/api/fixtures	List fixtures, filterable	Billable
GET	/api/fixture	Single fixture by ID	Billable
GET	/api/participants	Team/player names for a sport	Billable
GET	/api/odds	Live odds for one fixture	Billable
GET	/api/odds-by-tournaments	Live odds across tournaments	Billable
GET	/api/historical-odds	Odds price history	Free
GET	/api/markets	Available betting markets	Billable
GET	/api/settlements	Settled outcome results	Billable
GET	/api/scores	Live/final scores	Billable

Reference data

4 endpoints

Static lookup data — languages, sports, bookmakers, and tournaments — used to build queries against the fixtures and odds endpoints.

GET /api/languages Billable

Lists every language code accepted by the language parameter on other endpoints.

Query parameters

None.

Request

curl "__BASE_URL__/api/languages?apiKey=YOUR_API_KEY"

Response 200 OK

[
  { "a2": "en", "name": "English" },
  { "a2": "de", "name": "German" }
]

GET /api/sports Billable

Lists every sport available, with the numeric sportId used throughout the rest of the API.

Query parameters

Name	Type	Required	Description
language	string	Optional	Language for sportName in the response.

Request

curl "__BASE_URL__/api/sports?apiKey=YOUR_API_KEY"

Response 200 OK

[
  { "sportId": 10, "slug": "soccer", "sportName": "Soccer" },
  { "sportId": 11, "slug": "basketball", "sportName": "Basketball" }
]

GET /api/bookmakers Billable

Lists every bookmaker whose odds this feed carries, with the slug used to filter the odds endpoints.

Query parameters

None.

Request

curl "__BASE_URL__/api/bookmakers?apiKey=YOUR_API_KEY"

Response 200 OK

[
  { "bookmakerName": "Pinnacle", "slug": "pinnacle", "liveOdds": true, "cloneOf": null }
]

GET /api/tournaments Billable

Lists tournaments/leagues for a given sport, with fixture counts.

Query parameters

Name	Type	Required	Description
sportId	number	Required	Sport ID from /api/sports.
language	string (a2)	Optional · default en	Language for tournament/category names.

Request

curl "__BASE_URL__/api/tournaments?sportId=10&apiKey=YOUR_API_KEY"

Response 200 OK

[
  {
    "tournamentId": 8,
    "tournamentSlug": "laliga",
    "tournamentName": "LaLiga",
    "categoryName": "Spain",
    "futureFixtures": 300
  }
]

Fixtures & events

3 endpoints

Match/event data — scheduling, participants, and status — independent of odds pricing.

GET /api/fixtures Billable

Lists fixtures, filterable by sport, tournament, participant, date range, and odds availability.

Query parameters

Name	Type	Required	Description
sportId	number	Optional	Filter to one sport.
tournamentId	number	Optional	Filter to one tournament/league.
participantId	number	Optional	Filter to fixtures involving one team/player.
from	string (ISO 8601)	Optional	Only fixtures starting on/after this timestamp.
to	string (ISO 8601)	Optional	Only fixtures starting on/before this timestamp.
statusId	number	Optional	Filter by event status (0–3).
hasOdds	boolean	Optional	Only fixtures that currently have odds.
bookmakers	string	Optional	Comma-separated bookmaker slugs to check odds against.
language	string (a2)	Optional · default en	Language for names.

Request

curl "__BASE_URL__/api/fixtures?sportId=10&tournamentId=8&hasOdds=true&from=2026-04-13T00:00:00Z&apiKey=YOUR_API_KEY"

Response 200 OK

[
  {
    "fixtureId": "id1000001761301153",
    "participant1Name": "Liverpool FC",
    "participant2Name": "Manchester United",
    "sportId": 10,
    "tournamentId": 17,
    "tournamentName": "Premier League",
    "statusId": 0,
    "statusName": "Pre-Game",
    "hasOdds": true,
    "startTime": "2026-04-13T19:00:00.000Z"
  }
]

GET /api/fixture Billable

Returns a single fixture by ID — the same shape as one entry from /api/fixtures.

Query parameters

Name	Type	Required	Description
fixtureId	string	Required	Fixture ID, e.g. id1000001761301153.
language	string (a2)	Optional · default en	Language for names.

Request

curl "__BASE_URL__/api/fixture?fixtureId=id1000001761301153&apiKey=YOUR_API_KEY"

GET /api/participants Billable

Returns team/player names for a sport, keyed by participant ID.

Query parameters

Name	Type	Required	Description
sportId	number	Required	Sport ID from /api/sports.
language	string (a2)	Optional · default en	Language for names, where available.

Request

curl "__BASE_URL__/api/participants?sportId=11&apiKey=YOUR_API_KEY"

Response 200 OK

{
  "3409": "Chicago Bulls",
  "3410": "Milwaukee Bucks"
}

Odds

4 endpoints

Live and historical pricing, plus the market catalog those prices are keyed against.

GET /api/odds Billable

Current odds for a single fixture, broken down by bookmaker, market, and outcome.

Query parameters

Name	Type	Required	Description
fixtureId	string	Required	Fixture to fetch odds for.
bookmakers	string	Optional · default all	Comma-separated bookmaker slugs.
oddsFormat	string	Optional	One of fractional, decimal, american.
verbosity	number	Optional	Higher values return more detail per outcome.
language	string	Optional	Language for translated labels.

Request

curl "__BASE_URL__/api/odds?fixtureId=id1000003969653792&bookmakers=pinnacle&oddsFormat=decimal&apiKey=YOUR_API_KEY"

Response 200 OK (trimmed)

{
  "fixtureId": "id1000003969653792",
  "participant1Name": "FC Fredericia",
  "participant2Name": "Vejle BK",
  "hasOdds": true,
  "startTime": "2026-04-13T17:00:00.000Z",
  "bookmakerOdds": {
    "pinnacle": {
      "suspended": false,
      "markets": {
        "10286": {
          "marketActive": true,
          "outcomes": { "…": "price, limit, priceAmerican, priceFractional per outcome" }
        }
      }
    }
  }
}

GET /api/odds-by-tournaments Billable

Current odds across every fixture in one or more tournaments — the same per-fixture shape as /api/odds, batched.

Query parameters

Name	Type	Required	Description
tournamentIds	string	Required	Comma-separated tournament IDs.
bookmakers	string	Optional · default all	Comma-separated bookmaker slugs.
oddsFormat	string	Optional	One of decimal, american.
verbosity	number	Optional	Higher values return more detail per outcome.
language	string	Optional · default en	Language for translated labels.

Request

curl "__BASE_URL__/api/odds-by-tournaments?tournamentIds=17,8&bookmaker=pinnacle&oddsFormat=decimal&apiKey=YOUR_API_KEY"

GET /api/historical-odds Free

Price history for a fixture's odds — every recorded change, not just the current price. Never counts against quota.

Query parameters

Name	Type	Required	Description
fixtureId	string	Required	Fixture to fetch odds history for.
bookmakers	string	Required	Comma-separated bookmaker slugs — max 3.
id	number	Optional	Filter to one historical entry.
playerId	number	Optional	Filter to one player prop.
outcomeId	number	Optional	Filter to one outcome.
active	boolean	Optional	Filter to currently active/inactive price entries.

Request

curl "__BASE_URL__/api/historical-odds?fixtureId=id1000000758265379&bookmakers=pinnacle&apiKey=YOUR_API_KEY"

Response 200 OK (trimmed)

{
  "fixtureId": "id1000000758265379",
  "bookmakers": {
    "pinnacle": { "markets": { "101": { "outcomes": { "101": { "players": { "0": [
      { "createdAt": "2025-04-16T21:12:10.506Z", "price": 9.11, "active": false },
      { "createdAt": "2025-04-16T20:50:58.321Z", "price": 9.11, "active": true }
    ] } } } } } }
  }
}

GET /api/markets Billable

Lists every betting market and its possible outcomes — the catalog that bookmakerOdds.*.markets keys reference.

Query parameters

Name	Type	Required	Description
language	string (a2)	Optional · default en	Language for market/outcome names.

Request

curl "__BASE_URL__/api/markets?apiKey=YOUR_API_KEY"

Response 200 OK

[
  {
    "marketId": 101,
    "marketName": "Full Time Result",
    "marketType": "1x2",
    "outcomes": [
      { "outcomeId": 101, "outcomeName": "1" },
      { "outcomeId": 102, "outcomeName": "X" }
    ]
  }
]

Results

2 endpoints

What happened — settled outcomes and live/final scores.

GET /api/settlements Billable

Settled result (win/lose/push) for every outcome on a fixture.

Query parameters

Name	Type	Required	Description
fixtureId	string	Required	Fixture to fetch settlement results for.
playerId	number	Optional	Filter to one player prop.
outcomeId	number	Optional	Filter to one outcome.

Request

curl "__BASE_URL__/api/settlements?fixtureId=id1000000761280685&apiKey=YOUR_API_KEY"

Response 200 OK

{
  "fixtureId": "id1000000761280685",
  "markets": {
    "101": { "outcomes": {
      "101": { "players": { "0": { "result": "WIN" } } },
      "102": { "players": { "0": { "result": "LOSE" } } }
    } }
  }
}

GET /api/scores Billable

Score by period (e.g. per set, per quarter) for a fixture, live or final.

Query parameters

Name	Type	Required	Description
fixtureId	string	Required	Fixture to fetch scores for.

Request

curl "__BASE_URL__/api/scores?fixtureId=id65236323277832&apiKey=YOUR_API_KEY"

Response 200 OK

{
  "fixtureId": "id65236323277832",
  "scores": {
    "0": { "participant1Score": 0, "participant2Score": 2 },
    "1": { "participant1Score": 3, "participant2Score": 6 }
  }
}

Errors

Errors use standard HTTP status codes with a JSON body describing what went wrong. Two error shapes are specific to this API — everything else follows the endpoint's own error format.

Status	Meaning
4xx / 5xx	The request was rejected or failed — bad parameters, exhausted quota, etc. The response body describes what went wrong.
404	No such endpoint. { "error": "Not Found", "message": "…" }
502	We couldn't process the request right now (temporary connectivity issue). { "error": "Bad Gateway", "message": "…" }

Example error — quota exceeded

{
  "message": "Request limit exceeded",
  "code": "REQUEST_LIMIT_EXCEEDED"
}

Quota & billing

Every call counts against your plan's quota — we don't add any separate limits on top.

Billable

1 request = 1 call, counted regardless of response size or status. Most endpoints fall in this tier.

Free

/api/historical-odds never counts against your quota, however often it's called.

Each endpoint enforces roughly a 1-second cooldown between calls with identical parameters. Calling the same endpoint faster than that may get rate-limited — we don't currently smooth that out with local throttling or caching.