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

# Get events

> Retrieve a paginated list of events with filtering, sorting, and optional nested tags/markets



## OpenAPI

````yaml https://api.struct.to/openapi.json get /polymarket/events
openapi: 3.1.0
info:
  title: Polymarket API
  description: >-
    RESTful API for querying Polymarket prediction markets data including
    events, markets, traders, holders, and real-time metrics
  license:
    name: ''
  version: 1.0.0
servers:
  - url: https://api.struct.to/v1
security: []
paths:
  /polymarket/events:
    get:
      tags:
        - Events
      summary: Get events
      description: >-
        Retrieve a paginated list of events with filtering, sorting, and
        optional nested tags/markets
      operationId: get_events
      parameters:
        - name: id
          in: query
          description: >-
            Filter by event ID(s) - comma-separated (max 50). Cannot be used
            with 'event_slugs'. Example: id=99600,99601,99583
          required: false
          schema:
            type: string
        - name: event_slugs
          in: query
          description: >-
            Filter by event slug(s) - comma-separated (max 50). Cannot be used
            with 'id'. Example: event_slugs=will-trump-win,bitcoin-100k
          required: false
          schema:
            type: string
        - name: search
          in: query
          description: >-
            Search in title and description (3-100 characters). Example:
            search=trump
          required: false
          schema:
            type: string
        - name: sort_by
          in: query
          description: >-
            Sort: volume, txns, unique_traders, title, creation_date,
            start_date, end_date, relevance (relevance only works in search
            mode) (default: volume)
          required: false
          schema:
            $ref: '#/components/schemas/EventSortBy'
        - name: sort_dir
          in: query
          description: 'Sort direction: asc, desc (default: desc)'
          required: false
          schema:
            $ref: '#/components/schemas/SortDirection'
        - name: timeframe
          in: query
          description: 'Metrics timeframe: 1m, 5m, 30m, 1h, 6h, 24h, 7d, 30d (default: 24h)'
          required: false
          schema:
            $ref: '#/components/schemas/MetricsTimeframe'
        - name: status
          in: query
          description: 'Filter by status: open, closed, or all (default: all)'
          required: false
          schema:
            $ref: '#/components/schemas/MarketStatus'
        - name: categories
          in: query
          description: Comma-separated category filters
          required: false
          schema:
            type: string
        - name: exclude_categories
          in: query
          description: Comma-separated categories to exclude
          required: false
          schema:
            type: string
        - name: tags
          in: query
          description: >-
            Filter by tag slug(s) - comma-separated (max 50). Example:
            tags=sports,football,crypto
          required: false
          schema:
            type: string
        - name: exclude_tags
          in: query
          description: Comma-separated tag slugs to exclude
          required: false
          schema:
            type: string
        - name: min_volume
          in: query
          description: Minimum volume in selected timeframe
          required: false
          schema:
            type: number
            format: double
        - name: max_volume
          in: query
          description: Maximum volume in selected timeframe
          required: false
          schema:
            type: number
            format: double
        - name: min_txns
          in: query
          description: Minimum transactions in selected timeframe
          required: false
          schema:
            type: integer
            format: int32
        - name: max_txns
          in: query
          description: Maximum transactions in selected timeframe
          required: false
          schema:
            type: integer
            format: int32
        - name: min_unique_traders
          in: query
          description: Minimum unique traders in selected timeframe
          required: false
          schema:
            type: integer
            format: int32
        - name: max_unique_traders
          in: query
          description: Maximum unique traders in selected timeframe
          required: false
          schema:
            type: integer
            format: int32
        - name: include_tags
          in: query
          description: 'Include tags array (default: true)'
          required: false
          schema:
            type: boolean
        - name: include_markets
          in: query
          description: 'Include markets array with outcomes (default: true)'
          required: false
          schema:
            type: boolean
        - name: include_metrics
          in: query
          description: 'Include metrics object with all timeframes (default: true)'
          required: false
          schema:
            type: boolean
        - name: limit
          in: query
          description: 'Results limit (default: 10, max: 100)'
          required: false
          schema:
            type: integer
            format: int32
        - name: pagination_key
          in: query
          description: Cursor-based pagination key
          required: false
          schema:
            type: string
        - name: ai
          in: query
          description: >-
            Return truncated response optimized for AI consumers (default:
            false)
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: >-
            List of Polymarket events with nested tags, markets, and series.
            Response includes `pagination: { has_more, pagination_key }` for
            cursor-based pagination.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PolymarketEvent'
        '400':
          description: >-
            Bad request - validation error (search length, array limits,
            conflicting params)
