Aura Sports Data API

GET/health

Health check

Confirms the API process is reachable.

GET/api/openapi.json

OpenAPI schema

Returns this machine-readable API contract.

GET/api/coverage

Product coverage and reliability

Returns concise source-neutral availability and measured completeness by sport, capability, and season.

GET/api/catalog

API catalog

Returns the stable sports objects, request delivery capabilities, and documentation links available to customers without scanning stored data.

POST/api/query

Execute an Aura query

Runs up to eight named selections against registered roots and returns only requested fields.

GET/api/games

Page through games

Returns a chronological page from one Pacific calendar date, one league week (`week`), or one postseason round (`competition`/`round`). The first request defaults to today in America/Los_Angeles; a cursor keeps that window and the active filters stable. No sport filter means every sport. Collection items preserve identity, teams, score, phase, schedule, and freshness while omitting full-resource detail such as box scores, plays, metrics, and markets.

pageSizequery

Games per page (1-100; default 100).

cursorquery

Opaque cursor from `page.nextCursor`. Omitted filters continue from the cursor.

sportquery

Optional sport filter. Omit it for every sport.

subdivisionquery

Optional college-football subdivision membership. Cross-subdivision games match both filters.

statusquery

Optional game phase filter.

datequery

Pacific calendar date in YYYY-MM-DD format. Defaults to today in America/Los_Angeles on the first page.

teamquery

Optional team abbreviation filter.

weekquery

NFL or college football regular-season week, in place of `date`: every game of that week. Needs `sport`.

competitionquery

Postseason or championship, in place of `date`: every game of it in the season. Needs `sport`.

roundquery

One round, e.g. `quarterfinal`, `round_of_64`, `divisional`. Combine with `competition` to pick between tournaments.

seasonquery

Season for `week`, `competition`, or `round`. Defaults to the current season. Football seasons are named for the fall they start; college basketball for the spring it ends.

viewquery

Stable collection projection. `summary` is the default; `scoreboard` is the compact daily-slate contract.

fieldsquery

Optional comma-separated allowlist of summary scalar or team leaf dot paths. `gameId`, `sport`, and the team envelope are always included; duplicates and unknown paths fail with 400.

GET/api/games/live

List live games

Returns the complete filtered inventory of fresh games marked in progress. Games not updated inside the freshness window are excluded so stale state cannot appear live.

maxAgeSecondsquery

Maximum game-state age in seconds. Defaults to 300 and is capped at 86400.

GET/api/games/{gameId}

Get game

Returns one compact game with identity, schedule, status, teams, and score. Use `view=card` to omit the status labels; `fields` may select a bounded named-consumer projection.

viewquery

`research` (default) or `card`.

fieldsquery

Optional comma-separated allowlist of Game resource fields. `gameId`, `sport`, and the team envelope remain included; duplicates and unknown paths fail with 400. Fields require `view=card` or `view=research`.

GET/api/games/{gameId}/frame

Get current atomic game frame

Returns the latest source-neutral render snapshot assembled only after its scoreboard, play, player-stat, and metric writes are durable. Poll this ordinary one-credit request at a bounded cadence; resumable realtime delivery is available through a direct Aura relationship.

fieldsquery

Optional comma-separated allowlist of GameFrame state fields; game identity, scoreboard, state, latest play, and featured player remain included. Duplicates and unknown paths fail with 400.

GET/api/games/{gameId}/plays/page

Page through complete game plays

Returns one stable chronological page. Use `order=desc` for the latest plays. Pass `nextCursor` as `cursor` until `hasMore` is false.

pageSizequery

Events per page (1-250; default 250).

orderquery

Chronological direction: asc (default) or desc.

fieldsquery

Optional comma-separated allowlist of item fields, such as items.sequence,items.situation; structural fields remain included.

GET/api/games/{gameId}/boxscore

Get game box score

Returns one exact source-neutral Aura BoxScore with team and player stat lines flattened from the retained read model.

fieldsquery

Optional comma-separated allowlist of BoxScore fields; teams and players remain included as required identity/stat envelopes.

