> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polynode.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Event Catalog

> Walk the complete Polymarket event catalog with member-market counts and stable cursor pagination.

`GET /v3/events` groups markets by parent event slug and returns one event row
with status and member-market counts. Events are ordered by the latest update
among their member markets.

## Request

```text theme={null}
GET /v3/events
```

### Query parameters

| Parameter    | Type    | Default   | Description                                                           |
| ------------ | ------- | --------- | --------------------------------------------------------------------- |
| `limit`      | integer | 100       | Rows per page. Values below 1 use 1; values above 300 use 300.        |
| `cursor`     | string  | none      | Opaque `next_cursor` returned by the preceding page.                  |
| `status`     | string  | all       | `open`, `closed`, `inactive`, or `all`. Matching is case-insensitive. |
| `event_slug` | string  | none      | Exact event slug.                                                     |
| `sort`       | string  | `updated` | Only `updated` is available.                                          |
| `order`      | string  | `desc`    | Only `desc` is available.                                             |

Offset pagination is not supported on this route.

## Example

```bash theme={null}
curl "https://api.polynode.dev/v3/events?event_slug=example-event&limit=1" \
  -H "x-api-key: $POLYNODE_API_KEY"
```

```json theme={null}
{
  "events": [
    {
      "event_slug": "example-event",
      "title": "Example event",
      "status": "open",
      "active": true,
      "closed": false,
      "market_count": 2,
      "status_counts": {
        "open": 1,
        "closed": 1,
        "inactive": 0
      },
      "latest_market_updated_at": "2026-08-27T20:00:00Z",
      "title_variant_count": 1,
      "image_variant_count": 1,
      "icon_variant_count": 1,
      "image": "https://example.com/event.png",
      "representative_market": {
        "condition_id": "0x1111111111111111111111111111111111111111111111111111111111111111",
        "slug": "will-the-example-market-resolve-yes",
        "question": "Will the example market resolve Yes?",
        "end_date": null,
        "tag_slugs": ["example"]
      },
      "volume_all_time": null,
      "liquidity": null
    }
  ],
  "rows_returned": 1,
  "has_more": false,
  "limit": 1,
  "next_cursor": null,
  "sort": "updated",
  "order": "desc",
  "filters": {
    "status": null,
    "event_slug": "example-event"
  }
}
```

## Event status

An event is `open` while any member market is open. It is `closed` when every
member market is closed. Otherwise it is `inactive`.

## Response envelope

The envelope has the same cursor fields as the
[market catalog](/data/markets/catalog), with the page rows in `events`.
Pass `next_cursor` unchanged and keep the same filters. Stop when `has_more` is
`false`.

## Event fields

| Field                                       | Type    | Nullable | Description                                                                                  |
| ------------------------------------------- | ------- | -------- | -------------------------------------------------------------------------------------------- |
| `event_slug`                                | string  | no       | Event slug.                                                                                  |
| `title`                                     | string  | yes      | Representative event title.                                                                  |
| `status`                                    | string  | no       | `open`, `closed`, or `inactive`.                                                             |
| `active`, `closed`                          | boolean | no       | Status convenience flags.                                                                    |
| `market_count`                              | integer | no       | Member markets.                                                                              |
| `status_counts`                             | object  | no       | Open, closed, and inactive member-market counts.                                             |
| `latest_market_updated_at`                  | string  | yes      | Latest available update among member markets.                                                |
| `title_variant_count`                       | integer | no       | Distinct non-empty event titles among member markets.                                        |
| `image_variant_count`, `icon_variant_count` | integer | no       | Distinct non-empty image and icon URLs among member markets.                                 |
| `image`, `icon`                             | string  | yes      | Representative image URLs.                                                                   |
| `representative_market`                     | object  | no       | One member market with `condition_id`, `slug`, `question`, `end_date`, and `tag_slugs`.      |
| `volume_all_time`, `liquidity`              | null    | yes      | Reserved financial fields. This catalog currently returns `null`; do not treat them as zero. |

## Errors

| Status | Error                     | When it occurs                                                                                  |
| ------ | ------------------------- | ----------------------------------------------------------------------------------------------- |
| `400`  | `invalid_request`         | Invalid status, event slug, sort, order, or use of `offset`.                                    |
| `400`  | `invalid_cursor`          | A cursor is malformed, expired, belongs to the market route, or is used with different filters. |
| `401`  | authentication error      | The API key is missing or invalid.                                                              |
| `410`  | `invalid_cursor`          | The page walk referenced by the cursor is no longer available. Start again without a cursor.    |
| `503`  | `temporarily_unavailable` | Markets and events are temporarily unavailable.                                                 |


