Skip to main content
GET
List events

Authentication

Public — no authentication required. Provide X-Public-Key to receive personalized data (e.g. watchlist status).

Query parameters

integer
default:"1"
Page number.
integer
default:"20"
Results per page.
string[]
Fetch up to 50 specific events in the order you provide. Repeat the parameter for each UUID, for example eventIds=id1&eventIds=id2. Do not send a comma-separated list. When eventIds is present, the request returns all matching IDs on page 1; page and size do not limit the batch. Supply 1–50 valid, unique UUIDs. Omit eventIds to use normal pagination.
string
Filter by category (e.g. sports, crypto, politics).
string
Filter by subcategory.
string
Filter by status: open, paused, closed, resolved, cancelled. Defaults to open (includes paused) when omitted.
string
Search events by title keyword.
string
default:"USD"
Currency for prices: USD or NGN.
Return trending events only.
boolean
Return watchlisted events only (requires X-Public-Key).
string
Filter by event series slug (e.g. crypto-btc-1h).
string
Filter by sports game slug to fetch all related events (H2H, Goal Spread, Total Goals) for a match (e.g. bm-game-20260524-mci-avl). Only applies to sports events.
boolean
Return only events whose markets can be used as combo legs. Composes with every other filter — for example, sportGameSlug=bm-game-20260524-mci-avl&comboEligible=true lists one fixture’s combinable markets.

Example request

Status notifications

Subscribe to Event and market status on the WebSocket lifecycle channel to learn when an event or one of its child markets changes status. Refresh the event to obtain its current state.

Fetch multiple events by ID

Pass eventIds once for each UUID. The response keeps the same order as the IDs in the request. The batch accepts 1–50 unique UUIDs. Other filters such as status, category, and currency still apply. The default status filter includes open and paused events, even when IDs are supplied. Set status=closed or status=resolved to fetch events with those statuses. If one or more requested events are not returned, missingEventIds lists those IDs. An ID can be unavailable or excluded by an active filter. The field is omitted when all requested events are returned or when you do not pass eventIds.
The response contains the two events that were found, in request order, plus the ID that was not returned:

Response

array
List of event objects.
object
array
Requested event IDs that were not returned because they were unavailable or excluded by the active filters. Present when one or more IDs were not returned.