Markets

List observation-only sports-edge cohorts

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.

get/api/v1/sports-edge-observations

Query parameters

cohort'wider_holder' | 'in_play' | 'emerging_pile' required

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.

categorystring

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.

limitinteger

Page size.

cursorstring

Server-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.

Headers

If-None-Matchstring

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.

Response

Observation-only sports cohort with a snapshot-wide operational/unknown-completeness degraded verdict and accountable funnel

object'list' required
has_moreboolean required
next_cursorstring nullable required
snapshot_as_ofstring date-time required

Completion time of the shared observation snapshot pinned by the cursor.

degradedboolean required

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.