Pagination & Filtering

Use the parameters listed on an endpoint’s API Reference page. Paging and filters vary by family; an unrecognized parameter may be ignored rather than rejected.

Cursor lists

/v1/{league}/games, its /matches alias, /v1/proto/fixtures, and /v1/proto/rounds return an object inside data:

{
  "data": { "items": [], "next_cursor": "OPAQUE_CURSOR" },
  "_meta": { "request_id": "req_example", "served_from": "live" }
}

Read records from data.items. Pass data.next_cursor back as cursor while keeping your other filters unchanged. Stop when next_cursor is absent. Cursors are opaque and specific to the query; do not decode or build them yourself. These lists default to 25 items and cap limit at 200.

const base = "https://api.sportquanta.com/v1/mlb/games";
let cursor;
do {
  const url = new URL(base);
  url.searchParams.set("date", "2026-10-13");
  url.searchParams.set("limit", "50");
  if (cursor) url.searchParams.set("cursor", cursor);
  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.SPORTQUANTA_API_TOKEN}` },
  });
  const body = await res.json();
  if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
  for (const game of body.data.items ?? []) console.log(game);
  cursor = body.data.next_cursor;
} while (cursor);

Other lists

Family	Shape and limits
Catalogs	`data` is an array; no cursor.
Team directory	`data.items`; bounded by `limit`, without a continuation cursor. NFL/NHL have static directory routes.
Rosters, soccer events, squad history, player season stats, call-ups	Usually an array in `data`; no common cursor contract.
Recent games, leaders, shot charts, play-by-play	Sport-specific object and bounded `limit`; use the endpoint’s own default and maximum.
Odds/prop history	`data.items`, oldest first; default 1000 rows, maximum 5000. No continuation cursor.
Source-tier changes	`data.items`, oldest first; default 200 rows. Values outside 1–1000 fall back to 200.
Baseball player game log	`data.data.games`; `last` defaults to 25 and caps at 200. Supplying `season` without `last` returns the full completed regular-season log.

For a large history series, narrow the bookmaker, market, selection, player, or time range. Time bounds are inclusive, so deduplicate boundary rows when combining overlapping windows.

Schedule filters

Both /games and /matches use the same schedule handler.

Parameter	Meaning
`date`	Schedule date, `YYYY-MM-DD`.
`date_from`, `date_to`	Schedule-date bounds.
`season`	League-specific season value; treat as a string in requests.
`team_id`	Canonical team ID; use this exact name.
`status`	Stored status value. Casing and vocabulary vary by sport; use values returned by that league.
`week`	NFL week filter; ignored by sports that do not use it.
`game_type`	NHL game-type filter; ignored by sports that do not use it.
`upcoming`	Baseball convenience filter; accepts `true`, `1`, `yes`, or `y`.
`limit`, `cursor`	Cursor paging parameters.

For baseball, upcoming=true supplies the league’s current local date when no date bounds are given and extends the window through 30 days after that date, selects upcoming statuses when no status is given, orders by schedule date/start time, and collapses duplicate public fixtures. MLB uses America/New_York, KBO Asia/Seoul, and NPB Asia/Tokyo for that default.

curl "https://api.sportquanta.com/v1/kbo/games?upcoming=true&team_id=TEAM_ID&limit=10" \
  -H "Authorization: Bearer $SPORTQUANTA_API_TOKEN"

Seasons and sport filters

A season is not always a calendar year: soccer can use 2025/26, and basketball readers can accept a season start year or a supported season label. Follow the format documented for the endpoint. Some missing season parameters resolve the latest stored season, while others filter nothing. Soccer standings accept competition (alias competitionId) and group (alias groupCode). Team overview uses competitionId, recentLimit, and upcomingLimit. Soccer analytics use segment=all|home|away where documented. There is no general competition or stage filter on the universal schedule handler. Basketball rosters accept season for historical membership. NBA league-wide injuries require date=YYYY-MM-DD.

Odds and history filters

Parameter	Accepted by
`bookmaker`	CSV allowlist on current odds/props, fair/best reads, opening/closing, and odds/prop history. Source-tier changes take one bookmaker ID.
`market`	CSV on current props and opening/closing; a single market on history. Fair/best reads do not expose a market filter.
`player`	Current and derived props convenience filter; player-scoped routes use `{player_id}`.
`player_id`	Prop history filter.
`format`	`american` (default) or `decimal` on quoted current/derived/opening/closing prices.
`from`, `to`	Inclusive RFC 3339 timestamps on odds/prop history and source-tier changes.
`since`	Settlement revision feed; defaults to the preceding 24 hours.

Proto from and to are integer timestamps from its own fixture contract, rather than RFC 3339 strings. Do not reuse history parameters across families.

Composite reads and provenance

Use the dedicated matchup, box-score, details, lineup-card, profile, and snapshot routes to combine related data. A general include=odds query is not implemented on the universal fixture detail route. provenance=true or provenance=1 opts into per-field source metadata on supported single-resource reads. Lists and most composites accept the flag without adding provenance. See IDs, Assets & Availability.

Get Started

Core Concepts

Data & Integration

Agents

Pagination & Filtering

Cursor lists

Other lists

Schedule filters

Seasons and sport filters

Odds and history filters

Composite reads and provenance

​Cursor lists

​Other lists

​Schedule filters

​Seasons and sport filters

​Odds and history filters

​Composite reads and provenance

Cursor lists

Other lists

Schedule filters

Seasons and sport filters

Odds and history filters

Composite reads and provenance