> ## 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. # List markets > List bettable contracts/markets (e.g., "Winner", "Total Points Over/Under"). Supports filtering by date ranges, text search, tags, and pagination. Results are sorted by the selected field (default: `updated_at desc`). **Pagination:** Use the `next_cursor` value from the response to fetch the next page. ## OpenAPI ````yaml /openapi.json get /v1/markets 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: get: tags: - Discovery summary: List markets description: >- List bettable contracts/markets (e.g., "Winner", "Total Points Over/Under"). Supports filtering by date ranges, text search, tags, and pagination. Results are sorted by the selected field (default: `updated_at desc`). **Pagination:** Use the `next_cursor` value from the response to fetch the next page. operationId: list_markets_v1_markets_get parameters: - name: search in: query required: false schema: type: string maxLength: 200 description: Optional case-insensitive text match for market question or slug. examples: - trump title: Search description: Optional case-insensitive text match for market question or slug. - name: limit in: query required: false schema: type: integer maximum: 1000 minimum: 1 description: Maximum number of items returned in this page. examples: - 100 default: 100 title: Limit description: Maximum number of items returned in this page. - name: cursor in: query required: false schema: type: string description: Opaque cursor from a previous `metadata.next_cursor` value. title: Cursor description: Opaque cursor from a previous `metadata.next_cursor` value. - name: start_date_min in: query required: false schema: type: string description: >- Filter for markets with `start_date` greater than or equal to this ISO 8601 timestamp. examples: - '2026-01-01T00:00:00Z' title: Start Date Min description: >- Filter for markets with `start_date` greater than or equal to this ISO 8601 timestamp. - name: start_date_max in: query required: false schema: type: string description: >- Filter for markets with `start_date` less than or equal to this ISO 8601 timestamp. examples: - '2026-12-31T23:59:59Z' title: Start Date Max description: >- Filter for markets with `start_date` less than or equal to this ISO 8601 timestamp. - name: end_date_min in: query required: false schema: type: string description: >- Filter for markets with `end_date` greater than or equal to this ISO 8601 timestamp. examples: - '2026-01-01T00:00:00Z' title: End Date Min description: >- Filter for markets with `end_date` greater than or equal to this ISO 8601 timestamp. - name: end_date_max in: query required: false schema: type: string description: >- Filter for markets with `end_date` less than or equal to this ISO 8601 timestamp. examples: - '2026-12-31T23:59:59Z' title: End Date Max description: >- Filter for markets with `end_date` less than or equal to this ISO 8601 timestamp. - name: tags in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: >- Filter by event tags. Supports repeated params and comma-separated values. examples: - crypto title: Tags description: >- Filter by event tags. Supports repeated params and comma-separated values. - name: tags_match in: query required: false schema: $ref: '#/components/schemas/TagsMatchMode' description: 'Tag matching strategy: any (OR) or all (AND).' default: any description: 'Tag matching strategy: any (OR) or all (AND).' - name: sort in: query required: false schema: $ref: '#/components/schemas/SortField' description: Field used to sort the response rows. default: updated_at description: Field used to sort the response rows. - name: order in: query required: false schema: $ref: '#/components/schemas/SortOrder' description: Sort direction. default: desc description: Sort direction. responses: '200': description: Paginated list of markets. content: application/json: schema: $ref: '#/components/schemas/MarketListResponse' '400': description: Malformed date range or invalid pagination cursor. content: application/json: examples: invalid_cursor: summary: Invalid cursor value: detail: Invalid pagination cursor invalid_date_range: summary: Invalid date range value: detail: start_date_min must be <= start_date_max 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' '422': description: Validation error for one or more request parameters. content: application/json: example: detail: - loc: - query - limit msg: Input should be less than or equal to 1000 type: less_than_equal '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: TagsMatchMode: type: string enum: - any - all title: TagsMatchMode description: Tag match behavior for filtering. SortField: type: string enum: - created_at - updated_at title: SortField description: Sortable fields for discovery listings. SortOrder: type: string enum: - asc - desc title: SortOrder description: Sort direction for discovery listings. MarketListResponse: properties: metadata: $ref: '#/components/schemas/PaginationMetadata' description: Pagination metadata. data: items: $ref: '#/components/schemas/MarketItem' type: array title: Data description: Market results for this page. type: object title: MarketListResponse description: Paginated response for `GET /markets`. example: data: - end_date: '2025-11-05T23:59:59Z' id: '618831' question: Will Candidate X win the 2025 election? slug: will-candidate-x-win-2025 start_date: '2025-09-01T00:00:00Z' status: open tokens: - id: '12345' label: 'Yes' - id: '12346' label: 'No' metadata: count: 1 limit: 100 ErrorResponse: properties: detail: type: string title: Detail description: Human-readable error description. type: object title: ErrorResponse description: Generic API error response. PaginationMetadata: properties: count: type: integer minimum: 0 title: Count description: Number of items returned in this page. limit: type: integer maximum: 1000 minimum: 1 title: Limit description: Requested maximum number of items for this page. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: >- Opaque cursor to request the next page. Null when there are no more results. type: object title: PaginationMetadata description: Pagination metadata returned by list endpoints. MarketItem: properties: id: type: string title: Id description: Unique market identifier. examples: - '618831' slug: type: string title: Slug description: Stable URL-friendly market slug. examples: - will-candidate-x-win-2025 question: anyOf: - type: string - type: 'null' title: Question description: Human-readable market question. examples: - Will Candidate X win the 2025 election? status: type: string title: Status description: Current market status. examples: - open start_date: anyOf: - type: string format: date-time - type: 'null' title: Start Date description: Market start timestamp in ISO 8601 format. examples: - '2025-09-01T00:00:00Z' end_date: anyOf: - type: string format: date-time - type: 'null' title: End Date description: Market end timestamp in ISO 8601 format. examples: - '2025-11-05T23:59:59Z' tokens: items: $ref: '#/components/schemas/TokenInfo' type: array title: Tokens description: Token list for this market. type: object title: MarketItem description: Market object returned by `GET /markets`. TokenInfo: properties: id: type: string title: Id description: Unique token identifier. examples: - '12345' label: type: string title: Label description: Human-readable token label shown to users. examples: - 'Yes' type: object title: TokenInfo description: Token metadata for a market. ````