GET/api/games/{gameId}/markets

List game markets

Returns the complete sellable inventory for one game. Every independently graded line is a stable market.

marketTypequery

Filter by market type.

categoryquery

Filter player props by category.

playerIdquery

Filter to one Aura player id.

definitionIdquery

Filter to one market definition id.

primaryquery

Filter to current primary or alternate lines.

availabilityquery

Filter by current availability.

GET/api/games/{gameId}/odds/timeline

Get game odds timeline

Returns the complete compact source-neutral market history needed to chart line movement.

marketTypequery

Market type, defaults to moneyline.

fieldsquery

Comma-separated allowlisted response fields for the chart-ready market projection.

GET/api/games/{gameId}/metric-series

Page through metric observations

Returns change-only metric values used by Game Pulse. Omit `entityId` and `definitionId` to return every metric for the game. Follow `nextCursor` until `complete` is true.

entityIdquery

Comma-separated Aura entity ids.

definitionIdquery

Comma-separated metric definition ids.

limitquery

Maximum observation batches, 1 through 500.

cursorquery

Opaque continuation cursor from the previous response.

fieldsquery

Optional comma-separated allowlisted response fields from the metric-series catalog.

GET/api/games/history

Page through MLB game history

Returns exact source-neutral MLB game results in stable chronological order. Each item contains only game identity, season, schedule, phase, teams, score, and venue. Follow `nextCursor` until `hasMore` is false; cursors are scoped to the active filters.

pageSizequery

Games per page (1-100; default 100).

seasonquery

Four-digit season.

teamIdquery

Aura team id or common MLB abbreviation.

venuequery

Aura venue id.

phasequery

Game phase.

fieldsquery

Optional comma-separated allowlist of MLB history game fields. The page envelope and id, sport, season, startsAt, and teams identity fields remain included; duplicates and unknown paths fail with 400.

GET/api/games/history/coverage

Get MLB history coverage

One exact game and player-stat completeness contract for history discovery.

fieldsquery

Optional comma-separated allowlist of game and player-stat coverage dot paths. Top-level identity and coverage containers are always included; duplicates and unknown paths fail with 400.

GET/api/metrics/definitions

List metric definitions

Returns the complete filtered inventory of exact, cacheable Aura metric definitions and their analysis semantics.

sportquery

Sport filter, including ALL.

familyquery

Metric-family filter.

entityTypequery

Entity-type filter.

fieldsquery

Comma-separated allowlisted item fields; identity and paging remain included.

GET/api/metrics/definitions/{metricId}

Get metric definition

Returns one stable Aura metric definition.

metricIdpath · required

Stable Aura metric definition id.

fieldsquery

Comma-separated allowlisted item fields; identity remains included.

GET/api/analytics/landscape

Build league landscape

Returns the compact LeagueLandscape view.

entityTypequery

Landscape subject.

xquery · required

Metric definition id plotted on the x axis. Required.

yquery · required

Metric definition id plotted on the y axis. Required.

sizequery

Optional metric definition id encoded as point size.

colorquery

Optional metric definition id encoded as point color.

outcomequery

Optional metric definition id classified against `outcomeThreshold`.

outcomeOperatorquery

Comparison applied to the outcome metric.

outcomeThresholdquery

Numeric threshold for the outcome classification. Required with `outcome`.

sportquery

Optional sport filter, such as MLB or WNBA.

phasequery

Optional comma-separated game phase filter.

cohortquery

Optional cohort restriction as `team:<value>` or `position:<value>`.

aggregatequery

How multiple samples per entity collapse to one value.

fromquery

Optional inclusive lower bound on observation time, Unix epoch milliseconds.

toquery

Optional inclusive upper bound on observation time, Unix epoch milliseconds.

xDimensionsquery

Optional JSON object of metric dimension filters for the x axis.

yDimensionsquery

Optional JSON object of metric dimension filters for the y axis.

sizeDimensionsquery

Optional JSON object of metric dimension filters for the size metric.

colorDimensionsquery

