> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akaramarkets.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Baseball

> Event vocabulary and game state for the baseball feed — MLB

The baseball feed covers live MLB games. Feed reads carry no sport in the URL — the [catalog](/api-reference/catalog), [WebSocket](/api-reference/websocket), [history backfill](/api-reference/history), and [session health](/api-reference/health) are all top-level endpoints addressed by session id.

<Note>
  The baseball feed is driven by a **manual scorekeeper**. A scout works a board where each play spans `pitch → end`; runs, outs, and bases are asserted by hand. The inning never advances automatically — an explicit `inning_advance` press does it.
</Note>

***

## Game state

Every WebSocket frame carries a full `GameState` snapshot. The history backfill returns events only — to rebuild this state from the log, replay the events; each event's entry below specifies its exact effect on state. Fields are camelCase on the wire. See the [Sports overview](/sports/overview) for the conventions and cross-sport events (`score_set`, `game_end`, `undo`) shared across every sport.

### Score

| Field   | Type                       | Description                                                                                       |
| ------- | -------------------------- | ------------------------------------------------------------------------------------------------- |
| `score` | `{ a: number, b: number }` | Running score, derived from events. Increases on `run` and `home_run`; overwritten by `score_set` |
| `final` | boolean                    | `true` once the game ends — no further frames will arrive                                         |

### Inning clock

Baseball counts outs, not a run clock. The inning advances on an explicit `inning_advance` press.