components:
  schemas:
    EventSortBy:
      type: string
      enum:
        - volume
        - txns
        - unique_traders
        - title
        - creation_date
        - start_date
        - end_date
        - relevance
    SortDirection:
      type: string
      enum:
        - asc
        - desc
    MetricsTimeframe:
      type: string
      enum:
        - 1m
        - 5m
        - 30m
        - 1h
        - 6h
        - 24h
        - 7d
        - 30d
        - lifetime
    MarketStatus:
      type: string
      enum:
        - open
        - closed
        - all
    PolymarketEvent:
      type: object
      description: A Polymarket event from the Gamma API
      properties:
        id:
          type: string
          default: ''
        event_slug:
          type:
            - string
            - 'null'
          default: null
        title:
          type:
            - string
            - 'null'
          default: null
        ticker:
          type:
            - string
            - 'null'
          default: null
        description:
          type:
            - string
            - 'null'
          default: null
        resolution_source:
          type:
            - string
            - 'null'
          default: null
        category:
          type:
            - string
            - 'null'
          default: null
        image_url:
          type:
            - string
            - 'null'
          default: null
        market_count:
          type: integer
          format: int32
          default: 0
        created_time:
          type:
            - integer
            - 'null'
          format: int64
          default: null
        closed_time:
          type:
            - integer
            - 'null'
          format: int64
          default: null
        start_time:
          type:
            - integer
            - 'null'
          format: int64
          default: null
        end_time:
          type:
            - integer
            - 'null'
          format: int64
          default: null
        neg_risk:
          type: boolean
          default: false
        neg_risk_market_id:
          type:
            - string
            - 'null'
          default: null
        game_status:
          type:
            - string
            - 'null'
          default: null
        show_market_images:
          type: boolean
          default: false
        status:
          type:
            - string
            - 'null'
          description: 'Event status: "open" or "closed"'
          default: null
        metrics:
          type: object
          description: >-
            Per-timeframe metrics keyed by lookback window. Each timeframe key
            is optional — present only when data exists for that window.
          properties:
            1m:
              $ref: '#/components/schemas/SimpleTimeframeMetrics'
            5m:
              $ref: '#/components/schemas/SimpleTimeframeMetrics'
            30m:
              $ref: '#/components/schemas/SimpleTimeframeMetrics'
            1h:
              $ref: '#/components/schemas/SimpleTimeframeMetrics'
            6h:
              $ref: '#/components/schemas/SimpleTimeframeMetrics'
            24h:
              $ref: '#/components/schemas/SimpleTimeframeMetrics'
            7d:
              $ref: '#/components/schemas/SimpleTimeframeMetrics'
            30d:
              $ref: '#/components/schemas/SimpleTimeframeMetrics'
            lifetime:
              $ref: '#/components/schemas/SimpleTimeframeMetrics'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/PolymarketTag'
        markets:
          type: array
          items:
            $ref: '#/components/schemas/EventMarket'
        series:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/PolymarketSeries'
          default: null
    SimpleTimeframeMetrics:
      type: object
      properties:
        volume:
          type: number
          format: double
          default: 0
        shares_volume:
          type: number
          format: double
          default: 0
        builder_usd_volume:
          type: number
          format: double
          default: 0
        builder_shares_volume:
          type: number
          format: double
          default: 0
        fees:
          type: number
          format: double
          default: 0
        builder_fees:
          type: number
          format: double
          default: 0
        txns:
          type: integer
          format: int32
          default: 0
        builder_txns:
          type: integer
          format: int32
          default: 0
        unique_traders:
          type: integer
          format: int32
          default: 0
        unique_makers:
          type: integer
          format: int32
          default: 0
        unique_takers:
          type: integer
          format: int32
          default: 0
        unique_builder_traders:
          type: integer
          format: int32
          default: 0
    PolymarketTag:
      type: object
      description: A Polymarket tag from the Gamma API
      properties:
        id:
          type: string
          default: ''
        label:
          type: string
          default: ''
        slug:
          type:
            - string
            - 'null'
          default: null
        volume_usd:
          type: number
          format: double
        shares_volume:
          type: number
          format: double
        builder_usd_volume:
          type: number
          format: double
        builder_shares_volume:
          type: number
          format: double
        txn_count:
          type: integer
          format: int64
        builder_txn_count:
          type: integer
          format: int64
        unique_traders:
          type: integer
          format: int64
          description: Distinct active traders in the window.
        unique_makers:
          type: integer
          format: int64
        unique_takers:
          type: integer
          format: int64
        unique_builder_traders:
          type: integer
          format: int64
        fees_usd:
          type: number
          format: double
        builder_fees_usd:
          type: number
          format: double
    EventMarket:
      type: object
      description: Enriched market data for event API responses
      properties:
        condition_id:
          type: string
          default: ''
        id:
          type:
            - string
            - 'null'
          default: null
        title:
          type:
            - string
            - 'null'
          default: null
        question:
          type: string
          default: ''
        market_slug:
          type: string
          default: ''
        status:
          type: string
          default: ''
        created_time:
          type:
            - integer
            - 'null'
          format: int64
          default: null
        end_time:
          type:
            - integer
            - 'null'
          format: int64
          default: null
        volume:
          type:
            - number
            - 'null'
          format: double
          default: null
        liquidity_usd:
          type:
            - number
            - 'null'
          format: double
          default: null
        volume_24hr:
          type:
            - number
            - 'null'
          format: double
          default: null
        image_url:
          type:
            - string
            - 'null'
          default: null
        market_maker_address:
          type:
            - string
            - 'null'
          default: null
        creator:
          type:
            - string
            - 'null'
          default: null
        category:
          type:
            - string
            - 'null'
          default: null
        accepting_orders:
          type:
            - boolean
            - 'null'
          default: null
        uma_resolution_status:
          type:
            - string
            - 'null'
          default: null
        clob_rewards:
          type: array
          items:
            $ref: '#/components/schemas/ClobReward'
        outcomes:
          type: array
          items:
            $ref: '#/components/schemas/EventMarketOutcome'
        winning_outcome:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/EventMarketOutcome'
          default: null
    PolymarketSeries:
      type: object
      description: |-
        A Polymarket series from the Gamma API
        Series are parent groupings above events (e.g., "NBA Season 2024-25")
      properties:
        id:
          type: string
          default: ''
        slug:
          type:
            - string
            - 'null'
          default: null
        ticker:
          type:
            - string
            - 'null'
          default: null
        title:
          type:
            - string
            - 'null'
          default: null
        description:
          type:
            - string
            - 'null'
          default: null
        series_type:
          type:
            - string
            - 'null'
          default: null
        recurrence:
          type:
            - string
            - 'null'
          default: null
        layout:
          type:
            - string
            - 'null'
          default: null
        image_url:
          type:
            - string
            - 'null'
          default: null
        icon_url:
          type:
            - string
            - 'null'
          default: null
        active:
          type: boolean
          default: false
        closed:
          type: boolean
          default: false
        archived:
          type: boolean
          default: false
        featured:
          type: boolean
          default: false
        restricted:
          type: boolean
          default: false
        pyth_token_id:
          type:
            - string
            - 'null'
          default: null
        cg_asset_name:
          type:
            - string
            - 'null'
          default: null
        start_date:
          type:
            - integer
            - 'null'
          format: int64
          default: null
        event_count:
          type: integer
          format: int32
          default: 0
    ClobReward:
      type: object
      description: CLOB reward (public API format)
      required:
        - id
        - condition_id
      properties:
        id:
          type: string
        condition_id:
          type: string
        asset_address:
          type:
            - string
            - 'null'
        rewards_amount:
          type:
            - number
            - 'null'
          format: double
        rewards_daily_rate:
          type:
            - number
            - 'null'
          format: double
        start_date:
          type:
            - string
            - 'null'
        end_date:
          type:
            - string
            - 'null'
        rewards_max_spread:
          type:
            - number
            - 'null'
          format: double
        rewards_min_size:
          type:
            - number
            - 'null'
          format: double
        native_daily_rate:
          type:
            - number
            - 'null'
          format: double
        sponsored_daily_rate:
          type:
            - number
            - 'null'
          format: double
        total_daily_rate:
          type:
            - number
            - 'null'
          format: double
        sponsors_count:
          type:
            - integer
            - 'null'
          format: int32
    EventMarketOutcome:
      type: object
      description: Market outcome for event API responses
      required:
        - name
      properties:
        name:
          type: string
        price:
          type:
            - number
            - 'null'
          format: double
        position_id:
          type:
            - string
            - 'null'
        outcome_index:
          type:
            - integer
            - 'null'
          format: int32

````