---
title: "Polymarket Events"
method: GET
path: "/gateway/v1/prediction-market/polymarket/events"
tags: ["Prediction Market"]
---

# Polymarket Events

`GET /gateway/v1/prediction-market/polymarket/events`

## Request

- Base URL: `https://api.asksurf.ai`
- URL: `https://api.asksurf.ai/gateway/v1/prediction-market/polymarket/events`
- Auth: HTTP bearer

Returns Polymarket events with nested markets, optionally filtered by `event_slug`.

Each event includes aggregated status, volume, and a list of markets with `side_a`/`side_b` outcomes.

**Data refresh:** ~30 minutes

## Query parameters

- `event_slug` string, required: Polymarket event slug (identifies a multi-outcome question with several nested markets). Known World Cup match sibling slugs are expanded to the canonical match group. Discover slugs via /v1/search/prediction-market?platform=polymarket&q={keyword}. For a single Yes/No market, use /polymarket/markets with market_slug instead — this endpoint only accepts event_slug, not market_slug.
- `limit` integer: Results per page
- `offset` integer: Pagination offset

## Response `200`

OK

- DataResponsePolymarketEvent
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `data` PolymarketEvent[], nullable, required
    - `category` string: Surf curated event category
    - `description` string: Event description
    - `end_time` integer: Event end time (Unix seconds)
    - `event_slug` string, required: Event identifier slug
    - `image` string: Event image URL
    - `market_count` integer, required: Number of markets in this event
    - `markets` PolymarketMarketItem[], nullable, required: Markets within this event
      - `category` string: Surf curated market category
      - `close_time` integer: Market close time (Unix seconds)
      - `completed_time` integer: Resolution time (Unix seconds)
      - `condition_id` string, required: Unique condition identifier
      - `description` string: Market description
      - `end_time` integer: Market end time (Unix seconds)
      - `event_slug` string: Event identifier slug
      - `game_start_time` integer: Game start time for sports markets (Unix seconds)
      - `image` string: Market image URL
      - `market_slug` string, required: Market identifier slug
      - `negative_risk_id` string: Negative risk market identifier
      - `polymarket_link` string: Link to Polymarket page
      - `resolution_source` string: URL to resolution data source
      - `side_a` PolymarketMarketSide
        - `id` string, required: Token identifier for this outcome
        - `label` string, required: Outcome label
      - `side_b` PolymarketMarketSide
        - `id` string, required: Token identifier for this outcome
        - `label` string, required: Outcome label
      - `start_time` integer: Market start time (Unix seconds)
      - `status` string, required: Market status: `open` or `closed`
      - `subcategory` string: Surf curated market subcategory
      - `tags` string[], nullable: Market tags
      - `title` string, required: Market title
      - `volume_1_month` number, double, required: Trading volume in the past month (USD)
      - `volume_1_week` number, double, required: Trading volume in the past week (USD)
      - `volume_1_year` number, double, required: Trading volume in the past year (USD)
      - `volume_total` number, double, required: Total trading volume (USD)
      - `winning_side` string: Winning outcome label, if resolved
    - `settlement_sources` string: Resolution source URL
    - `start_time` integer: Event start time (Unix seconds)
    - `status` string, required: Event status: `open` if any market is open, `closed` if all markets are closed
    - `subcategory` string: Surf curated event subcategory
    - `tags` string[], nullable: Event tags
    - `title` string, required: Event title
    - `volume_total` number, double, required: Total event volume across all markets (USD)
  - `meta` OffsetMeta, required
    - `cached` boolean, required: Whether this response was served from cache
    - `credits_used` integer, required: Credits deducted for this request
    - `empty_reason` string: Hint explaining why the data array is empty, when applicable
    - `has_more` boolean: Whether more items may exist beyond this response. For offset-paged endpoints, continue with a larger offset. For time-series endpoints without offset/cursor controls, true means the requested time range hit an upstream cap; narrow from/to to continue. Omitted when exhaustion cannot be proven.
    - `limit` integer, required: Maximum number of items returned in this response
    - `offset` integer, required: Number of items skipped (pagination offset)
    - `total` integer: Total number of matching items (before pagination). Omitted when total is unknown.
    - `watermark` integer: Warehouse watermark (Unix seconds) this response was computed at, on warehouse-backed endpoints (e.g. Hyperliquid /trades/aggregate) — rows up to this time come from the warehouse, newer rows from the live tail. Omitted elsewhere.

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api.md) - [All operations](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/revisions/91774fdd5302?raw)