List Events

This endpoint retrieves a list of events based on the provided query parameters.
You can filter events either by (season year, week) OR (day, month, calendar year)
season type, and league ID are additional filters.

Note: The first week of the NFL postseason is week 1, season_type = POST

For NFL and NCAAF events, the response includes both week and season_type_agnostic_week fields.
The season_type_agnostic_week is a continuous week number across the entire season (regular season weeks 1-18 for NFL, 1-16 for NCAAF, with postseason weeks continuing from there).

Pagination is supported to navigate through large sets of data.

If none of (day/month/calendar_year, start_date/end_date, week,
season_type_agnostic_week) is supplied, results default to a rolling
window (recent past through the next ~30 days) rather than the league's
entire slate. Pass an explicit start_date/end_date to see events outside
this window.

Each sports event also carries market_count and market_counts_by_venue
so a client can tell which games have something to trade without reading
/odds per event. market_count is the number of distinct OPEN markets
(provider status active; suspended, closed, settled and unknown statuses
are not counted) in sources the tenant can read, the same visibility as
GET /markets; market_counts_by_venue gives the same count per venue
(aggregator, e.g. polymarket, kalshi), and its values can sum to more
than market_count because market_count counts a market once. Finished
events report 0. With active=true&aggregator=<venue> only that venue is
counted. A market being open does not mean it is currently priced; read
GET /events/{id}/odds for prices. null means the count could not be
computed right now (never 0); the list still serves. Crypto windows do
not carry these fields.

Crypto (league_id=CRYPTO; tenants entitled to the CRYPTO league only). One event
per crypto up/down window (event_id = the window id), with empty participants and a
title like BTC Up or Down 10:30-10:45 UTC (always UTC). Status is scheduled,
in_progress (inside the window), completed (from window_end, even if no venue has
posted a result yet) or cancelled (every listing voided). The additive
crypto_window object carries the asset, horizon, window bounds and the per-market
groups (list responses carry market_id, venues and alignment only; fetch
/events/{id} for constituents and results). With none of status, start_date or
end_date the set is live plus upcoming windows starting within 24 hours; an explicit
status or date replaces that default (completed is the last 24 hours), and
start_date..end_date may span at most 7 days. season_year is accepted and means the
UTC year of window_start. status=cancelled is not supported as
a filter. asset and horizon filter; active=true&aggregator=kalshi returns windows
the venue currently lists with a quote no older than 15 minutes (predict_fun,
prophetx, polymarket_us and sxbet are valid and empty). Default per_page is 100, maximum 200. Sports-only
filters (week, season_type*, participant_id, team_id, player_id,
day, month, year, calendar_year) are a 400 for this league;
include_scoreboard and the source-mapping parameters are accepted and ignored.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Query Params
integer

The year of the season. i.e. Superbowl on Feb 14th 2025 is still in the 2024 season

integer

(Use week OR season_type_agnostic_week) Week (only supported for weekly sports [NFL / NCAAF] i.e. first week of the season is 1, first week of the postseason is 1 with season_stage = POST)

integer

(Use week OR season_type_agnostic_week) Week - Agnostic of Season Type (only supported for weekly sports [NFL / NCAAF]) i.e. first week of the season is 1, first week of the postseason is 19. Setting this parameter will ignore season_type

string

Day of the month (DD) - must also pass month and calendar_year (or year)

string

Month of the year (MM) - must also pass day and calendar_year (or year)

string

Year of the event (YYYY) - must also pass day and month

string

Alias of calendar_year. Must also be passed with day and month.

string

Season type (PRE / REG / POST)

string
enum

Filter by event status (scheduled, in_progress, completed, cancelled, postponed, time_tbd)

Allowed:
boolean
Defaults to false

When true, return only nonterminal events that currently have tenant-visible odds from the required aggregator.

string
enum

Filter active event discovery by odds aggregator (for example kalshi or polymarket). Requires active=true. One value only: a comma-separated list returns 400; send one request per aggregator.

boolean
Defaults to false

When true, return only nonterminal events that currently have at least one OPEN market on a requested venue (see venue): the events whose market_counts_by_venue is nonzero for one of them. Several venues are checked in one request, unlike active=true&aggregator=. Requires league_id; cannot be combined with active or aggregator. Only events that started within the last 36 hours or start within 14 days are considered (the market_count window), so it does not apply the default date window; pass start_date/end_date to bound it further. 503 when the discovery read is unavailable.

string

Comma-separated prediction venues has_venue_markets considers (polymarket, kalshi, prophetx, predict_fun, limitless, polymarket_us, sxbet). Default: polymarket,kalshi,prophetx; polymarket_us and sxbet are opt-in and never part of the default. Requires has_venue_markets=true.

string
enum

CRYPTO league only (league_id=CRYPTO): filter to one asset. Any other league rejects it as an unknown parameter (400).

Allowed:
string
enum

CRYPTO league only (league_id=CRYPTO): filter to one window horizon. Any other league rejects it as an unknown parameter (400).

Allowed:
string
required

Filter by league ID — accepts a UUID or league abbreviation (e.g., 'NFL', 'NBA'). See GET /api/v1/leagues for all leagues.

uuid

Filter events by participant ID (team or player common_model_id). Returns events where the specified participant is involved.

uuid

Filter events containing this team common_model_id.

uuid

Filter events containing this player common_model_id.

string

Return events scheduled at or after this instant (inclusive). Accepts an ISO 8601 date-time (e.g. '2026-08-05T00:00:00Z') or a plain UTC date ('2026-08-05', interpreted as 00:00:00Z). Combine with end_date for a range. Bounds are UTC — distinct from the day/month/calendar_year filter, which resolves a calendar day in America/New_York; avoid combining the two.

string

Return events scheduled at or before this instant (inclusive). Accepts an ISO 8601 date-time or a plain UTC date ('2026-08-05', interpreted as the end of that day, 23:59:59.999999Z). Combine with start_date for a range. Bounds are UTC — distinct from the day/month/calendar_year filter, which resolves a calendar day in America/New_York; avoid combining the two.

string

Include source mappings from the specific integration (i.e. a provider key) will return a source_mappings object with the mappings for the respective objects

boolean

Return an exact x-total-count/x-total-pages for the list. Defaults
to true for a bounded request (any filter that narrows the league
board — a day/week, a date range, a participant/team/player, an event
status, or active=true) and false for a bare full-league board
(only league_id, optionally with season_year/season_type), where
counting every matching event is unbounded and can hold a database
connection open for tens of seconds. When the count is skipped both
x-total-count and x-total-pages are omitted — a skipped count
is reported by absence, never by a number — and pagination is
cursor-style: follow the link header's next relation until it is
absent. last is withheld too, because an uncounted read does not
know where the end is. Pass count=true for exact totals. Must be
true or false; any other value is rejected with HTTP 400.

boolean
Defaults to true

Include detailed scoreboard information for each event. Scoreboard is always included by default.

boolean
Defaults to false

When true, add source_mappings_by_source keyed by full normalized source (for example, provider.football.nfl).

string

Optional provider-family filter for source_mappings_by_source (for example, a provider key).

string

Optional full-source filter for source_mappings_by_source in provider.sport.league format.

integer
≥ 1
Defaults to 1

Page number for page/per_page pagination. Do not combine with limit/offset.

integer
1 to 1000
Defaults to 100

Number of items per page (max 1000). Do not combine with limit/offset.

integer
1 to 1000

Maximum rows for limit/offset pagination. Do not combine with page/per_page.

integer
≥ 0

Zero-based row offset for limit/offset pagination. Do not combine with page/per_page.

Responses

Callback
Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json