> ## 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. # Get token order book history > Get historical order book snapshots for a specific token. **Pagination limits:** - Default `limit`: 100 points per page - Maximum `limit`: 200 points per page - Use `cursor` from `metadata.next_cursor` to fetch the next page **Aggregation:** The last (most recent) order book in each interval is returned. **Format:** JSON only. ## OpenAPI ````yaml https://api.polymarketdata.co/openapi.json get /v1/tokens/{token_id}/books openapi: 3.1.0 info: title: PolymarketData API description: >- Historical Polymarket market data with plan-based access controls (resolution, lookback window, and RPM). Use this API to discover markets, then query historical metrics, prices, and order books. ## Authentication All `/v1` endpoints require an API key. 1. Sign in to the PolymarketData dashboard. [https://app.polymarketdata.co/](https://app.polymarketdata.co/dashboard) 2. Create an API key. 3. Send the key in the `X-API-Key` header on every request. Header format: `X-API-Key: pk_live_your_key_here` ## Key Concepts Polymarket data is organized in a hierarchy: - **Series**: Broad themes or recurring categories (for example, `US Politics` or `NBA`). - **Events**: Specific real-world happenings within a series (for example, `Presidential Debate`). - **Markets**: Tradable prediction questions inside an event (for example, `Will candidate X win?`). - **Tokens**: Outcome contracts within a market (for example, `Yes` and `No`). Mental model: `Series -> Events -> Markets -> Tokens`. ## Typical Workflow 1. Discover objects with `GET /v1/series`, `GET /v1/events`, and `GET /v1/markets`. 2. Select a market ID or slug from discovery responses. 3. Query historical data via `/v1/markets/{id_or_slug}/metrics`, `/prices`, or `/books`. version: 0.1.1 servers: - url: https://api.polymarketdata.co description: Production security: [] tags: - name: Clients & SDKs description: >- Official client libraries and SDK guidance. ### Python SDK - Package: [`polymarketdata-sdk`](https://pypi.org/project/polymarketdata-sdk/) - Install: `pip install polymarketdata-sdk` - Optional dataframe extras: `pip install "polymarketdata-sdk[dataframe]"` - API key can be passed directly or via `POLYMARKETDATA_API_KEY` ### SDK Surface Map | Namespace | What it covers | Core methods | |---|---|---| | `client.utility` | API health and plan/rate status | `health()`, `usage()` | | `client.discovery` | entity discovery and lookup | `list_series()`, `list_events()`, `list_markets()`, `get_market()`, `list_tags()` | | `client.discovery` iterators | auto-pagination for discovery | `iter_series()`, `iter_events()`, `iter_markets()` | | `client.history` | historical market/token data | `get_market_metrics()`, `get_market_prices()`, `get_token_prices()`, `get_market_books()`, `get_token_books()` | | `client.history` iterators | auto-pagination for history | `iter_market_metrics()`, `iter_token_prices()`, `iter_token_books()` | ### 60-Second Quickstart ```python from polymarketdata import PolymarketDataClient # api_key can also be set via POLYMARKETDATA_API_KEY with PolymarketDataClient(api_key="YOUR_API_KEY") as client: health = client.utility.health() usage = client.utility.usage() print(health.status) print(usage.plan) print(usage.limits.requests_remaining) ``` ### End-to-End Example (Discovery -> History) ```python from polymarketdata import PolymarketDataClient, Resolution with PolymarketDataClient(api_key="YOUR_API_KEY") as client: markets = client.discovery.list_markets( event_slug="us-presidential-election-2025", limit=5, ) market_id_or_slug = markets.data[0].slug or markets.data[0].id metrics = client.history.get_market_metrics( market_id_or_slug, start_ts="2025-09-01T00:00:00Z", end_ts="2025-11-05T00:00:00Z", resolution=Resolution.ONE_DAY, ) print(metrics.market_id, len(metrics.data)) ``` ### Supported Resolutions These match the API `resolution` enum: - `Resolution.ONE_MIN` (`1m`) - `Resolution.TEN_MIN` (`10m`) - `Resolution.ONE_HOUR` (`1h`) - `Resolution.SIX_HOUR` (`6h`) - `Resolution.ONE_DAY` (`1d`) ### DataFrame Helpers If installed with `polymarketdata-sdk[dataframe]`, use: - `to_dataframe_metrics(...)` - `to_dataframe_prices(...)` - `to_dataframe_books(...)` ### Errors and Retry Behavior All SDK exceptions inherit from `PolymarketDataError`. Common exception types: - `AuthenticationError` (401) - `PermissionDeniedError` (403) - `NotFoundError` (404) - `RateLimitError` (429) - `ServerError` (5xx) - `NetworkError` / `RequestTimeoutError` The SDK retries `429` and `5xx` responses with exponential backoff + jitter. Tune with `max_retries`, `retry_backoff_base`, `retry_backoff_max`, and `timeout`. ### Response Metadata Responses include: - `.meta` (HTTP metadata such as `status_code`, `request_id`) - `.raw` (unmodified response payload) externalDocs: description: Python SDK package url: https://pypi.org/project/polymarketdata-sdk/ - name: Discovery description: >- Start here. Discover series, events, and markets, then use the returned market IDs/slugs in History endpoints. - name: History description: >- Retrieve historical metrics, prices, and order book snapshots for a specific market. - name: Utility description: Health, status, and usage endpoints. paths: /v1/tokens/{token_id}/books: get: tags: - History summary: Get token order book history description: >- Get historical order book snapshots for a specific token. **Pagination limits:** - Default `limit`: 100 points per page - Maximum `limit`: 200 points per page - Use `cursor` from `metadata.next_cursor` to fetch the next page **Aggregation:** The last (most recent) order book in each interval is returned. **Format:** JSON only. operationId: get_token_books_v1_tokens__token_id__books_get parameters: - name: token_id in: path required: true schema: type: string minLength: 1 maxLength: 200 description: Token ID. examples: - '12345' title: Token Id description: Token ID. - name: start_ts in: query required: true schema: type: string description: Inclusive range start. Accepts ISO 8601 timestamp or Unix seconds. examples: - '2025-09-04T00:00:00Z' - '1756944000' title: Start Ts description: Inclusive range start. Accepts ISO 8601 timestamp or Unix seconds. - name: end_ts in: query required: true schema: type: string description: Exclusive range end. Accepts ISO 8601 timestamp or Unix seconds. examples: - '2025-09-05T00:00:00Z' - '1757030400' title: End Ts description: Exclusive range end. Accepts ISO 8601 timestamp or Unix seconds. - name: resolution in: query required: true schema: $ref: '#/components/schemas/Resolution' description: Aggregation bucket size. description: Aggregation bucket size. - name: limit in: query required: false schema: type: integer minimum: 1 description: >- Maximum number of points to return in this page. Default: 100, max: 200. examples: - 100 default: 100 title: Limit description: >- Maximum number of points to return in this page. Default: 100, max: 200. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Opaque cursor from a previous response metadata.next_cursor. title: Cursor description: Opaque cursor from a previous response metadata.next_cursor. responses: '200': description: Historical order book snapshots for a single token. content: application/json: schema: $ref: '#/components/schemas/BooksResponseSingleToken' '400': description: Invalid timestamp format, limit, or cursor. content: application/json: example: detail: Invalid pagination cursor schema: $ref: '#/components/schemas/ErrorResponse' '401': description: API key is missing, invalid, or expired. content: application/json: example: detail: Invalid or expired API key. schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- Plan does not allow the requested data point, granularity, or date range. content: application/json: example: detail: Your plan does not allow historical order books. schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Requested resource (market or token) was not found. content: application/json: examples: market: value: detail: 'Market not found: 618831' token: value: detail: 'Token not found: 12345' schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation error for one or more request parameters. content: application/json: example: detail: - loc: - query - resolution msg: Input should be '1m', '10m', '1h', '6h' or '1d' type: enum '429': description: Rate limit exceeded for the current API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Rate limit exceeded. Please try again later. '500': description: Unexpected server-side error. content: application/json: example: detail: Failed to fetch data. schema: $ref: '#/components/schemas/ErrorResponse' security: - ApiKeyAuth: [] components: schemas: Resolution: type: string enum: - 1m - 10m - 1h - 6h - 1d title: Resolution description: Supported time resolutions for historical endpoints. BooksResponseSingleToken: properties: market_id: type: string title: Market Id description: Canonical market ID. examples: - '618831' token_id: type: string title: Token Id description: Requested token ID. examples: - '12345' token_label: type: string title: Token Label description: Human-readable token label. examples: - 'Yes' resolution: type: string title: Resolution description: Applied resolution. examples: - 1h data: items: $ref: '#/components/schemas/OrderBookSnapshot' type: array title: Data description: Chronological order book snapshots for the selected token. metadata: $ref: '#/components/schemas/HistoryPageMetadata' description: Pagination metadata for this history page. type: object required: - market_id - token_id - token_label - resolution - data - metadata title: BooksResponseSingleToken description: Response for `GET /tokens/{token_id}/books`. example: data: - asks: - - 0.73 - 140 - - 0.74 - 300 bids: - - 0.72 - 150 - - 0.71 - 320 t: '2025-09-05T10:00:00Z' market_id: '618831' metadata: count: 1 limit: 100 resolution: 1h token_id: '12345' token_label: 'Yes' ErrorResponse: properties: detail: type: string title: Detail description: Human-readable error description. type: object required: - detail title: ErrorResponse description: Generic API error response. OrderBookSnapshot: properties: t: type: string title: T description: Bucket timestamp in ISO 8601 format. examples: - '2025-09-05T12:00:00Z' bids: items: items: type: number type: array type: array title: Bids description: Bid levels as `[price, size]` pairs, best bid first. examples: - - - 0.72 - 150 - - 0.71 - 320 asks: items: items: type: number type: array type: array title: Asks description: Ask levels as `[price, size]` pairs, best ask first. examples: - - - 0.73 - 140 - - 0.74 - 300 type: object required: - t - bids - asks title: OrderBookSnapshot description: Single token order book snapshot. HistoryPageMetadata: properties: count: type: integer title: Count description: Number of points returned in this page. limit: type: integer title: Limit description: Effective page limit used for this response. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Opaque cursor for the next page. Null when the page is complete. type: object required: - count - limit title: HistoryPageMetadata description: Pagination metadata for history responses. securitySchemes: ApiKeyAuth: type: apiKey description: >- Create an API key in the PolymarketData dashboard and send it in the `X-API-Key` request header. Example: `X-API-Key: pk_live_your_key_here` in: header name: X-API-Key ````