> ## 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. # Get market order book history > Get historical order book snapshots for market tokens. This endpoint always returns order books for all tokens in the market. Use `/v1/tokens/{token_id}/books` for single-token queries. **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 /openapi.json get /v1/markets/{id_or_slug}/books openapi: 3.1.0 info: title: PolyOrderbooks API description: > # PolyOrderbooks API Historical Polymarket **crypto** market data — discovery, prices, liquidity metrics, and L2 order books. Read paths query our historical data store; they never call Polymarket live. ## Base URL `https://api.polyorderbooks.com` ## Authentication All `/v1/*` data routes require an API key. Send `X-API-Key: pob_…` or `Authorization: Bearer pob_…`. Dashboard JWT session tokens are **not** accepted on data routes. ## Plans (hosted) | Plan | Req/min | Req/day | Finest resolution | History | | --- | --- | --- | --- | --- | | Starter | 60 | 1,000 | 60s | 7 days | | Pro | 300 | 50,000 | 1s | 31 days | | Scale | 1,000 | 200,000 | 1s | 90 days | ## Workflow 1. `GET /v1/markets` — discover 2. `GET /v1/markets/{id_or_slug}` — detail 3. `GET /v1/markets/{id_or_slug}/books` — history version: 0.1.0 servers: - url: https://api.polyorderbooks.com description: Production security: [] tags: - name: Discovery description: >- Discover series, events, and markets. Use returned ids or slugs in History endpoints. - name: History description: Historical metrics, prices, and L2 order book snapshots. - name: Utility description: Usage and account metadata. paths: /v1/markets/{id_or_slug}/books: get: tags: - History summary: Get market order book history description: >- Get historical order book snapshots for market tokens. This endpoint always returns order books for all tokens in the market. Use `/v1/tokens/{token_id}/books` for single-token queries. **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_market_books_v1_markets__id_or_slug__books_get parameters: - name: id_or_slug in: path required: true schema: type: string minLength: 1 maxLength: 200 description: Market ID or market slug. examples: - '618831' title: Id Or Slug description: Market ID or market slug. - 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 all market tokens. content: application/json: schema: $ref: '#/components/schemas/BooksResponseAllTokens' '400': description: >- Invalid timestamp format, limit, cursor, or market point constraints. content: application/json: examples: small_limit: value: detail: 'limit too small for this market. Minimum required: 3' many_tokens: value: detail: >- Market has more than 200 tokens. Use /v1/tokens/{token_id}/books instead. 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: >- Unsupported resolution '2m'. Allowed: 10m, 15m, 1d, 1h, 1m, 1s, 5m, 60s, 6h 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' components: schemas: Resolution: type: string enum: - 1s - 1m - 5m - 10m - 15m - 1h - 6h - 1d title: Resolution description: Supported time resolutions for historical endpoints. BooksResponseAllTokens: properties: market_id: type: string title: Market Id description: Canonical market ID. examples: - '618831' resolution: type: string title: Resolution description: Applied resolution. examples: - 1h tokens: additionalProperties: type: string type: object title: Tokens description: Mapping of token label to token ID. examples: - 'No': '12346' 'Yes': '12345' data: additionalProperties: items: $ref: '#/components/schemas/OrderBookSnapshot' type: array type: object title: Data description: Order book snapshots grouped by token label. metadata: $ref: '#/components/schemas/HistoryPageMetadata' description: Pagination metadata for this history page. type: object title: BooksResponseAllTokens description: Response for `GET /markets/{id_or_slug}/books`. example: data: 'No': - asks: - - 0.29 - 133 - - 0.3 - 281 bids: - - 0.28 - 142 - - 0.27 - 298 t: '2025-09-05T10:00:00Z' 'Yes': - 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: 2 limit: 100 resolution: 1h tokens: 'No': '12346' 'Yes': '12345' ErrorResponse: properties: detail: type: string title: Detail description: Human-readable error description. type: object title: ErrorResponse description: Generic API error response. OrderBookSnapshot: properties: t: type: string format: date-time 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 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 title: HistoryPageMetadata description: Pagination metadata for history responses. ````