Endpoint

Events

List events with current odds. Filters apply across endpoints; unknown values return 400 validation_failed with a machine-readable code in the response body.

GET/api/v1/eventsAuth: Required

List events with current odds from entitled sources. Default ordering is not guaranteed to be 'next upcoming'; pass dateFrom for future games.

Query / path parameters

sport: Sport code, defaults to football.
league: Optional league key for narrowing.
dateFrom: ISO-8601 kickoff lower bound. Use this to scope to upcoming games — default ordering does not guarantee 'next upcoming' first.
dateTo: ISO-8601 kickoff upper bound.
transport: rest (default) or live.
limit: Pagination size 1–500 (default 50).
offset: Pagination offset, 0-based (default 0).

Default ordering does not guarantee the next upcoming event first — always pass dateFrom when you need a future-only window.
To narrow by bookmaker, read /api/v1/events/{eventId}/odds with the bookmaker parameter; the event list itself has no bookmaker filter.

Request

curl "https://api.betspread.io/api/v1/events?sport=football&dateFrom=YOUR_UPCOMING_UTC_DATE&limit=25" \
  -H "Authorization: Bearer $BETSPREAD_API_KEY"

Replace YOUR_UPCOMING_UTC_DATE with an ISO-8601 UTC timestamp (e.g. 2026-12-01T00:00:00Z) that marks the start of the window you want.

Filters

sport

Sport code, defaults to football on /bookmakers.

transport

Product channel: rest (default) or live. Live requires plan entitlement; otherwise returns 403 live_not_enabled.

limit

Pagination size from 1 to 500 (default 50).

offset

Pagination offset, 0-based (default 0).

dateFrom / dateTo

ISO-8601 kickoff range filters. Use dateFrom to scope to upcoming games — default ordering does not guarantee 'next upcoming' first.

league

Optional league key for event list narrowing.

Ordering caveat

Default ordering does not guarantee "next upcoming" first — always pass dateFrom when you need a future-only window. Pair dateFrom with dateTo to scope to a tight window such as "the next 24 hours".

Example

For grouped odds on a single event use GET /api/v1/events/{eventId}/odds.