> ## 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.

# L2 Snapshots

> Query normalized order book snapshots with client.l2_snapshots()

Use `client.l2_snapshots()` when you need order book snapshots for market microstructure analysis. This method returns standardized Level 2 order book data with bids and asks at multiple price levels.

## Method signature

```python theme={null}
l2_snapshots(source, market, from_, to, limit=1000)
```

## Parameters

| Parameter | Type                  | Required | Notes                                                                  |
| --------- | --------------------- | -------- | ---------------------------------------------------------------------- |
| source    | str                   | Yes      | Source ID                                                              |
| market    | str                   | Yes      | Normalized market or instrument ID                                     |
| from\_    | str/datetime/date/int | Yes      | Inclusive start time (ISO 8601, datetime, date, or epoch microseconds) |
| to        | str/datetime/date/int | Yes      | Exclusive end time (same formats as from\_)                            |
| limit     | int                   | No       | Page size (default: 1000)                                              |

**Note:** API key required for historical ranges. Set `POLARIS_API_KEY` environment variable or pass `api_key` to `PolarisClient()`.

## Return value

List of normalized order book snapshot dictionaries.

## Example response

```python theme={null}
[
    {
        'timestamp': 1704067200000000,
        'venue': 'binance',
        'symbol': 'BTC-USDT',
        'type': 'orderbook',
        'data': {
            'bids': [
                {'price': 43250.00, 'quantity': 1.5},
                {'price': 43249.50, 'quantity': 2.0}
            ],
            'asks': [
                {'price': 43250.50, 'quantity': 1.2},
                {'price': 43251.00, 'quantity': 3.5}
            ]
        }
    }
]
```

## Fields

L2 snapshots use the standard event envelope with `type: "orderbook"` and the following order book-specific fields under `data`:

* `data.bids`: array of bid levels, each with `price` and `quantity`
* `data.asks`: array of ask levels, each with `price` and `quantity`

Bid levels are sorted descending by price, ask levels are sorted ascending. The envelope-level `timestamp` is the snapshot time in UTC microseconds since the Unix epoch.

## Example

```python theme={null}
from datetime import datetime, timedelta, timezone
from polaris_data import PolarisClient

end = datetime.now(timezone.utc)
start = end - timedelta(hours=1)

with PolarisClient() as client:
    snapshots = client.l2_snapshots(
        source="binance",
        market="BTC-USDT",
        from_=start,
        to=end,
    )

print(snapshots[:2])
```

## How it works

`client.l2_snapshots()` uses snapshot-first replay: it queries the `/snapshots` endpoint for historical data and reads from local cached files when available. The SDK handles pagination and data normalization automatically.

For more details on snapshot-based queries, see [Snapshots](/reference/snapshots).

## Related documentation

* [Depth metrics](/sdks/depth-metrics) for derived liquidity metrics
* [BBO](/sdks/bbo) if you only need top-of-book quotes
* [Events](/sdks/events) if you need order book updates mixed with other event types
* [Authentication](/guides/authentication)