Optional JSON object of metric dimension filters for the color metric.

outcomeDimensionsquery

Optional JSON object of metric dimension filters for the outcome metric.

xDirectionquery

Which x direction counts as better; defaults from the metric definition.

yDirectionquery

Which y direction counts as better; defaults from the metric definition.

includequery

Set to `export` to include bounded model-ready export rows.

fieldsquery

Optional comma-separated LeagueLandscape response fields.

limitquery

Maximum 500 returned entities.

GET/api/analytics/player-comparison

Compare MLB player form

Compares two to four Aura MLB players across season and rolling windows with bounded series, coverage, cache validators, and model-ready rows.

playersquery · required

Two to four comma-separated Aura MLB player IDs.

seasonquery · required

Four-digit MLB season.

rollingGamesquery

Rolling window from 1 to 50; default 10.

homeAwayquery

Optional home or away split for baseline and series.

throughquery

Optional inclusive UTC date, YYYY-MM-DD.

metricsquery

Optional comma-separated metric ID allowlist.

fieldsquery

Optional comma-separated PlayerComparison field allowlist; identity, window, comparison entities, samples, and coverage remain included. Duplicates and unknown paths fail with 400.

GET/api/markets

Page through markets by game

Returns each game once with its complete collection of source-neutral markets. The page unit is a game, so alternate lines remain independently graded market objects without repeating game detail. The first request defaults to today in America/Los_Angeles and no sport filter means every sport.

pageSizequery

Games per page (1-100; default 25).

cursorquery

Opaque cursor from `page.nextCursor`. Omitted filters continue from the cursor.

datequery

Pacific calendar date in YYYY-MM-DD format. Defaults to today in America/Los_Angeles on the first page.

sportquery

Filter the daily market board by sport. Omit it for every sport.

GET/api/markets/{marketId}

Get market

Returns one player prop or game moneyline, spread, total, or team total by the same market id the game board publishes.

marketIdpath · required

Aura market id from a game prop board or game odds.

GET/api/sports/{sport}/teams

List teams for a sport

Returns the full retained team inventory with names, colors, conference, division, and subdivision. No query parameters.

GET/api/teams

List teams

Returns the complete roster-free Team inventory for one sport.

sportquery · required

Required sport.

leaguequery

Optional league filter.

GET/api/teams/{teamId}

Get team

Returns one exact Team profile. NFL and college football teams also carry their current season: poll rank and ranked offense and defense stats. Rosters remain available from the dedicated roster route.

fieldsquery

Optional comma-separated Team profile fields; id, sport, and name remain included. Duplicates and unknown paths fail with 400.

GET/api/teams/{teamId}/roster

Get team roster

Returns one Team and directly renderable roster players without a second profile lookup.

GET/api/teams/{teamId}/injuries

Get team injuries

Returns every currently injured or suspended player on one team, newest report first. No query parameters.

GET/api/teams/{teamId}/news

Get team news

Returns the 20 newest stories about one team from the last 30 days, newest first. No query parameters.

GET/api/teams/{teamId}/seasons/{season}

Get team season

Returns one football team season: ranked team stats, record, results of completed games in date order with each game's week and offense and defense lines, and every player who appeared with season totals. Preseason games are left out. NFL record and totals are the regular season, with playoff games listed in results; college football counts bowl and playoff games. Season is the league season year. No query parameters.

GET/api/sports/{sport}/rankings

Get rankings

Returns college football polls as they stood for one week: the AP Top 25, the Coaches Poll, the CFP rankings once the committee starts publishing, and the FCS Coaches Poll. A week shows each poll's newest release at or before it, so week 1 returns the preseason polls and an early week has no CFP rankings. Retained from 2021. Omit both parameters for the latest release.

sportpath · required

Aura sport.

seasonquery

Four-digit season year. Defaults to the newest season with rankings.

weekquery

`preseason`, `final`, or a week number from 1 to 20. Defaults to the newest week of the season.

GET/api/sports/{sport}/leaders

Get leaders

