> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List events (keyset pagination)
> Returns events using cursor-based (keyset) pagination for stable, efficient paging through large result sets. Use `next_cursor` from each response as `after_cursor` in the next request. The `offset` parameter is explicitly rejected; use `after_cursor` instead.
## OpenAPI
````yaml /api-spec/gamma-openapi.yaml get /events/keyset
openapi: 3.0.3
info:
title: Markets API
version: 1.0.0
description: REST API specification for public endpoints used by the Markets service.
servers:
- url: https://gamma-api.polymarket.com
description: Polymarket Gamma API Production Server
security: []
tags:
- name: Gamma Status
description: Gamma API status and health check
- name: Sports
description: Sports-related endpoints including teams and game data
- name: Tags
description: Tag management and related tag operations
- name: Events
description: Event management and event-related operations
- name: Markets
description: Market data and market-related operations
- name: Comments
description: Comment system and user interactions
- name: Series
description: Series management and related operations
- name: Profiles
description: User profile management
- name: Search
description: Search functionality across different entity types
paths:
/events/keyset:
get:
tags:
- Events
summary: List events (keyset pagination)
description: >
Returns events using cursor-based (keyset) pagination for stable,
efficient paging through large result sets. Use `next_cursor` from each
response as `after_cursor` in the next request. The `offset` parameter
is explicitly rejected; use `after_cursor` instead.
operationId: listEventsKeyset
parameters:
- name: limit
in: query
description: Maximum number of results to return (max 500)
schema:
type: integer
minimum: 1
maximum: 500
default: 20
- name: order
in: query
description: Comma-separated list of JSON field names to order by
schema:
type: string
- name: ascending
in: query
description: Sort direction. Only used when order is set.
schema:
type: boolean
default: true
- name: after_cursor
in: query
description: Opaque cursor token from a previous response's next_cursor
schema:
type: string
- name: offset
in: query
description: Not allowed. Returns 422 if provided.
schema:
type: integer
- name: id
in: query
schema:
type: array
items:
type: integer
- name: slug
in: query
schema:
type: array
items:
type: string
- name: closed
in: query
schema:
type: boolean
- name: live
in: query
schema:
type: boolean
- name: featured
in: query
schema:
type: boolean
- name: cyom
in: query
schema:
type: boolean
- name: title_search
in: query
schema:
type: string
- name: liquidity_min
in: query
schema:
type: number
- name: liquidity_max
in: query
schema:
type: number
- name: volume_min
in: query
schema:
type: number
- name: volume_max
in: query
schema:
type: number
- name: start_date_min
in: query
schema:
type: string
format: date-time
- name: start_date_max
in: query
schema:
type: string
format: date-time
- name: end_date_min
in: query
schema:
type: string
format: date-time
- name: end_date_max
in: query
schema:
type: string
format: date-time
- name: start_time_min
in: query
schema:
type: string
format: date-time
- name: start_time_max
in: query
schema:
type: string
format: date-time
- name: tag_id
in: query
schema:
type: array
items:
type: integer
- name: tag_slug
in: query
schema:
type: string
- name: exclude_tag_id
in: query
description: Tag IDs to exclude. Cannot overlap with tag_id.
schema:
type: array
items:
type: integer
- name: related_tags
in: query
schema:
type: boolean
- name: tag_match
in: query
schema:
type: string
- name: series_id
in: query
schema:
type: array
items:
type: integer
- name: game_id
in: query
schema:
type: array
items:
type: integer
- name: event_date
in: query
schema:
type: string
format: date-time
- name: event_week
in: query
schema:
type: integer
- name: featured_order
in: query
schema:
type: boolean
- name: recurrence
in: query
schema:
type: string
- name: created_by
in: query
schema:
type: array
items:
type: string
- name: parent_event_id
in: query
schema:
type: integer
- name: include_children
in: query
schema:
type: boolean
- name: partner_slug
in: query
description: When set, external_partners are attached to matching events
schema:
type: string
- name: include_chat
in: query
description: When true, includes Chats and Series.Chats relations
schema:
type: boolean
- name: include_template
in: query
description: When true, includes Templates relation
schema:
type: boolean
- name: include_best_lines
in: query
description: When true, includes BestLines relation
schema:
type: boolean
- name: locale
in: query
schema:
type: string
responses:
'200':
description: >
Paginated list of events. Always includes Series, Tags, Markets, and
EventCreators relations. Chats/Series.Chats, Templates, and
BestLines are optional via their respective include_ flags. Nested
markets include clob_rewards and fee_schedule. Teams are enriched
automatically. external_partners attached only when partner_slug is
set.
content:
application/json:
schema:
$ref: '#/components/schemas/KeysetEventsResponse'
'422':
description: >
Validation error. Returned when offset is provided, cursor is
invalid, order fields are not valid, tag_id overlaps with
exclude_tag_id, invalid recurrence, or other filter validation
fails.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: Internal server error (DB failures, cursor encode failures)
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'503':
description: Service unavailable when keyset pagination is not configured