Get Sports Edge Observations
Pro-tier. Measures three 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 signals admission, including recent-flow rows rejected by its event, bucket, or total caps; in_play admits 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; emerging_pile is an additive post-compute projection of wider_holder rows with finite sharp_pct in [0.75, 0.85), holder_scan_complete=true, and a kickoff after its pinned projection cutoff. emerging_pile overlaps wider_holder, remains attributed to that source terminal and denominator, and is not holder-arrival history. 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-signals 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-signals membership result returns 503 with error.reason=read_model_warming. Category-resolution SQL errors, Redis coordination failures, observation-universe SQL errors, and primary-signals 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 means live-board work missed either an internal configured-scope deadline or the outer fair-wave deadline; both classify only already-started rows, so for the upcoming source read funnel.sports[].board_upcoming_status instead; 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; healthy emerging_pile requests may use the same snapshot. 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 page position; request-specific meta excluded; the opaque emerging_pile projection cutoff in next_cursor is not itself a validator input.
Read the cohorts
cohort is required.
wider_holdermeasures pre-game holder piles outside the funded route’s admission, with recent-flow rows that its caps rejected.in_playadmits only provider-confirmed live games. It fails closed when the live board, holder, or directional evidence is stale or unavailable.emerging_pileprojectswider_holderrows withsharp_pctin[0.75, 0.85),holder_scan_complete=true, and a kickoff after its pinned cutoff. It overlapswider_holderand adds no new work.
Read the rows
observation_onlyis alwaystrue.categoryis one of 14 sport buckets. Omit it to get all 14, withTable TennisandPickleball. Those two stay outside the funded projection.holder_scan_complete=falsemeans the pile is a lower bound. It cannot support a capital promotion.directional_statusisavailable,unknown_ungrouped,unknown_stale, orunavailable. Awider_holderrow stays emitted withunavailable. Anin_playrow is not emitted.degradedis snapshot-wide.truemeans an operational failure or an unknown completeness state made the snapshot partial.capacity_limitedrows do not set it.funnel.sports[]accounts for every input per sport.reconciledistrueonly wheninputequalsterminal_total. A mismatch is an operational fault, not an empty cohort.snapshot_as_ofis the snapshot completion time. A healthywider_holdersnapshot serves for about 180 seconds. Anin_playrequest never serves a snapshot older than about 30 seconds. A degraded snapshot serves for about 30 seconds.
Handle the 503
- Read
error.reasonon a503.read_model_warmingmeans a refresh is in flight, a compute deadline expired, or the provider-work admission is busy. - Retry this route only after
Retry-Afterorerror.retry_at. Do not add it to a shared rate-limit backoff. - A
503withouterror.reasonis the rate limiter outage. Retry afterRetry-After.
500 internal_error. A later board, holder, or price failure stays in a 200 with degraded=true. The compute deadline is about 25 seconds under the 30-second router timeout. A 408 has an empty body.
Handle the cursor
- Read
next_cursor. It is a signedseo_v2_cursor that pinssnapshot_as_of,cohort,rank, andcondition_id. - Send it only with the same
cohort. A cursor cannot cross cohorts. - A refreshed snapshot returns
400witherror.reason="cursor_expired". Request the first page again.
Cache the page
The 200 response carries a weakETag over the stable page payload. Request-specific meta is excluded. Send If-None-Match to get 304 Not Modified with an empty body. Both 200 and 304 set Cache-Control: private, no-cache, so revalidate before every reuse. A fresh compute reports meta.cost of 5. A cache hit reports 1.
Related
Get Sports Edge Signals returns the funded pre-game list.Authorizations
API key authentication. Send your key in the Authorization header as Bearer oxi_sk_live_.... Live keys require an active Pro 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 and the opaque emerging_pile projection cutoff inside next_cursor are excluded from validation.
Query Parameters
Observation cohort. wider_holder measures pre-game holder piles outside the funded route's exact raw signals admission. in_play admits only provider-confirmed live games and excludes stale or unavailable provider live-board, holder, or directional evidence. emerging_pile is a post-compute wider_holder projection for finite sharp_pct in [0.75, 0.85) with holder_scan_complete=true and a kickoff after its pinned projection cutoff; it overlaps wider_holder, is not an independent denominator, and is not arrival history.
wider_holder, in_play, emerging_pile 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 <= 100Server-authenticated opaque seo_v2_ cursor from next_cursor. Pins snapshot_as_of, cohort, rank, and condition_id; pre-deploy unsigned seo_ cursors are rejected, so clients must request the first page after this contract ships; emerging_pile cursors also pin the first-page projection_now cutoff so kickoff filtering cannot renumber continuation pages. Client edits fail closed; 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.