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

# Data model

> How series, events, markets, and tokens nest, and which identifiers to persist.

Polymarket data is a four-level hierarchy. History endpoints sit on **markets** and **tokens**. Discovery endpoints sit on the layers above them.

```
Series → Events → Markets → Tokens
```

| Level      | What it is                           | Example                 |
| ---------- | ------------------------------------ | ----------------------- |
| **Series** | Broad theme or recurring category    | `NBA`, `US Politics`    |
| **Event**  | A specific happening inside a series | `Presidential Debate`   |
| **Market** | A tradable question inside an event  | `Will candidate X win?` |
| **Token**  | An outcome contract inside a market  | `Yes`, `No`             |

## Identifiers

Discovery objects include both an `id` and a `slug`. History routes accept either on `{id_or_slug}`.

<Info>
  Persist the exact `id` or `slug` you used, plus the timestamp when you built the universe. Discovery results change as markets open and resolve. If the universe drifts, backtests are not comparable.
</Info>

Token-level history uses `{token_id}`:

* `GET /v1/tokens/{token_id}/prices`
* `GET /v1/tokens/{token_id}/books`

Market-level price and book endpoints return **every token** in the market. If a market has more than 200 tokens, those endpoints refuse the request and tell you to query one token at a time.

## Timestamps

Keep the pipeline in UTC.

* Discovery date filters use ISO 8601 timestamps.
* History `start_ts` is inclusive. `end_ts` is exclusive.
* Both accept ISO 8601 (`2025-09-01T00:00:00Z`) or Unix seconds (`1756684800`).
* History rows expose `t` as ISO 8601.

<Warning>
  Convert to local time only for display. Mixing naive and aware datetimes, or dropping timezone info, shifts signals by hours without an obvious error.
</Warning>

## Resolutions

History endpoints require `resolution`. Allowed values: `1m`, `10m`, `1h`, `6h`, `1d`.

| Series  | Aggregation                                |
| ------- | ------------------------------------------ |
| Prices  | Average inside each bucket                 |
| Metrics | Average inside each bucket                 |
| Books   | Last (most recent) snapshot in each bucket |

Your plan's finest allowed resolution comes back on `GET /v1/usage` as `limits.granularity_allowed`. Requesting a finer bucket returns `403`.

## What each history family is for

* **Prices** — token probability from `0.0` to `1.0`. Field name is `p`.
* **Metrics** — market-level `volume`, `liquidity`, and `spread`.
* **Books** — `bids` and `asks` as `[price, size]` arrays, best level first.

<Tip>
  Join prices to metrics before you backtest. Price bars alone do not tell you whether a print was tradable at your size. Even a simple spread filter changes which setups survive.
</Tip>