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

# Historical overview

> Time-series prices, liquidity metrics, and L2 order book snapshots.

Historical endpoints return bucketed time series for a market or token within a half-open interval `[start_ts, end_ts)`.

Data is materialized from sparse historical captures into uniform buckets using **last-value carry** — each bucket reflects the most recent known value at or before that timestamp.

All historical routes require `X-API-Key` on the hosted API and enforce your plan's **resolution floor** and **history window** — see [Pricing](/pricing).

## Endpoints

| Method | Path                               | Returns                             |
| ------ | ---------------------------------- | ----------------------------------- |
| `GET`  | `/v1/markets/{id_or_slug}/prices`  | Outcome-labeled price series        |
| `GET`  | `/v1/markets/{id_or_slug}/metrics` | Volume, liquidity, spread           |
| `GET`  | `/v1/markets/{id_or_slug}/books`   | L2 order book snapshots per outcome |
| `GET`  | `/v1/tokens/{token_id}/prices`     | Single-token price series           |
| `GET`  | `/v1/tokens/{token_id}/books`      | Single-token order book series      |

## Required parameters

| Parameter    | Description                                               |
| ------------ | --------------------------------------------------------- |
| `start_ts`   | Inclusive window start — ISO-8601 UTC or Unix seconds     |
| `end_ts`     | **Exclusive** window end — ISO-8601 UTC or Unix seconds   |
| `resolution` | Bucket width — see [Resolutions](/historical/resolutions) |

Optional: `limit` (default `100`, max `200`) and `cursor` for paginated series.

<Note>
  `end_ts` is exclusive. To query July 26 00:00 through July 26 23:59 inclusive at `1h` resolution, set `end_ts` to `2026-07-27T00:00:00Z`.
</Note>

## Example — market order books (Starter)

On Starter, use `resolution=60s` and keep `start_ts` within the last **7 days**:

```bash theme={null}
curl -s -H "X-API-Key: $POLYORDERBOOKS_API_KEY" \
  "https://api.polyorderbooks.com/v1/markets/MARKET_SLUG/books" \
  --get \
  --data-urlencode "start_ts=2026-07-26T00:00:00Z" \
  --data-urlencode "end_ts=2026-07-26T06:00:00Z" \
  --data-urlencode "resolution=60s"
```

**Response (abbreviated)**

```json theme={null}
{
  "market_id": "618831",
  "resolution": "60s",
  "tokens": {
    "Yes": "0xabc...",
    "No": "0xdef..."
  },
  "data": {
    "Yes": [{ "t": "2026-07-26T00:00:00Z", "b": [[0.54, 1000]], "a": [[0.56, 800]] }],
    "No": [{ "t": "2026-07-26T00:00:00Z", "b": [[0.44, 900]], "a": [[0.46, 1100]] }]
  },
  "metadata": {
    "count": 1,
    "limit": 100,
    "next_cursor": null
  }
}
```

## Field reference

| Field                       | Description                               |
| --------------------------- | ----------------------------------------- |
| `data.<outcome>[].t`        | Bucket timestamp (UTC, ISO-8601)          |
| `data.<outcome>[].p`        | Price in \[0, 1] on `/prices` endpoints   |
| `data.<outcome>[].b` / `.a` | Bid and ask ladders on `/books` endpoints |
| `metadata.next_cursor`      | Pagination token when more buckets exist  |

## When to use token endpoints

Use token-level routes when you already have a CLOB token id:

* [`GET /v1/tokens/{token_id}/prices`](/api-reference/history/get-token-price-history)
* [`GET /v1/tokens/{token_id}/books`](/api-reference/history/get-token-order-book-history)

## Related guides

<CardGroup cols={3}>
  <Card title="Resolutions" icon="clock" href="/historical/resolutions">
    Bucket sizes and plan restrictions.
  </Card>

  <Card title="Pagination" icon="angles-right" href="/historical/pagination">
    Cursor-based paging for long ranges.
  </Card>

  <Card title="Rate limits" icon="gauge-high" href="/rate-limits">
    Quotas and efficient bulk retrieval.
  </Card>
</CardGroup>