History

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.

get/v1/markets/{id_or_slug}/books

Request

  • Base URL: https://api.polymarketdata.co
  • URL: https://api.polymarketdata.co/v1/markets/{id_or_slug}/books
  • Auth: API key in header X-API-Key

Path parameters

id_or_slugstring required

Market ID or market slug.

Example:618831

Query parameters

start_tsstring required

Inclusive range start. Accepts ISO 8601 timestamp or Unix seconds.

Example:2025-09-04T00:00:00Z
end_tsstring required

Exclusive range end. Accepts ISO 8601 timestamp or Unix seconds.

Example:2025-09-05T00:00:00Z
resolution'1m' | '10m' | '1h' | '6h' | '1d' required

Supported time resolutions for historical endpoints.

Aggregation bucket size.

limitinteger

Maximum number of points to return in this page. Default: 100, max: 200.

Example:100
cursorstring nullable

Opaque cursor from a previous response metadata.next_cursor.

Response

Historical order book snapshots for all market tokens.

market_idstring required

Canonical market ID.

resolutionstring required

Applied resolution.

tokensobject required

Mapping of token label to token ID.

dataobject required

Order book snapshots grouped by token label.

Example response

{
  "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"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.