Skip to main content
GET
List events

Query Parameters

​
stage
enum<string>[]

Event stage (exact, case-sensitive values), matched against the event's stage: a match-less fixture's own, or the parent match's. Multi-value: repeated keys or CSV, OR-ed. Unknown value → 400 invalid_stage.

Available options:
group,
r32,
r16,
quarter_finals,
semi_finals,
third_place,
final,
fifa_friendlies,
ucl,
uefa_europa_conference_league
​
group
string[]

Group label, e.g. A (1–8 upper-case letters or digits, case-sensitive), matched against the event's group: a match-less fixture's own, or the parent match's. Multi-value: repeated keys or CSV. Malformed → 400 invalid_group.

Pattern: ^[A-Z0-9]{1,8}$
​
team
string[]

Team code(s): 3 letters, case-insensitive (upper-cased by the server). Each value matches the parent match's teamA or teamB. Multi-value: repeated keys or CSV. Matches only events bound to a match — match-less head-to-head events (e.g. most tennis) are not matched even though they carry teamA / teamB. Malformed → 400 invalid_team.

Pattern: ^[A-Za-z]{3}$
​
tag
string[]

Tag slug(s), exact and case-sensitive (e.g. premier-league). An event matches when it carries at least one of the given active tags. Multi-value: repeated keys or CSV. Malformed (e.g. upper-case) → 400 invalid_tag.

Pattern: ^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$
​
from
string

Dual mode, decided by the value's shape.

  • Digits only (0–1000000): 0-based start position in the sorted list. from alone returns positions [from, from + 100), with the header X-Events-Window-Capped: 100. Cannot be combined with page / limit (400 ambiguous_pagination).
  • Anything else: parsed as a date — inclusive lower bound on the event's start time (scheduledAt). Send a full ISO-8601 timestamp with Z or an explicit offset. It replaces the default "not already started" floor, so a past date also returns started events that still have open markets. Events with no start time never match a date bound. Combines with page / limit when it starts YYYY-MM-DD (a date, optionally with a time); any other value beside page / limit is 400 ambiguous_pagination.

Beware: a 4-digit year such as 2026 is read as a position, and an epoch-milliseconds value is rejected. Unparseable or above 1000000 → 400 invalid_from.

​
to
string

Dual mode, like from.

  • Digits only: exclusive end position. A to − from span above 100 returns only the first 100 events from from, with the header X-Events-Window-Capped: 100; to alone returns [0, min(to, 100)); to equal to from returns an empty list. Cannot be combined with page / limit.
  • Anything else: parsed as a date — inclusive upper bound on the event's start time. Combines with page / limit when it starts YYYY-MM-DD, like from.

to before from → 400 invalid_range. Unparseable or above 1000000 → 400 invalid_to.

​
sort
enum<string>

Ordering (single value).

  • absent: chronological — the earliest kickoff among the event's open markets (the event start when a market has none) first, then title, then id. With q: relevance. On the closed view there is no kickoff anchor, so the default order is by title.
  • trending: 24 h volume, highest first.
  • coming_soon: only events with a market that has not opened yet; next opensAt first.
  • ending_soon: only events with a market still to close; next closesAt first.
  • starting_soon: only events with a future kickoff; next kickoff first.
  • live: only events currently in play; most recent kickoff first.

An explicit sort overrides relevance under q. Unknown value → 400 invalid_sort (error.details.allowed).

Available options:
trending,
coming_soon,
ending_soon,
starting_soon,
live
​
vertical
string[]

Vertical slug(s) — see GET /api/verticals. crypto selects crypto markets. Open set: an unknown slug matches nothing, a malformed one → 400 invalid_vertical; soccer is folded to football. Repeated keys or CSV, ≤20 values.

​
asset
string[]