Returns teams or players ranked by one stat over a season, a week range, or a date range. Team stats: points, totalYards, passingYards, rushingYards, firstDowns, turnovers, on offense or defense (allowed). Player stats: any football stat key, e.g. rushingYards, passingYards, receivingYards, totalTackles, sacks. College football ranks FBS unless subdivision=FCS. Example: who led rushing in October is scope=player&stat=rushingYards&from=2026-10-01&to=2026-10-31.

sportpath · required

Aura sport.

scopequery

team (default) or player.

statquery

The stat to rank. Teams default to points; players require it.

sidequery

Teams only: offense (default) or defense, what the team allowed.

seasonquery

Defaults to the current season.

weeksquery

One week (6) or a range (4-8).

fromquery

First Pacific date, YYYY-MM-DD.

toquery

Last Pacific date, YYYY-MM-DD.

subdivisionquery

College football: FBS (default) or FCS.

conferencequery

Conference abbreviation (SEC, BIG12) or id; NFL: AFC or NFC.

perquery

Sort by per-game average or total. Teams default to game, players to total. Per-game player leaders need 60% of the games of the player who played most.

limitquery

1-100; default 25.

GET/api/stats/mlb/history/team-aggregates

Get MLB team form

Exact season and recent form used by Game Pulse.

teamIdquery · required

Required Aura team id or abbreviation.

fieldsquery

Optional comma-separated allowlist of MLB team form fields. Team identity and request context remain included; duplicates and unknown paths fail with 400.

GET/api/stats/player-game

List player-game stats

Returns the complete normalized player-stat inventory for one game.

gameIdquery · required

Required Aura game id.

teamIdquery

Aura team id.

GET/api/sports/{sport}/players

List players for a sport

Returns up to 100 retained player profiles in stable identity order, collapsing source aliases. Follow page.next for subsequent pages. No query parameters.

GET/api/sports/{sport}/players/page/{cursor}

Continue player discovery

Follow page.next from sport player discovery without constructing the cursor. No query parameters.

cursorpath · required

Opaque cursor from the previous page.

GET/api/players

Page through players

Returns a cursor-paged catalog of exact Player profiles. Omit sport and league to browse every retained player.

pageSizequery

Players per page (1-100; default 100).

cursorquery

Opaque cursor from `page.nextCursor`. Omitted filters continue from the cursor.

sportquery

Optional sport filter.

leaguequery

Optional league filter.

GET/api/players/{playerId}

Get player

Returns one full Player by default. The stable `card` view returns nullable identity, team, position, and headshot fields shared by player reveals.

viewquery

`full` (default) or `card`. Unsupported views fail deterministically.

fieldsquery

Optional comma-separated Player profile fields; id, sport, and the full name identity envelope remain included. Fields require the full view; duplicates and unknown paths fail with 400.

GET/api/players/{playerId}/headshot

Get player headshot

Returns available player image bytes. Follow media.headshot from the player profile; null means no retained photo. Authenticate like other API reads. Browser apps should fetch a blob with their allowed public key or serve the image through their backend; never place a server key in an image URL. No query parameters. Returns 404 when unavailable.

GET/api/players/{playerId}/news

Get player news

Returns the 20 newest stories that name one player from the last 30 days, newest first. No query parameters.

GET/api/players/{playerId}/seasons

Get player seasons

Returns every retained football season newest first, one row per season, part and team, totaled from completed games the player appeared in. Preseason games are left out. NFL playoffs are their own postseason row; college football bowl and playoff games are part of the regular row, as in NCAA season totals. No query parameters.

GET/api/players/{playerId}/seasons/{season}/ranks

Get player season ranks

Ranks one football player season against every player in the same position group, overall and in their conference. NFL ranks cover the regular season. QB ranks among players with passing yards, RB with rushing yards, WR and TE with receiving yards, DL, LB and DB with tackles. Equal values share a rank. Returns 404 when the player has no completed games that season or plays an unranked position. No query parameters.

GET/api/players/{playerId}/seasons/{season}/gamelogs

Get player season gamelogs

