API Reference — Endpoints and Parameters
Base URL https://api.sockodds.com/v2. All responses use the envelope { success, data, nextCursor, notice }; every endpoint except /health needs a key. Each endpoint page has the full parameter table, response schema, code samples in six languages and a live request builder. Machine-readable: openapi.json · openapi.yaml · Postman.
| Endpoint | Summary | Query parameters |
|---|---|---|
GET /events/ | Get a list of Events | eventID, eventIDs, sportID, leagueID, type, oddsAvailable, oddsPresent, oddID, includeOpposingOdds, includeAltLines, expandResults, includeOpenCloseOdds, bookmakerID, teamID, playerID, finalized, live, started, ended, cancelled, startsAfter, startsBefore, includeFinished, limit, cursor |
GET /odds/history/ | Get the tick-by-tick odds history of an Event | eventID, oddID, bookmakerID, from, to, limit, cursor |
GET /teams/ | Get a list of Teams by ID or league | sportID, leagueID, teamID, limit, cursor |
GET /players/ | Get a list of Players for a specific Team or Event | teamID, eventID, playerID, leagueID, limit, cursor |
GET /sports/ | Get a list of sports | — |
GET /leagues/ | Get a list of Leagues | sportID, leagueID |
GET /stats/ | Get a list of StatIDs | statID, sportID, statLevel |
GET /markets/ | Get a list of Markets | oddID, sportID, leagueID, bookmakerID, statID, statEntityID, periodID, betTypeID, sideID, isMainMarket, isProp, isSubPeriod, propType, isSupported, limit, cursor |
GET /account/usage | Get rate-limits and usage data about your API key | — |
GET /stream/events | Setup streamed (WebSocket) connection | feed, leagueID, eventID |
Authentication
x-api-key header (case-insensitive) or ?apiKey=. Missing or unknown → 401; deactivated → 403.
Health
GET /health → {"status":"ok","timestamp":"…","version":"…","uptimeSeconds":123,"pipeline":"healthy|stale|empty"}Schemas
OddsHistoryTick
One recorded change to one bookmaker's price on one market (SockOdds extension). Odds are given as American strings (bookOdds) and decimals.
| Field | Type | Description |
|---|---|---|
eventID | string | The event |
oddID | string | The market side, in the oddID format (statID-statEntityID-periodID-betTypeID-sideID) |
bookmakerID | string | The bookmaker |
changedAt | string (date-time) | When the bookmaker's quote changed |
kind | string | open = first quote seen · move = price, line or main-line status changed · limit = only the bet limit changed (Pinnacle) · close = the quote was withdrawn |
bookOdds | string | null | The new price as American odds; null on a close |
decimalOdds | number | null | The new price as decimal odds |
previousBookOdds | string | null | The price this change replaced (American); null on an open |
previousDecimalOdds | number | null | The price this change replaced (decimal) |
line | number | null | The spread or total the price applies to; null for moneylines and yes/no markets |
isMainLine | boolean | null | Whether this line was the bookmaker's headline line at the time |
layOdds | number | null | Exchange lay price, where the bookmaker is an exchange |
maxStake | number | null | The bet limit after the change, where the bookmaker publishes one |
previousMaxStake | number | null | The bet limit before the change |
Event
Contains basic information, consensus odds, results (stats & scores), team info, lineups and bookmaker links for a given event/game
| Field | Type | Description |
|---|---|---|
eventID | string | Unique identifier for the event (e.g. afl_2026-09-12_brisbane_lions_vs_adelaide_crows) |
sportID | string | The sport (AUSSIE_RULES, RUGBY_LEAGUE, SOCCER, …) |
leagueID | string | The league (AFL, NRL, RUGBYLEAGUE_NRLW, EPL, …) — always the feed's own key, never constructed |
type | string | match, tournament or prop |
status | object | started, ended, live, cancelled, delayed, finalized, completed, startsAt, oddsPresent, oddsAvailable, currentPeriodID, periods{started,ended}, displayShort/displayLong |
info | object | displayName, commenceTime, lastUpdatedAt, stale (no source write for 45 min), bookmakersPresent, sourceBookmakerCount |
teams | object | home/away → { teamID, names{long,medium,short}, colors, statEntityID, score } |
players | object | playerID → { playerID, teamID, name, firstName, lastName } — the production SGO player ids |
results | object | Nested results in the format {periodID}.{statEntityID}.{statID} → number, where the source carries them |
odds | object | oddID → Odds object. Every market the event is priced on, all bookmakers nested under byBookmaker |
links | object | bookmakers{bookmakerID → event URL} and betslip{bookmakerID → bet-slip strategy} deeplinks, straight from each book's own event ids |
Odds
One side of one market on one event, with every bookmaker's price nested inside
| Field | Type | Description |
|---|---|---|
oddID | string | {statID}-{statEntityID}-{periodID}-{betTypeID}-{sideID} |
opposingOddID | string | null | The oddID of the other side (over ↔ under, home ↔ away); null for pick-N markets |
marketName | string | Human-readable market name, e.g. "Head to Head — Brisbane Lions" |
statID | string | The statistic being wagered on |
statEntityID | string | home, away, all, a playerID or a teamID |
periodID | string | game, 1h, 1q, 1i, 1ix5, 1s, … |
betTypeID | string | ml, sp, ou, ml3way, yn, eo, pick, … |
sideID | string | home, away, over, under, yes, no, draw, … |
playerID | string | Set when the market is a player prop |
bookOdds | string | Consensus American price across the books pricing this side, e.g. "-108" (the vig left in) |
bookOddsAvailable | boolean | Whether at least one bookmaker has this side open for wagering |
bookSpread / bookOverUnder | string | null | Consensus line for spread and total markets |
fairOdds | string | null | The de-vigged fair price derived from exchange and sharp-book consensus; null on plans without fair odds |
fairOddsAvailable | boolean | Whether enough exchange/sharp data existed to compute fairOdds |
fairSpread / fairOverUnder | string | null | The fair line for spread and total markets |
started / ended / cancelled | boolean | Whether the period this market settles on has started, ended or been cancelled |
scoringSupported | boolean | Whether the source can grade this market from results |
byBookmaker | object | bookmakerID → ByBookmakerOdds |
altLines | object | Alternate lines keyed by line, each with its own byBookmaker (only with includeAltLines=true) |
ByBookmakerOdds
One bookmaker's price for one side of one market
| Field | Type | Description |
|---|---|---|
bookmakerID | string | The bookmaker (sportsbet, tab, pinnacle, betfairexchange, …) |
odds | string | American price, e.g. "-108" or "+240" |
decimal | number | The same price as decimal odds, e.g. 1.93 — Australian books quote decimal |
overUnder / spread | string | This book's line where the market has one |
available | boolean | Whether the book has the side open right now (a suspended market is listed with available: false) |
lastUpdatedAt | date-time | When this book's price was last observed |
eventName | string | The book's own name for the event |
deeplink | string | Direct URL to the market on the book where one is known (also see Event.links) |
Team
Contains information on a team
| Field | Type | Description |
|---|---|---|
teamID | string | e.g. BRISBANE_LIONS_AFL — defined per league |
sportID | string | |
leagueID | string | |
names | object | { long, medium, short } |
colors | object | { primary, secondary, primaryContrast, secondaryContrast } where known |
statEntityID | string | home or away on the event the team was read from |
Player
Contains information on a player
| Field | Type | Description |
|---|---|---|
playerID | string | e.g. SONNY_GRAY_1_MLB — the production SportsGameOdds id format, unique across teams in a league |
teamID | string | |
sportID | string | |
leagueID | string | |
name / firstName / lastName | string | |
position / jerseyNumber | string | number | Where the source carries them |
Sport
Contains information on a sport
| Field | Type | Description |
|---|---|---|
sportID | string | |
name / shortName | string | |
enabled | boolean | Whether your plan can read this sport |
activeEvents | number | Events currently carried |
League
Contains information on a specific league
| Field | Type | Description |
|---|---|---|
leagueID | string | |
sportID | string | |
name / shortName | string | |
enabled | boolean | Whether your plan can read this league |
activeEvents | number | Events currently carried |
Stat
Contains information on a statistic (statID)
| Field | Type | Description |
|---|---|---|
statID | string | |
supportedLevels | object | { all, team, player } — which statEntityID classes it is priced at |
displays | object | { short, long } |
isScoreStat | boolean | True for `points`, the stat that decides the event |
supportedSports | object | sportID → true |
Market
Contains information about a betting market, including its classification and support data across leagues and bookmakers
| Field | Type | Description |
|---|---|---|
oddID | string | The unique identifier for this market |
statID / statEntityID / periodID / betTypeID / sideID | string | The decomposed grammar |
playerID / teamID | string | Set for player props and tournament team markets |
marketGroupID / marketGroupName | string | The group (all sides of the market) this market belongs to, and its display name |
isMainMarket | boolean | True for the full-game moneyline, spread and total |
isMainDerivative | boolean | True for a sub-period of a main market |
isSubPeriod | boolean | True when the market tracks a non-main period |
isProp | boolean | True if this is a prop bet |
propType | string | game_prop, team_prop, player_prop or other_prop |
isSupported | boolean | True if at least one bookmaker prices it in at least one league |
activeEvents | number | Unique events with this market priced right now |
support | object | leagueID → { bookmakerID → true } |
bookmakers | string[] | SockOdds extension: the flat list of bookmakers pricing it |
AccountUsage
Your API key's tier, rate limits and current usage
| Field | Type | Description |
|---|---|---|
keyID | string | The hashed identifier for the API key (the first 16 hex of sha256) |
customerID | string | null | Billing customer id where one exists |
email | string | null | |
isActive | boolean | |
tier | string | lite, base or internal |
rateLimits | object | per-second / per-minute / per-hour / per-day / per-month → RateLimitInterval |
RateLimitInterval
One rate-limit window
| Field | Type | Description |
|---|---|---|
max-requests | integer | null | Maximum allowed requests in the interval (null = unlimited) |
current-requests | integer | Requests made so far in the interval |
max-entities | integer | null | Maximum objects in the interval (null = unlimited) |
current-entities | integer | null | Objects served so far in the interval |