List Events

get

https://api.sportsstack.io/api/v1/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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

season_year

integer

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

week

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)

season_type_agnostic_week

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

day

string

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

month

string

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

calendar_year

string

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

year

string

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

season_type

string

Season type (PRE / REG / POST)

status

string

enum

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

Allowed:

active

boolean

Defaults to false

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

aggregator

string

enum

Filter active event discovery by odds aggregator (for example kalshi or polymarket). Requires active=true.

Allowed:

league_id

string

required

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

participant_id

uuid

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

team_id

uuid

Filter events containing this team common_model_id.

player_id

uuid

Filter events containing this player common_model_id.

start_date

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.

end_date

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.

return_source_id_format

string

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

include_scoreboard

boolean

Defaults to true

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

include_source_mappings_by_source

boolean

Defaults to false

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

source_mapping_provider

string

Optional provider-family filter for source_mappings_by_source (for example, sportradar, opticodds, sportsdataio, espn).

source_mapping_source

string

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

page

integer

≥ 1

Defaults to 1

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

per_page

integer

1 to 1000

Defaults to 100

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

limit

integer

1 to 1000

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

offset

integer

≥ 0

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

Responses

Callback

200Event Response

400Bad Request

401Unauthorized

404Not Found