API ReferenceSports
List sports competitions.
const url = 'https://data.predictefy.com/v1/sports/competitions';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/competitions \ --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). Sorted by ID from facets metadata joined with market counts and distinct venues. Inactive and zero-count competitions are included. No country, gender, age-grade or external source IDs are emitted. 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.
Responses
Section titled “Responses”Successful snapshot response.
object
Snapshot competition metadata and summed market counts. Inactive and empty competitions remain visible. Country, gender, age-grade, and source identities are not emitted.
object
Facets/competitions use the facets snapshot clock when available; teams uses the mirror refresh clock. Degraded reads retain the last usable snapshot. A cold index that cannot load returns 503.
object
Missing or unrepresentable heartbeat clocks produce null heartbeatAt/lagMs and zero engine counts.
object
object
Example
{ "success": true, "data": [ { "id": "c", "sport": "soccer", "name": "Cup", "active": true, "venues": [ "a", "b" ], "count": 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 } }}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" }}