V1 / Reliability

Detect gaps. Recover from a fresh snapshot.

A fast feed is only useful if consumers can prove their state is current. Beta-0 favors explicit gaps and deterministic reconstruction over silent continuation: reconnects and sequence gaps require a new REST snapshot before deltas resume.

ORDERING

Sequence ownership

Each subscription has an explicit effective scope and a strictly increasing sequence. Consumers commit a sequence only after its message has been applied durably.

Expected next

Apply when the sequence equals the last committed value plus one.

Duplicate

Ignore an already committed message ID or sequence.

Gap

Pause application and begin fresh-snapshot recovery immediately.

Fresh snapshot

Atomically replace state before any later deltas resume.

DELIVERY

Ordered deltas, defensive consumers

Beta-0 delivers contiguous WebSocket deltas only after accepting the current REST snapshot position and matching scope. Consumers should deduplicate by message ID and make full-state replacements idempotent.

message_iddeduplicationUUID for one emitted message.
sequenceorderingPer-subscription ordering; the first relevant delta is 1.
effective_scopeownershipPrevents data outside the accepted filters from entering state.
schema_versioncompatibilityEvery REST body and WebSocket envelope declares version 1.
TIME

Three relevant clocks

observedAtRFC 3339When OddsLoom observed the provider state.
emitted_atRFC 3339When OddsLoom published the snapshot or frame.
consumer_received_atclient clockWhen your system received the frame; recorded by the consumer.

Use sequence for ordering. Use timestamps for freshness analysis. Provider clocks may be absent or skewed and are never invented.

STATE

Quote availability

OPENQuote may be consumed as current.
→
SUSPENDEDRetain the last quote but treat it as unavailable.
→
OPENThe same quote ID may reopen with replacement state.
OPENCurrent offer exists.
→
CLOSEDMarket or event reached a terminal condition.
→
REMOVEDDelete after an explicit odds.remove.

A correction is a replacement upsert at a higher sequence. Provider degradation is explicit, and last-known values are not presented as current after the freshness threshold.

RECOVERY

Reconnect and gap procedure

RECONNECT OR GAP→PAUSE DELTAS→FRESH REST SNAPSHOT→NEW SUBSCRIPTION→DECLARE POSITION→RESUME
  1. Stop mutating consumer-visible state when the connection closes or the next sequence is missing.
  2. Discard uncommitted deltas and atomically replace state with a fresh filtered REST snapshot.
  3. Open a new authenticated subscription with that snapshot’s position and matching filters.
  4. Resume only after the server accepts the current position.

There is no beta replay, backfill, historical API, or resume-from-committed-position path. A stale position is rejected with fresh_snapshot_required.

OPERATIONS / CANDIDATE SLOS

Targets to validate, not promises

These are candidate beta SLOs. They guide implementation and measurement, but are not customer commitments until measured and published as such.

processing freshnessp95 ≤ 2 seconds from source receipt to customer publication while the source connection is healthy.CANDIDATE
stale-state detectionMark a supported source degraded within 15 seconds of exceeding its source-specific heartbeat or refresh threshold.CANDIDATE
delivery availability99.5% monthly for snapshot and stream endpoints, excluding announced maintenance and upstream sportsbook outages.CANDIDATE
recoveryObtain a coherent snapshot and stream position within 10 seconds at the documented beta scope.CANDIDATE
correctnessNo known silent sequence gaps; corrections and removals are explicit and ordered.CANDIDATE

Upstream sportsbook availability is measured separately from OddsLoom delivery availability. No source-to-OddsLoom latency promise is made when a trustworthy source timestamp is unavailable.

Tell us where this breaks.

We want concrete feedback about sequence scope, fresh-snapshot recovery, market identity, and state transitions while the implementation is validated.

Request beta access →