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

# Top of Book

> Best bid, best ask, spread, and mid per outcome from orderbook snapshots

> [!NOTE]
>
> Top of Book is an **early access** dataset available through [SQL](https://docs.probalytics.io/docs/sql-guide/overview.md). It requires orderbook access. To request access, email [support@probalytics.io](mailto:support@probalytics.io).

Best bid and ask, their sizes, spread, and mid for each outcome. Computed at query time from verified [orderbook snapshots](https://docs.probalytics.io/docs/datasets/orderbook.md) (`state = 'VERIFIED'`).

| View | Rows |
| - | - |
| `top_of_book` | One per snapshot |
| `top_of_book_1s`, `top_of_book_10s`, `top_of_book_1m`, `top_of_book_5m` | One per outcome per bucket |

## Raw view

`top_of_book` has one row per verified snapshot. It reads `orderbook_snapshots` directly, so always filter by `market_id` and a `timestamp` range:

```sql theme={null}
SELECT timestamp, outcome.name, best_bid, best_ask, spread, mid
FROM top_of_book
WHERE market_id = '00000000-0000-0000-0000-000000000000'
  AND timestamp >= now() - INTERVAL 1 HOUR
ORDER BY timestamp
```

## Sampled views

The `_1s`, `_10s`, `_1m`, and `_5m` views are parameterized and return the book **as of** each bucket boundary, on a regular time grid:

```sql theme={null}
SELECT *
FROM top_of_book_1m(
    market_id = '00000000-0000-0000-0000-000000000000',
    start = '2026-11-01 00:00:00',
    end = '2026-11-02 00:00:00'
)
```

| Parameter | Type | Meaning |
| - | - | - |
| `market_id` | `UUID` | Market. Joins to `markets.id`. |
| `start` | `DateTime` (UTC) | Range start, rounded down to the bucket boundary. Inclusive. |
| `end` | `DateTime` (UTC) | Range end. Exclusive. |

* Each row describes the last verified snapshot at or before `timestamp`. The book is carried forward through buckets with no updates.
* The views look back at most **1 day before `start`** for the starting book. If an outcome had no update in that window, its rows are `null` until the first update.
* Rows are returned only for outcomes with at least one snapshot in the lookback window or range.

## Fields

| Field | Type | Values and meaning |
| - | - | - |
| `platform` | `enum` | Source venue. |
| `market_id` | `UUID` | Probalytics market ID. |
| `market_platform_id` | `string` | Venue market ID. |
| `outcome` | `tuple` | Outcome struct. |
| `timestamp` | `datetime` | Snapshot time (raw view) or bucket time (sampled views). |
| `best_bid` | `decimal \| null` | Highest bid price. `null` if there are no bids. |
| `best_bid_size` | `decimal \| null` | Size at the best bid. |
| `best_ask` | `decimal \| null` | Lowest ask price. `null` if there are no asks. |
| `best_ask_size` | `decimal \| null` | Size at the best ask. |
| `spread` | `decimal \| null` | `best_ask - best_bid`. |
| `mid` | `decimal \| null` | `(best_bid + best_ask) / 2`. |

## Usage tips

* Use the sampled views to align the book with other time series, such as [OHLC candles](https://docs.probalytics.io/docs/datasets/ohlc.md).
* Coverage and history follow [orderbook snapshots](https://docs.probalytics.io/docs/datasets/orderbook.md#coverage-by-venue-and-product).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.