API ReferenceSports
List fixture identities and available markets.
const url = 'https://data.predictefy.com/v1/sports/fixtures?limit=50';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://data.predictefy.com/v1/sports/fixtures?limit=50' \ --header 'Authorization: Bearer <token>'DARK by default. Requires READS_ENABLE_SPORTS to be the literal true and a configured sports Redis client; otherwise the route is unmounted (404). Kickoff keyset pagination without block reads. Every row has market: null, markets containing header block-availability descriptors, and unplaced counts. Same inclusive instant and date-precision window rules as screen. Serves owned Redis snapshots only, with no Core or venue request calls. Unknown query keys are ignored except the documented facets window rejection. Degraded responses preserve the last usable snapshot with honest stale flags. Catalog and stale cells are never best; unknown fees keep net null; edge is absent when fair is absent. final means keyed markets closed; fair, edge and hold are Predictefy calculations.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Exact canonical sport slug. Unknown valid values return an empty result.
Exact competition ID. Unknown valid values return an empty result.
Exact teamA.id or teamB.id; does not match display names.
ISO-8601 instant with seconds and timezone, or YYYY-MM-DD as UTC midnight. Defaults to now minus 12 hours. Exact kickoff endpoints are inclusive; date-precision fixtures compare eventDate to the inclusive normalized UTC endpoint days.
ISO-8601 instant or YYYY-MM-DD as UTC midnight. Defaults independently to now plus 7 days. Must be strictly after from, with a span at most 31 days. Inclusion uses the same inclusive instant/UTC-day semantics as from.
One venue, trimmed and lowercased. The header venues must include it. Comma lists are not accepted here.
Comma-separated fixture statuses: scheduled, live, final, postponed, cancelled. Whitespace is trimmed and duplicates removed. Omission includes all statuses. final means the engine keyed markets closed.
Maximum rows in a keyset page.
Opaque unsigned keyset cursor from nextCursor. Malformed or sort-incompatible cursors return VALIDATION_ERROR; no offset or signing key is needed.
Header Parameters
Section titled “Header Parameters”Send the exact returned ETag when repeating the same query. An exact match returns 304 only while healthy; degraded responses remain 200.
Responses
Section titled “Responses”Successful snapshot response.
object
object
object
object
object
Counts of unplaced markets by reason. Reasons absent from the source are omitted.
object
Screen and fixture-list metadata. asOf is the oldest actually served block builtAt, or the mirror refresh clock when no block is projected. unplaced sums only served fixture headers.
object
Missing or unrepresentable heartbeat clocks produce null heartbeatAt/lagMs and zero engine counts.
object
object
Quote age thresholds in milliseconds. These are applied before projection while engine or Redis liveness is degraded.
object
Counts of unplaced markets by reason. Reasons absent from the source are omitted.
object
Unsigned library keyset pagination. No offset or total. nextCursor is null at the end and is duplicated at the top level of paged responses.
object
Example
{ "success": true, "data": [ { "fixtureId": "f2", "sport": "soccer", "competition": { "id": "c", "name": "Cup", "timeZone": "UTC" }, "home": { "id": "b", "name": "Beta" }, "away": { "id": "a", "name": "Alpha" }, "teams": [ { "id": "a", "name": "Alpha" }, { "id": "b", "name": "Beta" } ], "kickoffAt": "2026-09-19T12:00:00.000Z", "kickoffPrecision": "exact", "eventDate": "2026-09-19", "status": "scheduled", "venues": [ "a", "b" ], "market": null, "markets": [ { "marketType": "total", "period": "full", "slot": null, "lines": [ 2.5, 3.5 ], "venues": [ "a", "b" ] } ], "unplaced": { "line_missing": 2 } } ], "meta": { "asOf": "2026-09-19T12:00:00.000Z", "degraded": false, "degradedReason": null, "engine": { "heartbeatAt": "2026-09-19T12:00:00.000Z", "lagMs": 17, "fixtures": 1, "blocks": 1 }, "index": { "refreshedAt": "2026-09-19T12:00:00.000Z", "fixtures": 1 }, "freshness": { "live": 30000, "day": 120000, "week": 1200000 }, "unplaced": { "line_missing": 2 } }, "page": { "limit": 50, "hasMore": false, "nextCursor": null }, "nextCursor": null}Headers
Section titled “Headers”Example
W/"pss1:f2:1789819200000"Weak snapshot validator. Screen/listing use the query fingerprint plus served fixture/revision pairs; fingerprintQuery excludes limit and cursor. Single-fixture and compare use W/"pss1:
Private response that requires revalidation before reuse.
No body. The exact weak ETag matches and the response is not degraded. Repeat the same query: fingerprintQuery excludes limit/cursor, and single-fixture/compare tags contain only fixture ID and revision. Degraded responses always return 200.
Headers
Section titled “Headers”Example
W/"pss1:f2:1789819200000"Weak snapshot validator. Screen/listing use the query fingerprint plus served fixture/revision pairs; fingerprintQuery excludes limit and cursor. Single-fixture and compare use W/"pss1:
Private response that requires revalidation before reuse.
Invalid query or fixture ID. Facets rejects from/to because its snapshot owns the window.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}Missing, invalid or revoked API key.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}The account's credit balance cannot cover this sports read's weight. Not retryable.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}The API key lacks the read scope this route requires. Not retryable.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}ROUTE_NOT_FOUND while the sports family is unmounted, or the screen flag is off.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}Request rate limit exceeded.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}Unexpected internal error; requestId identifies the failure.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}Retryable: the mirror has never loaded and cannot load, a single-fixture snapshot keeps changing across two read attempts, or authentication or metering storage is unavailable.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}