Get Sports Edge Observations
Insider-tier. Measures two explicitly observation-only Polymarket sports cohorts without changing or feeding GET /api/v1/sports-edge-signals: wider_holder measures pre-game holder piles outside the funded route’s exact raw slate admission, including recent-flow rows rejected by its event, bucket, or total caps; in_play admits only provider-confirmed live games and fails closed when the provider live-board snapshot is stale or unavailable or holder/directional evidence is stale or unavailable. Every row carries observation_only=true, provider/holder freshness and completeness fields, and the response carries a required snapshot-wide operational/unknown-completeness degraded boolean plus an accountable per-sport funnel over a closed 25-value terminal-reason vocabulary. Omitted or blank category selects all 14 registered observation sport buckets, including Table Tennis and Pickleball; those two remain outside the funded sports projection. All category and all-sports cache scopes share one global observation provider-work admission, so distinct scope keys cannot multiply concurrent provider fanout. One absolute ~25s compute deadline covers cache coordination, board/universe and primary-slate membership reads, holder cache/provider work, price/metadata evaluation, and directional reads, leaving ~5s below the public router timeout for funnel reconciliation, cleanup, and response transport. A shared pre-holder stage deadline jointly bounds those database reads and board reconciliation to the smaller of 12s or half of the absolute budget remaining when that stage starts, preserving holder/post-holder opportunity; board reads use bounded fair waves and cold holder admission gives each represented canonical sport one row before any sport repeats. Single-flight refresh contention, global provider-work admission contention, absolute deadline exhaustion before a usable cache, or pre-holder stage expiry before a usable stored universe or primary-slate membership result returns 503 with error.reason=read_model_warming. Category-resolution SQL errors, Redis coordination failures, observation-universe SQL errors, and primary-slate membership query failures return 500 internal_error instead. Once a usable universe exists, later operational or unknown-completeness board, holder, or price/metadata failures are retained as explicit terminal reasons in a degraded 200 response with degraded=true: board_source_unavailable is a completed board-source failure, board_deadline_unavailable is fair-wave deadline exhaustion, provider_unavailable is an attempted holder-provider failure, and holder_deadline_unavailable is holder-stage deadline exhaustion. Directional incompleteness is cohort-specific: a wider_holder row remains emitted with terminal wider_holder_emitted and directional_status=unavailable, while an in_play row fails closed with terminal in_play_directional_unavailable. capacity_limited records intentional bounded provider-work admission in the funnel and does not by itself set degraded=true. Healthy wider_holder requests may reuse a snapshot for ~180s; in_play never serves a cached observation snapshot older than ~30s, and degraded snapshots use ~30s. The ETag is a weak semantic validator over the stable page payload, including next_cursor, with request-specific meta excluded.
cohort:
wider_holdermeasures current graded-holder consensus without requiring recent graded whale flow.in_playmeasures only provider-confirmed live games. Stale or unavailable live-board, holder, or directional evidence fails closed and emits no observation.
observation_only: true. Never route these rows to an order executor. This endpoint does not feed Sports Edge Signals or Pick of the Day.
Omit category to evaluate all 14 observation sports. The observation registry includes Table Tennis and Pickleball, but both remain outside the 12-sport funded projection. category=table-tennis, category=table tennis, and category=pickleball resolve through the same canonical taxonomy as their title-cased bucket names; a non-sport category returns an empty list.
For an all-sports request, board reads run in bounded fair waves so one slow source cannot block every later sport. Cold holder admission gives each represented canonical sport a first-candidate attempt before any sport repeats. This preserves evaluation breadth; it does not guarantee an emitted row when that sport’s candidates fail a terminal gate.
All category and all-sports cache scopes share one global observation provider-work admission. Independent scope keys cannot multiply concurrent holder and price fan-out against funded provider traffic.
For in_play, provider event_status is authoritative when present: Live and Paused count as in progress, while Ended does not. The legacy score overlay is consulted only when event_status is absent.
200 response includes a required top-level degraded boolean. It is true when an operational failure or unknown completeness state made the snapshot partial. Treat it as the snapshot-wide verdict: it can remain true even when the per-sport funnel cannot show the same failure because each input receives exactly one terminal reason.
The response also includes that per-sport funnel. For each evaluated sport, input must equal terminal_total; sparse terminal reason counts explain why candidates were emitted or excluded. capacity_limited is intentional bounded admission: it remains fully accounted in the funnel and does not by itself set degraded: true. board_upcoming_configured distinguishes a sport with no applicable upcoming-board source from a configured source that is unavailable.
A healthy wider_holder request can reuse a snapshot for about 180 seconds. An in_play request never serves a cached observation snapshot older than about 30 seconds. Degraded snapshots use the shorter, about-30-second lifetime for both cohorts.
Directional degradation is cohort-specific. A wider_holder candidate can remain emitted with directional_status: "unavailable" and terminal reason wider_holder_emitted. An in_play candidate fails closed instead and is counted under in_play_directional_unavailable.
The route reserves about 25 seconds for one compute attempt. Single-flight refresh or global provider-work admission contention, or the deadline elapsing before a usable cache, universe, or exact raw funded-slate membership result exists, returns JSON 503 rate_limit_unavailable with error.reason: "read_model_warming". Category-resolution SQL errors, Redis coordination failures, observation-universe SQL errors, and primary-slate membership SQL errors return JSON 500 internal_error. Once a usable universe exists, later unfinished board, holder, price, or metadata work is represented in a degraded 200 funnel instead of becoming a route-wide error.
Pagination uses the endpoint-specific seo_ cursor. Cursors are pinned to snapshot_as_of and the selected cohort, so you cannot reuse one across cohorts or after its snapshot refreshes.
Successful responses return a weak semantic ETag. It covers the stable page payload, including next_cursor, but excludes request-specific meta. Send it back as If-None-Match with the same query to receive 304 Not Modified with an empty body when that stable payload is unchanged.
Malformed typed query values, such as limit=abc, return the standard JSON 400 bad_request envelope. Read error.param when it is present; otherwise use error.message.
Like other public API routes, this endpoint is also subject to the 30-second transport timeout. If that outer timeout is reached, it returns 408 Request Timeout with an empty body. Check the status before parsing JSON.Authorizations
API key authentication. Send your key in the Authorization header as Bearer oxi_sk_live_.... Live keys require an active Insider subscription and return live data.
Headers
Conditional GET using a previous weak semantic ETag. Matching stable payloads return 304 Not Modified with an empty body; request-specific meta is excluded from validation.
Query Parameters
Observation cohort. wider_holder measures pre-game holder piles outside the funded route's exact raw slate admission. in_play admits only provider-confirmed live games and excludes stale or unavailable provider live-board, holder, or directional evidence.
wider_holder, in_play Optional canonical sport bucket. Omitted or blank selects all registered sports. Raw provider categories resolve through the canonical taxonomy, including table-tennis or table tennis to Table Tennis and pickleball to Pickleball; a non-sport category returns an empty list.
Page size.
1 <= x <= 100Opaque seo_ cursor from next_cursor. Pins snapshot_as_of, cohort, rank, and condition_id. It cannot cross cohorts; a refreshed snapshot invalidates it with 400.
Response
Observation-only sports cohort with a snapshot-wide operational/unknown-completeness degraded verdict and accountable funnel
"list"Completion time of the shared observation snapshot pinned by the cursor.
True when an operational failure or unknown provider-board, holder, directional, reconciliation, or internal completeness state made this snapshot partial. This is snapshot-wide and can retain degradation that the funnel's one-terminal-per-input accounting cannot represent. Intentional bounded capacity_limited rows remain fully accounted in the funnel and do not by themselves set this field.
Per-sport accountable funnel for the full observation snapshot, returned on every page.