# Following each event's state

> Whether each event is still on, from two free routes: the snapshot, the log of changes, the recipe for a listing and the windows behind started.

## What the two routes say

`GET /v2/events/state` gives each event's state now, and `GET /v2/events/changes` gives every change since a point you hold, in order. The state is the fixture's, judged across every bookmaker and exchange we read, not only yours: an event your bookmakers stop pricing stays `scheduled` while it is on.

Whether your bookmakers price an event is raw's answer (`/v2/odds/raw?bookmakers=`). Build your listing from raw, and use these two routes for each event's fate.

Both cost 0 tokens, need a key and count against your account's rate limits. They answer in the envelope only, so `format` is a 400.

## The states

Every row carries one `state`:

- `scheduled`: not known to be over or called off. It may have no prices right now: raw answers that.
- `started`: pre-match is over, because it was seen in play, or its kick-off plus K (the windows below) passed with no venue listing it pre-match. It is not a claim the event was played. It returns to `scheduled` (`returned`) if venues list it pre-match again, as for a late or moved start; a `kickoff` change follows when the time moved.
- `merged`: a duplicate of the event in `merged_into`, always the final one.
- `gone`: called off before kick-off by every venue that listed it, confirmed. It is not sent yet, and the changelog will give the date it starts. Until then a called-off event reads `started` after its kick-off, and one called off inside K of kick-off reads `started` either way. `reason` is `null` for now.

## The changes

Each change carries `seq`, `at`, `change` and the event's whole row in `event`. `change` is one of:

- `listed`: first seen, `scheduled`, or `started` when first seen in play
- `kickoff`: a new kick-off time; `from_commence_time` is the old one
- `descriptors`: a public field moved (`previous_ids` included); `from_descriptors` holds the old values
- `started`, `returned` (back to `scheduled`) and `merged`
- `unmerged`: a merge undone, so the id is its own fixture again
- `regions`: a region joined or left the event's `regions` (`regions_added`, `regions_removed`), outside `uk` only
- `gone` and `split` (`split_to` or `split_from`): not sent yet

## Snapshot, then follow

Walk every page of `/v2/events/state` with the `region` and filters you will use on `/changes`, and keep the first page's `meta.since`. A page holds up to 1,000 rows in id order; pass `meta.next_cursor` as `cursor` for the next one (there is no `X-Next-Cursor` header, and a cursor expires 300 s after it was issued). Store each row with its `seq`.

`states` defaults to `scheduled`. Any other value needs `eventIds`, or a kick-off window of at most 7 days. `eventIds`, at most 50, is one page in all four states: each id's own row, plus the final event each merged id became, whatever your filters. Look up every id raw serves that your snapshot lacks this way.

Then, every ~30 s, call `/v2/events/changes?since=` with the same `region` and filters. While `meta.more` is true, call again at once with `meta.next_since` (a page can be empty while `more` is true); then store `meta.next_since`. A call returns up to 1,000 changes by default, 5,000 at most.

Use the snapshot's filters exactly. A kick-off window on `/changes` selects on the event's kick-off at the time of each change, so an event that enters a moving window as time passes sends no change: fix the window and snapshot again to move it, or filter on your side.

Snapshot, look up, follow:

```
# 1. Snapshot: every scheduled football event, a page at a time; keep the FIRST page's meta.since
curl --compressed -s -H "Authorization: Bearer $ODDSRELAY_KEY" \
  "https://api.oddsrelay.io/v2/events/state?region=uk&sports=soccer"

# 2. Any ids you hold, at most 50, in all four states: a merged id also returns the event it became
curl --compressed -s -H "Authorization: Bearer $ODDSRELAY_KEY" \
  "https://api.oddsrelay.io/v2/events/state?region=uk&eventIds=$EVENT_IDS"

# 3. Every ~30 s: what changed since, with the snapshot's region and filters; keep meta.next_since
curl --compressed -s -H "Authorization: Bearer $ODDSRELAY_KEY" \
  "https://api.oddsrelay.io/v2/events/changes?region=uk&sports=soccer&since=$SINCE"
```

## Applying changes

For every change whose `seq` is above the `seq` of the row you hold, or for an id you hold no row for, replace your row with the change's `event`, whatever its `change` value, including values you do not know yet. Applying one twice is harmless: the highest `seq` wins.

If raw serves an id the changes have not named within 2 minutes, look it up with `eventIds`.

Follow the log:

```
// state: Map of event id -> row, from your snapshot. since: the snapshot's first meta.since.
// get(path): your keyed GET, returning the parsed reply.
async function follow(state, since, query) {
  for (;;) {
    const page = await get(`/v2/events/changes?${query}&since=${since}`);
    for (const c of page.data) {
      const held = state.get(c.event.id);
      if (!held || c.seq > held.seq) state.set(c.event.id, { ...c.event, seq: c.seq });
    }
    since = page.meta.next_since;
    if (!page.meta.more) return since; // store it; call again in ~30 s
  }
}
```

