API ReferenceSports
Read a cross-venue sports price grid.
const url = 'https://data.predictefy.com/v1/sports/screen?marketType=moneyline&period=full&lineTeam=team1&sort=kickoff&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/screen?marketType=moneyline&period=full&lineTeam=team1&sort=kickoff&limit=50' \ --header 'Authorization: Bearer <token>'DARK by default. Requires READS_ENABLE_SPORTS and READS_ENABLE_SPORTS_SCREEN to be the literal true and a configured sports Redis client; otherwise the route is unmounted (404). Defaults render up to 50 rows over now minus 12 hours through now plus 7 days. Kickoff pages fetch only the selected page blocks; edge sorting uses every candidate. meta.asOf is the oldest served block clock, falling back to mirror refresh time when no market is projected. Example uses marketType=total. 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.
Screenable market type.
Canonical market period.
Allowed only when marketType=team_total; otherwise 400. team1 is home when both home/away identities are stated, else teamA. Spread always addresses team1 without this parameter. The default applies only to team totals.
Finite numeric line. Screen selects this line when the block has numeric lines; line-less blocks retain their null line.
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.
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.
Exact teamA.id or teamB.id; does not match display names.
Comma-separated display venues. Lowercased, trimmed and deduplicated before enforcing at most 12 distinct venues; each normalized name is 1..32 letters, digits or underscores. Omission uses all available venues.
Comma-separated average venues. Lowercased, trimmed and deduplicated before enforcing at most 12 distinct venues; each normalized name is 1..32 letters, digits or underscores. Omission uses all available venues.
Comma-separated venue:integer entries. Venue names match ^[a-z0-9_]{1,32}$. Weights are integers 0..10; at least one supplied effective weight must be positive. Zero excludes a venue from averages; unspecified venues use weight 1. Every weighted venue must belong to avgVenues when supplied. Duplicate venue entries use the last weight.
Kickoff ascending, or best row edge descending. Fixture ID breaks ties; rows without an edge sort last.
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
A screen row. An absent block remains market=null. snapshot_unavailable can accompany a row whose block read failed. final means the keyed markets used by the engine are closed; it is not independent official-result verification.
object
object
object
object
object
object
object
Predictefy computes average, normalized fair probability, edge, and hold. Edge is null whenever fair is null. Best is an eligible live, non-stale quote or null; unknown fees can select best on gross with edgeOnGross=true and net=null. Best does not promise a verified all-in execution cost.
object
One venue quote. Catalog and stale cells cannot be best. feeUnknown=true always has net=null. grossReason explains a null gross price; asOf is the source quote clock, not a freshness confirmation.
object
One venue quote. Catalog and stale cells cannot be best. feeUnknown=true always has net=null. grossReason explains a null gross price; asOf is the source quote clock, not a freshness confirmation.
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": { "marketType": "total", "period": "full", "line": 2.5, "lineTeam": null, "lines": [ { "line": 2.5, "venues": [ "a" ] }, { "line": 3.5, "venues": [ "b" ] } ], "selections": [ { "selection": { "key": "over", "kind": "over", "side": null, "team": null }, "cells": [ { "venue": "a", "marketId": "m-a", "outcomeId": "a-over", "selection": "over", "gross": { "probability": 0.5, "american": 100, "decimal": 2 }, "grossReason": null, "net": { "probability": 0.5, "american": 100, "decimal": 2 }, "feeBps": 0, "feeUnknown": false, "sizeAtPrice": 100, "asOf": "2026-09-19T12:00:00.000Z", "stale": false, "source": "live" } ], "best": { "venue": "a", "marketId": "m-a", "outcomeId": "a-over", "selection": "over", "gross": { "probability": 0.5, "american": 100, "decimal": 2 }, "grossReason": null, "net": { "probability": 0.5, "american": 100, "decimal": 2 }, "feeBps": 0, "feeUnknown": false, "sizeAtPrice": 100, "asOf": "2026-09-19T12:00:00.000Z", "stale": false, "source": "live" }, "avg": { "probability": 0.5, "american": 100, "decimal": 2 }, "fair": { "probability": 0.5, "american": 100, "decimal": 2 }, "edge": 0, "edgeOnGross": false }, { "selection": { "key": "under", "kind": "under", "side": null, "team": null }, "cells": [ { "venue": "a", "marketId": "m-a", "outcomeId": "a-under", "selection": "under", "gross": { "probability": 0.5, "american": 100, "decimal": 2 }, "grossReason": null, "net": { "probability": 0.5, "american": 100, "decimal": 2 }, "feeBps": 0, "feeUnknown": false, "sizeAtPrice": 100, "asOf": "2026-09-19T12:00:00.000Z", "stale": false, "source": "live" } ], "best": { "venue": "a", "marketId": "m-a", "outcomeId": "a-under", "selection": "under", "gross": { "probability": 0.5, "american": 100, "decimal": 2 }, "grossReason": null, "net": { "probability": 0.5, "american": 100, "decimal": 2 }, "feeBps": 0, "feeUnknown": false, "sizeAtPrice": 100, "asOf": "2026-09-19T12:00:00.000Z", "stale": false, "source": "live" }, "avg": { "probability": 0.5, "american": 100, "decimal": 2 }, "fair": { "probability": 0.5, "american": 100, "decimal": 2 }, "edge": 0, "edgeOnGross": false } ], "hold": { "average": 0, "byVenue": { "a": 0 } } } } ], "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" }}