Crypto coin slug(s) — data-driven (btc, eth, …), plus the reserved others (crypto markets with no identifiable asset). A well-formed but unknown slug matches nothing (200, empty list); a MALFORMED slug returns 400 invalid_asset. Repeated keys or CSV, ≤20 values.

​
cadence
enum<string>[]

Crypto window cadence slug(s). CLOSED set — an unknown value returns 400 invalid_cadence. Matches events carrying at least one windowed market of that cadence. Repeated keys or CSV, ≤20 values. For calendar-month, annual or one-time products use frequency (monthly, annual, one-time) instead.

Available options:
5-minute,
15-minute,
30-minute,
hourly,
6-hour,
daily,
weekly
​
closed
boolean

true: the settled / finished tab — events with no open-view market and at least one SUSPENDED, CLOSED, PENDING_RESOLUTION, DELAYED, DISPUTED, RESOLVED or VOIDED market, not in play and not postponed; their markets[] carry those closed-status markets. false (default): the open view. Accepts true/false/1/0/yes/no/on/off (case-insensitive); an empty value is ignored; anything else → 400 invalid_closed. Cannot be combined with status (400 ambiguous_status).

​
kind
enum<string>

match: events bound to a match. tournament: events with no parent match — outright questions and match-less fixtures (e.g. most tennis and baseball). Single value; unknown → 400 invalid_kind.

Available options:
match,
tournament
​
page
integer
default:1

1-based page number. Returns positions [(page − 1) × L, page × L) where L = min(limit, 100); default 1 when only limit is given. Walk pages until one comes back empty. Digits only, ≥ 1, otherwise 400 invalid_page; an offset above 1000000 → 400 invalid_page. Combines with ISO-8601 from / to dates that start YYYY-MM-DD; any other from / to, numeric included, is 400 ambiguous_pagination.

Required range: x >= 1
​
limit
integer
default:100

Page size. A response carries at most 100 events: a larger value is served as 100 — it is not rejected — pages then step by 100, and the response carries X-Events-Window-Capped: 100. Default 100. Digits only, ≥ 1; 0, negative or non-numeric values → 400 invalid_limit. Previously a response held up to 500 events and a limit above 500 was 400 invalid_limit.

Required range: x >= 1
​
status
enum<string>

open (the default view: events with ≥1 tradeable market, or currently in play) or closed (the settled set: no tradeable market and ≥1 closed market). Omit it for the default view. Single value; unknown → 400 invalid_status; together with closed → 400 ambiguous_status. Combinations that cannot match — status=closed with sort=ending_soon, starting_soon, coming_soon or live, or with preMarket=true — return an empty list, not an error.

Available options:
open,
closed
​
preMarket
boolean

true: only events with ≥1 visible market in PRE_MARKET (orders accepted, matching deferred — a TRADEABLE state, not a read-only one). false: only events with none. Absent: no constraint. PLATFORM-WIDE, not crypto-only: PRE_MARKET means the same thing in every vertical, and the two values partition the whole catalogue. ?vertical=crypto&preMarket=true matches the crypto.preMarket count on GET /api/verticals. Only markets past their reveal time count, so a scheduled-but-unrevealed market never surfaces an event here. Accepts true/false/1/0/yes/no/on/off (case-insensitive); a bare ?preMarket with no value is ignored, like ?closed=. Anything else → 400 invalid_pre_market.

​
predictionType
enum<string>[]

Shape of the price question. rise-fall = no operator-set level; the reference is derived from the market itself (a window's pinned open price, the previous month's close) and the outcome is a direction. above-below = the operator set a level and the question is whether the metric clears it. Multi-value (CSV or repeated keys, ≤20). STRICT: an unknown value → 400 invalid_prediction_type. CRYPTO events only (events in the crypto vertical; a crypto rule on an event filed under another vertical does not match). More than 20 values → 400 too_many_prediction_type.

Available options:
rise-fall,
above-below
​
frequency
enum<string>[]