## Listing from raw

- Add an event to your listing when raw serves it with your `bookmakers`, and keep it while its state is `scheduled`, even when raw has no prices for it right now.
- Hide it, but keep its row, while it is `started`, `gone` or `merged`, and show it again when a later change makes it `scheduled` (`returned`, `unmerged`).
- Take prices from `/v2/odds/raw` with your `bookmakers`, and never show them under an id whose state is not `scheduled`. Raw's `meta.removed` reason `removed`, or a bookmaker leaving, means no prices now, never called off. When raw's `removed_since` is later than your `updatedSince`, read raw in full once.
- On `merged`, move your row and prices to `merged_into`. If you hold no row for it, fetch it with `eventIds=` and follow `merged_into` until a row is not `merged`; if you filter `/changes` by `eventIds`, add it there. On `unmerged`, show the id by its own state and price it from raw under its own id.
- A `scheduled` row whose kick-off has passed is not yet confirmed started: a pre-match listing hides it at its own cut-off and keeps the row.

## Which events are covered

The routes cover every id raw serves in the region; an id only a matched board serves comes back in `meta.unknown_ids`. An id raw serves appears here within 75 s. If an id is in `unknown_ids` while this reply's `X-OddsRelay-Version` is below the raw page's, it is not recorded yet: ask again. If it is still unknown after that, it is not tracked yet (a new listing in its first minute, a race in its first 10 minutes, or a race of fewer than 2 runners): ask again in 60 s, and treat it as `scheduled` from raw meanwhile.

`region` is one code, never a list, read as raw reads one: `uk` when missing, and every region raw serves (`/v2/regions` lists yours). `since` tokens belong to one lane, `uk` or every other region. A fixture listed in both can have a row in each, and the two can briefly differ, so keep one state store and one `since` per region you read.

An event belongs to every region whose reply lists it, for its whole life: show it there while it is `scheduled`. `regions` says where venues listed it in the last 30 minutes (always `["uk"]` in `uk`), so never hide an event because a code left `regions`.

## Duplicates and new ids

- A fixture moved by more than its sport's match window and 12 h can take a new id with no link, for now. The old id stays `scheduled` with no prices and reads `started` at its old kick-off plus K, and the new id arrives as `listed`. A smaller move keeps the id and sends `kickoff`.
- A restart of our matching can list an event again under a second id, for now. The old id stays `scheduled` with no prices until its kick-off plus K, unless we link the two with `merged`.
- Some fixtures are listed as two ids at different kick-offs, or at the same minute under two spellings. Both stay `scheduled` until we link them or their own kick-off ends them. Two `scheduled` ids in one region with the same `sport_key`, sides and `commence_time`, only one of which raw serves, are one fixture: show the one raw serves.
- Never join two ids at different kick-offs yourself: doubleheaders, series and rematches are different fixtures. We link true duplicates with `merged`.
- A placeholder side renamed (Qualifier to a player), or a race whose field changed, can take a new id; show the one raw serves. Raw can still carry one venue's row with a wrong date under an id: trust the state.

## The windows

K: a pre-match listing that ends this close to kick-off counts as the kick-off. G: the grace after kick-off used to confirm. C: the most we wait for a venue still listing an event. They are floors for now, and measured values per sport will replace them from a date the changelog gives, so treat when an event reads `started` as something that can change.

- Football, handball, rugby union, rugby league, American football, ice hockey, basketball and volleyball: K 15 min, G 60 min, C 60 min
- Baseball and cricket: K 15 min, G 4 h, C 3 h
- Tennis and badminton: K 15 min, G 2 h, C 6 h
- Table tennis: K 10 min, G 1 h, C 3 h
- Darts and snooker: K 15 min, G 2 h, C 4 h
- MMA and boxing: K 15 min, G 3 h, C 8 h
- Esports: K 15 min, G 2 h, C 2 h
- Golf matchups: K 15 min, G 3 h, C 4 h
- Any other sport but racing: K 15 min, G 60 min, C 60 min
- Horse and greyhound racing: K 15 min, for an abandonment mid-card only

## Errors and flags

- 400 `missing_param`: `/changes` without `since`. 400 `bad_request`: a malformed `since`, an unknown or repeated parameter, a list in `region`, or `format`
- 403 `sport_not_in_plan`: a `sports` value outside your account's scope
- 404 `unknown_region`: a region the routes do not answer. For one you were reading, keep your rows and `since` and retry in 60 s
- 410 `since_expired`: the log keeps 14 days, and `oldest_since` is its oldest point. Snapshot again, then look up with `eventIds` every id you hold that the new snapshot lacks before you hide it
- 429: your account's rate limit; wait the Retry-After seconds
- 503 `temporarily_unavailable`: retry with the same `since`
- While `meta.stale` or `meta.verdicts_held` is true, keep applying changes, and infer nothing from an event's absence

Source: https://oddsrelay.io/docs/guides/event-state · the API contract: https://oddsrelay.io/openapi.json