## OpenAPI

````yaml GET /v3/events
openapi: 3.1.0
info:
  title: PolyNode API
  description: >-
    Real-time Polymarket data API with decoded mempool settlements, OHLCV
    candles, and full Polygon JSON-RPC proxy.
  contact:
    name: PolyNode
    url: https://polynode.dev
  license:
    name: ''
  version: 2.0.0
servers:
  - url: https://api.polynode.dev
    description: Production
security:
  - api_key: []
paths:
  /v3/events:
    get:
      tags:
        - V3 Events
      summary: Complete event catalog
      description: Walk the complete event catalog using opaque cursor pagination.
      operationId: v3_event_catalog
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 300
        - name: cursor
          in: query
          schema:
            type: string
          description: Opaque next_cursor from the preceding page.
        - name: status
          in: query
          schema:
            type: string
            enum:
              - open
              - closed
              - inactive
              - all
            default: all
        - name: event_slug
          in: query
          schema:
            type: string
          description: Exact event slug.
        - name: sort
          in: query
          schema:
            type: string
            enum:
              - updated
            default: updated
        - name: order
          in: query
          schema:
            type: string
            enum:
              - desc
            default: desc
      responses:
        '200':
          description: Cursor-paginated events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3EventCatalogResponse'
        '400':
          description: Invalid request or cursor
        '401':
          description: Unauthorized
        '410':
          description: The cursor can no longer be continued
        '503':
          description: Markets and events are temporarily unavailable
      security:
        - api_key: []
components:
  schemas:
    V3EventCatalogResponse:
      type: object
      additionalProperties: false
      required:
        - events
        - rows_returned
        - has_more
        - limit
        - next_cursor
        - sort
        - order
        - filters
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/V3EventCatalogRow'
        rows_returned:
          type: integer
          minimum: 0
        has_more:
          type: boolean
        limit:
          type: integer
          minimum: 1
          maximum: 300
        next_cursor:
          type:
            - string
            - 'null'
        sort:
          type: string
          const: updated
        order:
          type: string
          const: desc
        filters:
          $ref: '#/components/schemas/V3CatalogFilters'
    V3EventCatalogRow:
      type: object
      additionalProperties: false
      required:
        - event_slug
        - status
        - active
        - closed
        - market_count
        - status_counts
        - title_variant_count
        - image_variant_count
        - icon_variant_count
        - representative_market
        - volume_all_time
        - liquidity
      properties:
        event_slug:
          type: string
        title:
          type: string
        status:
          $ref: '#/components/schemas/V3CatalogStatus'
        active:
          type: boolean
        closed:
          type: boolean
        market_count:
          type: integer
          minimum: 1
        status_counts:
          $ref: '#/components/schemas/V3CatalogStatusCounts'
        latest_market_updated_at:
          type: string
        title_variant_count:
          type: integer
          minimum: 0
        image_variant_count:
          type: integer
          minimum: 0
        icon_variant_count:
          type: integer
          minimum: 0
        image:
          type: string
        icon:
          type: string
        representative_market:
          $ref: '#/components/schemas/V3EventRepresentativeMarket'
        volume_all_time:
          type: 'null'
        liquidity:
          type: 'null'
    V3CatalogFilters:
      type: object
      additionalProperties: false
      required:
        - status
        - event_slug
      properties:
        status:
          oneOf:
            - $ref: '#/components/schemas/V3CatalogStatus'
            - type: 'null'
        event_slug:
          type:
            - string
            - 'null'
    V3CatalogStatus:
      type: string
      enum:
        - open
        - closed
        - inactive
    V3CatalogStatusCounts:
      type: object
      additionalProperties: false
      required:
        - open
        - closed
        - inactive
      properties:
        open:
          type: integer
          minimum: 0
        closed:
          type: integer
          minimum: 0
        inactive:
          type: integer
          minimum: 0
    V3EventRepresentativeMarket:
      type: object
      additionalProperties: false
      required:
        - condition_id
        - slug
        - question
        - end_date
        - tag_slugs
      properties:
        condition_id:
          type: string
        slug:
          type:
            - string
            - 'null'
        question:
          type:
            - string
            - 'null'
        end_date:
          type:
            - string
            - 'null'
        tag_slugs:
          type: array
          items:
            type: string
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: x-api-key

````