Documentation Index
Fetch the complete documentation index at: https://docs.polymarket.us/llms.txt
Use this file to discover all available pages before exploring further.
The Events resource provides access to event data. Events contain one or more markets and represent the underlying question or competition being predicted.
Methods
| Method | Endpoint | Description |
|---|
list(params?) | GET /v1/events | List events with filtering |
retrieve(id) | GET /v1/events/{id} | Get event by ID |
retrieveBySlug(slug) | GET /v1/events/slug/{slug} | Get event by URL slug |
list
Fetch a paginated list of events with optional filters.
const events = await client.events.list({
limit: 10,
offset: 0,
active: true,
categories: ['sports', 'crypto'],
});
for (const event of events.events) {
console.log(`${event.title} - ${event.markets?.length ?? 0} markets`);
}
Parameters
| Parameter | Type | Description |
|---|
limit | number | Maximum results to return (default: 100) |
offset | number | Number of results to skip for pagination |
active | boolean | Filter by active events |
closed | boolean | Filter by closed events |
archived | boolean | Filter by archived events |
featured | boolean | Filter featured events only |
categories | string[] | Filter by category slugs |
seriesId | number[] | Filter by series IDs |
live | boolean | Filter live sports events |
ended | boolean | Filter ended sports events |
Response Fields
| Field | Type | Description |
|---|
id | number | Unique event identifier |
slug | string | URL-friendly identifier |
title | string | Event title |
description | string | Event description |
category | string | Primary category |
active | boolean | Whether event is active for trading |
closed | boolean | Whether event is closed |
markets | array | Associated markets |
retrieve
Get a single event by its numeric ID.
const event = await client.events.retrieve(12345);
console.log(`Title: ${event.title}`);
console.log(`Category: ${event.category}`);
console.log(`Markets: ${event.markets?.length ?? 0}`);
Parameters
| Parameter | Type | Description |
|---|
id | number | Event ID |
retrieveBySlug
Get an event by its URL slug. Useful when you have the slug from a URL or API response.
const event = await client.events.retrieveBySlug('super-bowl-2025');
console.log(`Title: ${event.title}`);
for (const market of event.markets ?? []) {
console.log(` - ${market.title}: ${market.slug}`);
}
Parameters
| Parameter | Type | Description |
|---|
slug | string | Event URL slug |
Sports Event Fields
Sports events include additional real-time data:
| Field | Type | Description |
|---|
gameId | string | Sports provider game ID |
live | boolean | Whether game is in progress |
ended | boolean | Whether game has ended |
score | object | Current score |
period | string | Current period/quarter/half |
participants | array | Teams or players |
const events = await client.events.list({ live: true, categories: ['sports'] });
for (const event of events.events) {
if (event.live) {
console.log(`${event.title}: ${JSON.stringify(event.score)}`);
}
}