How often the market recurs. Multi-value (CSV or repeated keys, ≤20). STRICT: an unknown value → 400 invalid_frequency (closed set, like scope/cadence). Matches events carrying ≥1 visible market of one of the given frequencies. Not a rename of ?cadence=: it folds TWO mechanisms — the series grid step (5-minute…weekly) and the product's own declared window (monthly = a calendar month, midnight to midnight US Eastern time; one-time = a single deadline). ?cadence= sees only the first and stays available as the low-level knob. annual is a valid value, but no market uses it today, so it matches no events.

Available options:
5-minute,
15-minute,
30-minute,
hourly,
6-hour,
daily,
weekly,
monthly,
annual,
one-time
​
scope
enum<string>[]

Market-scope filter: closed scope vocabulary (games, futures, totals, handicap, correct-score, player-props, team-props, awards, specials) — the slugs /api/verticals advertises per vertical/competition. Multi-value (CSV or repeated keys, ≤20). STRICT: an unknown value → 400 invalid_scope (closed set, unlike vertical). Matches events carrying ≥1 bettable market of the scope.

Available options:
games,
futures,
totals,
handicap,
correct-score,
player-props,
team-props,
awards,
specials
​
subcategory
string[]

Sub-topic slug(s) — the values GET /api/verticals lists in each vertical's subcategories[]. A subcategory slug is globally unique and implies its vertical, so no ?vertical= is needed. Each event has at most one subcategory. Open set: an unknown slug matches nothing; a malformed one → 400 invalid_subcategory. Repeated keys or CSV, ≤20 values.

​
competition
string[]

Competition slug(s) — see GET /api/verticals. Matches on the effective competition (the match's, else the event's own). Unknown slugs match nothing; a malformed slug → 400 invalid_competition. Repeated keys or CSV.

​
q
string

Free-text search. Matches event title (substring), team (code exact / name substring) and active tag name (substring) — the same arms as /api/search/events, so the page and the header dropdown agree. Composes with EVERY other filter (a sort mode's implicit time filter included: ?q=x&sort=live ranks the live subset). With q and no sort, ordering is RELEVANCE (exact > prefix > substring; direct hit > tag-only; similarity tiebreak); an explicit sort overrides. Adds total, openMarketCount, totalMarketCount and facets.competition to every page of the response. Trimmed; max 64 chars (400 query_too_long); empty = absent. A repeated q → 400 invalid_query.

Maximum string length: 64

Response

OK — at most 100 events. total, openMarketCount and totalMarketCount on the first page of every listing and on every page with q; facets only with q.

Response of GET /api/events: at most 100 event rows. total, openMarketCount and totalMarketCount are present on the first page of every listing and on every page when q is supplied; facets only when q is supplied.

​
events
object[]
required

Event rows of the requested page — at most 100. An empty array means you are past the last page.

​
total
integer

The number of events matching every filter of the request — q, ISO-8601 from / to date bounds and the implicit filter of sort=coming_soon / ending_soon / starting_soon / live included; sibling long-crypto periods counted once — independent of page / limit and of numeric from / to. Present on the first page of every listing (page=1, from=0, or no page and no digits-only from) and on every page when q is supplied; absent from later pages. Optional even there: when it cannot be computed in time, a first page is answered without it and without openMarketCount / totalMarketCount (a q request fails instead). Not a stop signal — keep paging until a page comes back empty.

Example:

3

​
openMarketCount
integer

Without scope: the sum of the rows' openMarketCount over the total events, so 0 on status=closed. With scope: the number of markets of the requested scopes that the scope filter admits on the requested view — not the sum of the rows' own counters. Present whenever total is.

Example:

7

​
totalMarketCount
integer

Without scope: the sum of the rows' totalMarketCount over the total events — the count to show on status=closed, where openMarketCount is 0. With scope: the same number as openMarketCount. Present whenever total is.

Example:

9

​
facets
object

Present only when q is supplied: per-competition counts of the matched set.