Skip to main content
The V2 API organizes sports data in a nested hierarchy. Understanding this structure is essential for parsing event responses, building odds screens, and processing delta updates. For how the model supports comparing prices across books, see the sports odds API guide.

Hierarchy Overview

Event completion for grading

For events with game-stat coverage, meta.complete: true marks the event’s box score finalized for grading. REST exposes this event-level signal on each team or player stats group from /api/v2/events/{eventID}/stats or /api/v2/events/{eventID}/players/stats, paired with meta.event_id. It is not a field on the ordinary event object or the events response envelope. WebSocket game_stats messages use data.complete and data.event_id for the same event-level signal. See Event completion for grading for examples, access requirements, and handling of missing completion or later corrections.

Event Object

Each event represents a single game or match. Events are the top-level objects returned by /api/v2/sports/{sportID}/events/{date}.
For V2 REST endpoints and WebSocket filters, pass the event_id value returned in event payloads. Do not substitute event_uuid.

Score Object

Score metadata can be incomplete. Text fields such as venue_name, venue_location, broadcast, and display_clock may be empty when unavailable. Period arrays can also be empty. Use score.updated_at to judge freshness.
Regulation NFL and NBA finals have four period entries per side and game_period of 4. Each overtime adds another entry and advances game_period: one overtime gives five entries and Final/OT; two give six entries and Final/2OT. Regulation finals use event_status_detail of Final. Exhibition exceptions are described below. Read each side by its own array length. In baseball, the home array is one entry shorter when the home team does not bat in the bottom of the ninth or the last extra inning. Do not pad a missing entry with zero or assume both arrays have the same length.
The final scores (score_home and score_away) and period arrays are independent fields. In the twelve months reviewed on September 8, 2026, every NFL and NBA event that reached a final state had period sums matching its final scores. game_period matched the array lengths in all but one exhibition game. These are observations, not enforced guarantees: verify completeness, each side’s sum, and the period count before deriving a result, and handle mismatches without guessing.All-Star and preseason games can be final with an empty period array or game_period of 0 or 1. Regular-season and playoff games were consistent in that review, but still need validation. Exclude preseason using the season-specific sport IDs, including NBA Preseason (23) and NFL Preseason (25).
See Scores and Results for worked examples, half scores, and checks before locking a result.

Team Object

Market Object

Each market represents a type of bet (moneyline, spread, total, player prop, etc.). Markets are nested inside events.

Participant Object

Participants are the entities you can bet on within a market — teams, players, or result types (Over/Under).
id is the stable, joinable identifier — join on id, not name. What id points to depends on type:
  • TYPE_TEAM — id is the normalized team ID. It is stable across seasons and endpoints, and matches event.teams[].team_id. Fetch the full team at GET /api/v2/teams/{team_id}.
  • TYPE_PLAYER — id is the player ID. Fetch the full player (team, names, position) at GET /api/v2/players/{player_id}.
  • TYPE_RESULT — id is a small outcome index (e.g. 0/1 for Over/Under) and is not a team or player resource key.
Because every distinct team and player has a distinct id, joining on id resolves shared-name collisions that joining on name cannot. To look up an id from a name once, use the roster at GET /api/v2/teams/{team_id}/players or the team list at GET /api/v2/sports/{sportID}/teams.

Line Object

A line represents a specific betting line for a participant. For spreads and totals, the value contains the line number. An empty value, such as an unlabelled moneyline, is omitted from the response.
line_value_is_participant tells you where the meaningful selection detail lives. When it is true, the participant carries the selection and the line value may be a placeholder or label. When it is false, display the line value when present; it may be a number, threshold, method, round, or other outcome qualifier.

Price Object

A price is the odds offered by a single sportsbook for a specific line. Fields that appear in delta/history responses: For a full current price object, an omitted closed_at means open; clear any previously stored closure timestamp when replacing that object. For historical rows and chart points, omission only means that row has no closing timestamp and does not establish the line’s current state. Chart responses use the optional c field for the same historical closing-time semantics. Fields present on selected affiliates:
liquidity_usd is omitted entirely, never null and never a fabricated 0, when a current reading is not available. Treat a missing field as “unknown,” not as zero. See What is liquidity_usd on a price object? in the FAQ for what the number means on each affiliate and why it is not on every price.

Traversing the Data

Market participants are ordered by type and ID, not by home or away side. Find the market by market_id and period_id, then match a team participant by type and its team ID. A filtered or missing market can also change the positions in markets. This helper returns the raw price object, or None when the requested market, team, line or affiliate quote is absent. Use None for an unlabelled line and the exact returned value string for a spread, including its sign. The examples use full-game period 0.

Reading a moneyline price

Given one returned event, select its away team and use the helper above to read that team’s DraftKings (19) moneyline (1):
Reading a price does not establish its current availability. Apply the closed_at rule above before using a quote as available.

Reading a spread value and price

Using the same helper, request the away team’s spread (2) at a specific line. "+3" is an example; choose a value present in your response.

Iterating all prices for an event

Delta Responses

Delta endpoints return a different shape. Instead of the nested event → market → participant → line → price hierarchy, they return flat change records: Use the event_id, market_id, participant_id, and affiliate_id to locate the correct entry in your local cache and replace the price. See the Efficient Polling guide for the full update pattern.