API ReferenceSports
Compare all lines of one fixture block.
const url = 'https://data.predictefy.com/v1/sports/fixtures/example/compare?marketType=moneyline&period=full&lineTeam=team1';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/example/compare?marketType=moneyline&period=full&lineTeam=team1' \ --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). Returns all projected lines in ascending order. Without projection options, the healthy answer equals diffBlocks(undefined, block, slot)[0].block, the stream first replacement. Degraded cells are re-marked before projection. A failed command for an advertised block returns data: [] with degraded metadata; a genuinely missing or corrupt block returns SPORTS_BLOCK_NOT_FOUND. 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”Path Parameters
Section titled “Path Parameters”Canonical mirrored fixture ID. Invalid characters or more than 128 characters return VALIDATION_ERROR.
Query Parameters
Section titled “Query Parameters”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.
Accepted and validated as a finite number, but does not filter comparison output. Compare returns every projected line.
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.
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
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
Single-fixture and compare metadata. rev is the fixture-wide change stamp. Repeated concurrent revision changes return retryable SPORTS_SCREEN_UNAVAILABLE rather than mismatched headers and prices.
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
Example
{ "success": true, "data": [ { "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 } } }, { "marketType": "total", "period": "full", "line": 3.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": "b", "marketId": "m-b", "outcomeId": "b-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": "b", "marketId": "m-b", "outcomeId": "b-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": "b", "marketId": "m-b", "outcomeId": "b-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": "b", "marketId": "m-b", "outcomeId": "b-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": { "b": 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 }, "rev": 1789819200000 }}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" }}The fixture is missing, the addressed block is absent, undecodable or identity-mismatched, or the family is unmounted. A failed Redis command for an advertised block instead produces an empty degraded 200 response.
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" }}