Returns the full retained season newest first, across all seven sports, with one entry per game, game context, grouped stats, and explicit coverage. Season is the league season year (ending year for NBA, NHL, and college basketball). No query parameters or pagination. Missing games are not zero-stat appearances.

GET/api/players/{playerId}/gamelogs/{gameId}

Get player gamelog

Returns one player game entry using the same shape as the season collection. No query parameters. Returns 404 when no retained entry exists.

GET/api/stats/nfl/history/player-seasons

NFL player seasons

Season totals and play-derived advanced stats on Aura player ids.

seasonquery · required

Required NFL season.

seasonTypequery

REG; the retained 2025 fantasy season.

positionquery

Optional position abbreviation.

fieldsquery

Comma-separated exact fields. playerId, season, and seasonType remain included.

GET/api/stats/mlb/history/player-lines

MLB player lines

Exact v2 rows; page ≤250, bulk ≤1,000.

viewquery

Read mode: `page` (≤250 rows) or `bulk` (≤1,000 rows, bulk-export billing).

pageSizequery

Rows per page: 1-250 for `page` (default 100), 1-1000 for `bulk` (default 500).

seasonquery

Four-digit MLB season.

teamIdquery

MLB abbreviation or Aura team id.

opponentTeamIdquery

MLB abbreviation or Aura team id.

rolequery

Player role for the line.

fieldsquery

Optional comma-separated allowlist of player-line item fields; identity fields remain included. Duplicates and unknown paths fail with 400.

GET/api/stats/mlb/history/player-aggregates

Get MLB player form

Exact season and recent form; optional home/away and opponent splits.

playerIdquery · required

Required Aura player id.

includequery

Optional homeAway,opponents splits.

fieldsquery

Optional comma-separated allowlist of MLB player form response fields; identity and request envelope remain included. Duplicates and unknown paths fail with 400.

GET/api/sports/{sport}/news

Get league news

Returns the 20 newest league stories from the last 30 days, newest first. No query parameters.

GET/api/fantasy/nfl/adp

NFL fantasy draft data

2026 draft ranks, ADP inputs, season projections, and recomputable fantasy scores.

entityIdquery

Optional Aura player or team id.

afterquery

Continue after this entity id.

fieldsquery

Comma-separated exact fields. entityId, entityType, and season remain included.

GET/api/fantasy/nfl/weeks/{week}

NFL fantasy week

One current NFL week with retained opening/latest/closing snapshots, input ranges, availability, and actual performance.

weekpath · required

Regular-season week, 1 through 18.

entityIdquery

Optional Aura player id; equivalent to playerId.

fieldsquery

Comma-separated exact fields. Identity, season, and week remain included.

GET/api/fantasy/nfl/players/{playerId}

NFL fantasy player

One player across draft data, weekly projections, retained observation history, and actual performance.

weekquery

Optional regular-season week.

fieldsquery

Comma-separated weekly player fields.

POST/api/agent/register

Create trial agent access

Creates trial API access (1,000 requests) without an email, password, browser session, or approval step. Key secrets are returned once. When the trial is used up, requests return `email_required`: verify the user's email with `/api/agent/claim` to move the same keys to the free plan.

POST/api/agent/claim

Email a verification code

Sends a six-digit code to the user's email. Authenticate with the trial key. Codes expire after 15 minutes.

POST/api/agent/claim/verify

Verify the emailed code

Moves the trial key's active keys to the free plan under the verified email. One account per email: a second verification of the same email joins that account and shares its quota. Key secrets do not change.

POST/api/agent/upgrade

Create a Pro checkout link

Returns a Stripe Checkout URL for the verified account behind this key. Give it to the user; payment happens in their browser and the same keys move to Pro.

POST/api/agent/connections

Request free API access

Starts a ten-minute connection request. The coding agent keeps the verifier private and sends the approval URL to its user.

POST/api/agent/connections/{connectionId}/redeem

Redeem approved API access

Polls with the private verifier. A pending approval returns 202; an approved request returns each API key secret once.

connectionIdpath · required

Connection id returned by the start request.