| Field    | Type    | Description                                                                     |
| -------- | ------- | ------------------------------------------------------------------------------- |
| `inning` | integer | Current inning number (1-indexed)                                               |
| `half`   | string  | `"top"` or `"bottom"`. See [Half values](#half-values)                          |
| `outs`   | integer | Outs in the current half-inning (`0`–`3`). Resets to `0` on half-inning advance |

### Baserunners

The bases are **confirmed-runner flags**, not verified occupancy, and carry no runner identities. `true` means the scout has confirmed a runner safe on that base. `false` means **no confirmed runner** — an absence of a claim (never marked, cleared by `contact` or a half-inning advance, or retracted) — *not* a statement that the base was checked and found empty. Read the flags as the scoring threat the scout has confirmed so far, not as a complete picture of who is on base.

| Field   | Type    | Description                                   |
| ------- | ------- | --------------------------------------------- |
| `bases` | `Bases` | Confirmed-runner flags. See [`Bases`](#bases) |

**`Bases`**

| Field    | Type    | Description                     |
| -------- | ------- | ------------------------------- |
| `first`  | boolean | Runner confirmed safe on first  |
| `second` | boolean | Runner confirmed safe on second |
| `third`  | boolean | Runner confirmed safe on third  |

### Play flags

These fields track the manual scorekeeper's open-play span (`pitch → end`).

| Field     | Type    | Description                                                                              |
| --------- | ------- | ---------------------------------------------------------------------------------------- |
| `live`    | boolean | A play is open (between `pitch` and `end`). `false` at rest                              |
| `contact` | boolean | Bat-on-ball contact was recorded this play — required before a `home_run` can be pressed |
| `hr`      | boolean | A home run was recorded this play                                                        |

***

## Enum values

### Half values

| Value      | Meaning           |
| ---------- | ----------------- |
| `"top"`    | Away side batting |
| `"bottom"` | Home side batting |

***

## Events

The scout operates as a manual scorekeeper. A "play" spans `pitch → end`; runs, outs, and bases are asserted by hand. The inning never advances automatically — an explicit `inning_advance` press does it.

***

### Play lifecycle

<AccordionGroup>
  <Accordion title="pitch — open a play">
    The pitcher begins the delivery — a play is live. The press is anchored at the **start of the delivery**, not at release: it is the earliest warning that an outcome may be imminent. Sets `live` and clears the per-play `contact`/`hr` flags. Does nothing if a play is already open or the half-inning already has three outs.

    No payload fields.

    ```json theme={null}
    { "type": "pitch", "payload": {} }
    ```
  </Accordion>

  <Accordion title="end — close the play">
    The play is over. Clears `live` and the per-play `contact`/`hr` flags. Does nothing when no play is open.

    No payload fields.

    ```json theme={null}
    { "type": "end", "payload": {} }
    ```
  </Accordion>
</AccordionGroup>

***

### Within a live play

<AccordionGroup>
  <Accordion title="contact — batter makes contact">
    The batter makes bat-on-ball contact. This claims **contact only** — at press time fair or foul (let alone a safe reach) is not yet known, so it is not the official "hit" statistic: contact can resolve into an out, an error, or a foul closed by `end` with nothing else recorded. Sets the `contact` flag, which a `home_run` press requires, and **clears every base** — a ball off the bat puts every runner's safety back in question, so the scout re-marks who's safe with `set_base` rather than the feed assuming everyone advances. (A following `home_run` press still credits the runners who were on base at the moment of contact — the clear doesn't cost them their runs.) Runs are credited separately with `run`/`home_run`. Does nothing unless a play is live.

    No payload fields.

    ```json theme={null}
    { "type": "contact", "payload": {} }
    ```
  </Accordion>

  <Accordion title="out — record one out">
    Records one out within the live play. Recording the third out does **not** advance the half-inning on its own — wait for an explicit `inning_advance`. Does nothing unless a play is live.

    No payload fields.

    ```json theme={null}
    { "type": "out", "payload": {} }
    ```
  </Accordion>

  <Accordion title="run — credit one run">
    Credits one run to the batting side (top = side B, bottom = side A). It detects a walk-off right away: if the home side takes the lead in the ninth inning or later, the game ends. Does nothing unless a play is live.

    No payload fields.

    ```json theme={null}
    { "type": "run", "payload": {} }
    ```
  </Accordion>

  <Accordion title="home_run — bases-clearing homer">
    A home run: scores every confirmed runner plus the batter, then clears the bases. Requires recorded `contact` this play, and fires once per play. It also ends the game on a walk-off. Does nothing otherwise.

    No payload fields.

    ```json theme={null}
    { "type": "home_run", "payload": {} }
    ```
  </Accordion>
</AccordionGroup>

***

### Baserunners

<AccordionGroup>
  <Accordion title="set_base — mark a runner safe on a base">
    Sets one base's confirmed-runner flag. `occupied: true` asserts the scout confirmed a runner safe on the base; `occupied: false` retracts that claim — it means **no confirmed runner**, not that the base was checked and found empty. Operationally: on a steal/advance, clear the old base and set the next one only once the runner is confirmed safe; if the runner is out, send `false` and report the out via `out`. Absolute, so re-sending is harmless. Editable any screen except the next-inning prompt (the bases are about to clear).

    | Field      | Type    | Description                                                               |
    | ---------- | ------- | ------------------------------------------------------------------------- |
    | `base`     | string  | `"first"`, `"second"`, or `"third"`                                       |
    | `occupied` | boolean | `true` = runner confirmed safe on the base; `false` = no confirmed runner |

    ```json theme={null}
    { "type": "set_base", "payload": { "base": "second", "occupied": true } }
    ```
  </Accordion>

  <Accordion title="inning_advance — advance the half-inning">
    Advances the inning clock: top → bottom (same inning) or bottom → top (next inning). Resets outs and clears the bases. Ends the game when the side that just finished batting in the ninth inning or later trails.

    Does nothing during a live play.

    No payload fields.

    ```json theme={null}
    { "type": "inning_advance", "payload": {} }
    ```
  </Accordion>
</AccordionGroup>

***

### Corrections

<AccordionGroup>
  <Accordion title="score_set — manual score correction">
    Overwrites the run totals. Scoring continues from the new values.

    | Field | Type    | Description              |
    | ----- | ------- | ------------------------ |
    | `a`   | integer | New run total for side A |
    | `b`   | integer | New run total for side B |

    ```json theme={null}
    { "type": "score_set", "payload": { "a": 3, "b": 1 } }
    ```
  </Accordion>

  <Accordion title="game_end — game is final">
    Terminal: sets `final`. Consumers should close the WebSocket after receiving this — no further frames will arrive.

    No payload fields.

    ```json theme={null}
    { "type": "game_end", "payload": {} }
    ```
  </Accordion>

  <Accordion title="undo — retract last press">
    Retracts the most recent scout press. Both the original press and the `undo` appear in `/history` as raw events — a client replaying the log resolves it there: each `undo` cancels the most recent non-`undo` event.

    The scout sends no payload fields; the served payload carries the server-stamped `retractsSeq` — the `seq` of the press the undo cancelled (`null` when nothing remained) — on the live frame and in `/history` alike, so a display can strike the retracted row without replaying.

    ```json theme={null}
    { "type": "undo", "payload": { "retractsSeq": 41 } }
    ```
  </Accordion>
</AccordionGroup>