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

# Historical L2 order books

> Query paginated source order-book snapshots and deltas directly from the historical REST API.

Use `GET /historical/orderbook-l2` to read stateless L2 source events in global collector-time order. Each flat REST row has fixed price and size fields for up to 25 levels per side. The [L2 schema page](/schemas/l2-snapshots) describes SDK and snapshot event envelopes and how to reconstruct a complete book; this endpoint returns the source observations without doing that reconstruction.

`source_event_is_snapshot: true` identifies a complete source snapshot. `false` identifies a sparse update with absolute level quantities. Do not treat every returned row as a complete order book.

## Access and time range

Omit both `start` and `end` to query the latest ten minutes without authentication. Supply either bound to query a chosen interval with a Polaris API key in `Authorization: Bearer YOUR_API_KEY`. `start` and `end` are **inclusive collector timestamps in Unix milliseconds**. With only `start`, the query runs through now; with only `end`, it covers the preceding ten minutes.

## Query parameters

<ParamField query="source" type="string">
  Exact source ID. Omit to query across sources.
</ParamField>

<ParamField query="market" type="string">
  Exact normalized routing market. Omit to query across markets.
</ParamField>

<ParamField query="instrument" type="string">
  Venue-native instrument filter.
</ParamField>

<ParamField query="start" type="integer">
  Inclusive collector time in Unix milliseconds. Requires a Polaris API key.
</ParamField>

<ParamField query="end" type="integer">
  Inclusive collector time in Unix milliseconds. Requires a Polaris API key.
</ParamField>

<ParamField query="limit" type="integer" default={200}>
  Page size from `1` to `1000`.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque `next_cursor` from the previous page of the same query.
</ParamField>

Use [Catalog](/reference/catalog) to find exact source and market IDs.

## Request and response

```bash theme={null}
curl "https://api.polaris.supply/historical/orderbook-l2?source=hyperliquid&market=BTC&limit=2"
```

Example response excerpt, showing level `00` and `24` only:

```json theme={null}
{
  "items": [
    {
      "event_id": "book-123",
      "source": "hyperliquid",
      "market": "BTC",
      "instrument": null,
      "collector_timestamp": 1727200000000,
      "exchange_timestamp": null,
      "source_capture_id": "capture-123",
      "schema_version": 2,
      "source_event_is_snapshot": true,
      "bid_px_00": 63450.0,
      "bid_sz_00": 1.2,
      "ask_px_00": 63451.0,
      "ask_sz_00": 0.8,
      "bid_px_24": null,
      "bid_sz_24": null,
      "ask_px_24": null,
      "ask_sz_24": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

Every full item also has all intermediate `bid_px_01` through `bid_px_23`, `bid_sz_01` through `bid_sz_23`, `ask_px_01` through `ask_px_23`, and `ask_sz_01` through `ask_sz_23` fields. Each level price or size is a nullable number. `event_id`, `source`, `market`, `collector_timestamp`, `source_capture_id`, `schema_version`, and `source_event_is_snapshot` are required. `instrument` and `exchange_timestamp` are present but can be null.

## Pagination and errors

When `has_more` is `true`, send `next_cursor` as `cursor` while keeping the other query parameters unchanged. Stop when `has_more` is `false`; `next_cursor` is then null.

The API documents `400` for an invalid request, `401` when authentication is needed, `422` when query work exceeds its limit, `429` when the request quota is exceeded, and `503` when the service is unavailable. Narrow the requested time range after a `422`; respect `Retry-After` after a `429`. Errors have an `error` object with `code`, `message`, and `resolution`.

## Related documentation

* [L2 order-book schema](/schemas/l2-snapshots) for reconstruction and SDK event fields
* [Python SDK](/sdks/python), [TypeScript SDK](/sdks/typescript), and [Rust SDK](/sdks/rust) for client methods
* [Snapshots](/reference/snapshots) for bulk historical files