Download recorded Polymarket order books
Page through stored book snapshots captured during your recording access windows.
Your API key can read snapshots captured during its granted recording windows. Market closure, unsubscribe or a plan downgrade ends recording but preserves access to those snapshots within retention. Resubscribing opens a new window; recordings captured between your windows are not included. Revoked keys cannot read recordings. Use timezone-aware ISO 8601 values for since and until, and follow the returned integer cursor with the same filters. Retention is up to seven days or the newest 100,000 rows per market, whichever limit is reached first. A busy market may retain less than seven days.
Authentication
Send your key in the X-API-Key header. Keep the key out of URLs and shared logs.
Parameters
| Name | Location | Type | Required | Details |
|---|---|---|---|---|
id | path | string | Yes | minLength: 1. maxLength: 160. pattern: ^[A-Za-z0-9_.-]+$. |
since | query | string or null | No | Inclusive timestamp with timezone, compared at the microsecond precision of recorded_at |
until | query | string or null | No | Inclusive timestamp with timezone, compared at the microsecond precision of recorded_at |
limit | query | integer | No | Default: 100. minimum: 1. maximum: 500. |
cursor | query | integer | No | Default: 0. minimum: 0. |
Example request
curl --fail-with-body -X GET \
"https://polymarket.omray.dev/subscriptions/YOUR_WALLET_OR_MARKET_ID/books" \
-H "X-API-Key: $PM_API_KEY"Responses
| Status | Meaning |
|---|---|
200 | Successful Response |
422 | Validation Error |
Authenticated requests can return 401 for an invalid key or 429 when a plan limit is reached. Upstream failures may return a server error; do not treat an error as an empty dataset.
OpenAPI operation schema
{
"tags": [
"Subscriptions"
],
"summary": "Download recorded Polymarket order books",
"description": "Read retained websocket events and REST snapshots captured during this API key's subscription windows. Ending a subscription preserves access to its recordings until retention expires. Records outside those windows are excluded. Paginate by row ID; retention is seven days or 100,000 rows per market, whichever comes first.",
"operationId": "recorded_books",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 160,
"pattern": "^[A-Za-z0-9_.-]+$",
"title": "Id"
}
},
{
"name": "since",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Inclusive timestamp with timezone, compared at the microsecond precision of recorded_at",
"title": "Since"
},
"description": "Inclusive timestamp with timezone, compared at the microsecond precision of recorded_at"
},
{
"name": "until",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Inclusive timestamp with timezone, compared at the microsecond precision of recorded_at",
"title": "Until"
},
"description": "Inclusive timestamp with timezone, compared at the microsecond precision of recorded_at"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"default": 100,
"title": "Limit"
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 0,
"title": "Cursor"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordedBooks"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}