> ## 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.

# Events

> Retrieve and filter events

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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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 |

```typescript theme={null}
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)}`);
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.