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

# List Events

> List events with filtering, sorting, and cursor-based pagination

Events are top-level groupings that contain one or more markets. Use `status=open` for active events only.

<Tip>**Free & Unlimited.** This endpoint does not count toward your monthly usage limits on any plan.</Tip>

### Nesting markets and filtering by liquidity

Pass `include_markets=true` to nest each event's markets inline (same shape as [List Markets](/api-reference/markets/list-markets)), and `markets_per_event` (1–50, default 10) to cap how many are nested per event. Filter to liquid events with `min_open_interest` (current OI in USD) and `min_volume` (7-day volume in USD).

### Pagination

This endpoint uses cursor-based (keyset) pagination, which stays stable for large backfills and long-running crawls and does not return a `total` count. To fetch the next page, pass the returned `pagination.pagination_key` as the next request's `pagination_key`, keeping the same filter and sort parameters across pages.

| Constraint       | Value                                      |
| ---------------- | ------------------------------------------ |
| `limit`          | 1–100 (default 20)                         |
| `pagination_key` | Cursor returned from the previous response |


## OpenAPI

````yaml GET /v2/polymarket/events/keyset
openapi: 3.1.0
info:
  title: Predexon API
  description: Prediction market data aggregation and matching API
  version: 2.0.0
servers:
  - url: https://api.predexon.com
security:
  - apiKey: []
paths:
  /v2/polymarket/events/keyset:
    get:
      tags:
        - polymarket
      summary: Get Events
      description: >-
        List events with filtering and sorting.


        Events are top-level groupings that contain one or more markets. Use

        status=open for active events only. With include_markets=true, each
        event

        carries up to markets_per_event of its markets inline (volume-sorted) —
        for

        deep per-event market pagination use GET /markets?event_slug=.
      operationId: get_events_v2_polymarket_events_keyset_get
      parameters:
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/EventStatusOption'
              - type: 'null'
            description: 'Filter by status: open or closed'
            title: Status
          description: 'Filter by status: open or closed'
        - name: category
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter by category (e.g. Sports, Crypto)
            title: Category
          description: Filter by category (e.g. Sports, Crypto)
        - name: search
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                minLength: 3
                maxLength: 100
              - type: 'null'
            description: Search in title (minimum 3 characters)
            title: Search
          description: Search in title (minimum 3 characters)
        - name: id
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                maxItems: 50
              - type: 'null'
            description: Filter by event ID(s)
            title: Id
          description: Filter by event ID(s)
        - name: slug
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                maxItems: 50
              - type: 'null'
            description: Filter by event slug(s)
            title: Slug
          description: Filter by event slug(s)
        - name: tag
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                maxItems: 50
              - type: 'null'
            description: Filter by tag slug(s)
            title: Tag
          description: Filter by tag slug(s)
        - name: sort
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/EventSortOption'
            description: Sort by
            default: created
          description: Sort by
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            description: Number of events to return
            default: 20
            title: Limit
          description: Number of events to return
        - name: pagination_key
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Cursor returned from the previous response
            title: Pagination Key
          description: Cursor returned from the previous response
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            description: >-
              Deprecated. Offset pagination has been removed; only 0 is
              accepted.
            default: 0
            title: Offset
          description: Deprecated. Offset pagination has been removed; only 0 is accepted.
          deprecated: true
        - name: include_markets
          in: query
          required: false
          schema:
            type: boolean
            description: Nest each event's markets inline (same shape as /markets)
            default: false
            title: Include Markets
          description: Nest each event's markets inline (same shape as /markets)
        - name: markets_per_event
          in: query
          required: false
          schema:
            type: integer
            maximum: 50
            minimum: 1
            description: Max markets nested per event when include_markets=true
            default: 10
            title: Markets Per Event
          description: Max markets nested per event when include_markets=true
        - name: min_volume
          in: query
          required: false
          schema:
            anyOf:
              - type: number
                minimum: 0
              - type: 'null'
            description: Only events with 7d volume >= this (USD)
            title: Min Volume
          description: Only events with 7d volume >= this (USD)
        - name: min_open_interest
          in: query
          required: false
          schema:
            anyOf:
              - type: number
                minimum: 0
              - type: 'null'
            description: Only events with current open interest >= this (USD)
            title: Min Open Interest
          description: Only events with current open interest >= this (USD)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolymarketEventsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    EventStatusOption:
      type: string
      enum:
        - open
        - closed
      title: EventStatusOption
    EventSortOption:
      type: string
      enum:
        - created
        - created_asc
        - start_date
        - start_date_asc
        - end_date
        - end_date_desc
        - title
        - relevance
        - volume_1d
        - volume_7d
        - volume_30d
        - volume_all_time
        - open_interest
        - trades_1d
        - trades_7d
        - trades_30d
      title: EventSortOption
    PolymarketEventsResponse:
      properties:
        events:
          items:
            $ref: '#/components/schemas/PolymarketEvent'
          type: array
          title: Events
        pagination:
          $ref: '#/components/schemas/CursorPagination'
      type: object
      required:
        - events
        - pagination
      title: PolymarketEventsResponse
      description: Response for Polymarket events list endpoint.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PolymarketEvent:
      properties:
        id:
          type: string
          title: Id
        ticker:
          type: string
          title: Ticker
          default: ''
        slug:
          type: string
          title: Slug
          default: ''
        title:
          type: string
          title: Title
          default: ''
        description:
          type: string
          title: Description
          default: ''
        category:
          type: string
          title: Category
          default: ''
        tags:
          items:
            type: object
          type: array
          title: Tags
        series:
          items:
            type: object
          type: array
          title: Series
        image_url:
          type: string
          title: Image Url
          default: ''
        icon_url:
          type: string
          title: Icon Url
          default: ''
        resolution_source:
          type: string
          title: Resolution Source
          default: ''
        start_date:
          anyOf:
            - type: string
            - type: 'null'
          title: Start Date
          description: ISO 8601 timestamp
        end_date:
          anyOf:
            - type: string
            - type: 'null'
          title: End Date
          description: ISO 8601 timestamp
        creation_date:
          anyOf:
            - type: string
            - type: 'null'
          title: Creation Date
          description: ISO 8601 timestamp
        closed_time:
          anyOf:
            - type: string
            - type: 'null'
          title: Closed Time
          description: ISO 8601 timestamp
        neg_risk:
          type: boolean
          title: Neg Risk
          default: false
        neg_risk_market_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Neg Risk Market Id
        enable_order_book:
          type: boolean
          title: Enable Order Book
          default: false
        status:
          type: string
          title: Status
          default: open
        market_count:
          type: integer
          title: Market Count
          default: 0
        total_volume_usd:
          type: number
          title: Total Volume Usd
          default: 0
        trades_all_time:
          type: integer
          title: Trades All Time
          default: 0
        liquidity_usd:
          type: number
          title: Liquidity Usd
          default: 0
        current_oi_usd:
          type: number
          title: Current Oi Usd
          default: 0
        rolling_metrics:
          anyOf:
            - type: object
            - type: 'null'
          title: Rolling Metrics
        markets:
          anyOf:
            - items:
                $ref: '#/components/schemas/PolymarketMarket'
              type: array
            - type: 'null'
          title: Markets
      type: object
      required:
        - id
      title: PolymarketEvent
      description: Polymarket event in list response.
    CursorPagination:
      properties:
        limit:
          type: integer
          title: Limit
          description: Requested limit
        count:
          type: integer
          title: Count
          description: Number of items in current response
        pagination_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Pagination Key
          description: Base64-encoded cursor for next page
        has_more:
          type: boolean
          title: Has More
          description: Whether there are more items available
      type: object
      required:
        - limit
        - count
        - has_more
      title: CursorPagination
      description: Cursor-based pagination for endpoints that don't support offset.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    PolymarketMarket:
      properties:
        condition_id:
          type: string
          title: Condition Id
        question_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Question Id
        market_id:
          type: string
          title: Market Id
        market_slug:
          type: string
          title: Market Slug
        title:
          type: string
          title: Title
        description:
          type: string
          title: Description
          default: ''
        status:
          type: string
          title: Status
        winning_side:
          anyOf:
            - type: string
            - type: 'null'
          title: Winning Side
        start_time:
          anyOf:
            - type: string
            - type: 'null'
          title: Start Time
          description: ISO 8601 timestamp
        end_time:
          anyOf:
            - type: string
            - type: 'null'
          title: End Time
          description: ISO 8601 timestamp
        close_time:
          anyOf:
            - type: string
            - type: 'null'
          title: Close Time
          description: ISO 8601 timestamp
        created_time:
          anyOf:
            - type: string
            - type: 'null'
          title: Created Time
          description: ISO 8601 timestamp
        image_url:
          type: string
          title: Image Url
          default: ''
        event_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Event Id
        event_slug:
          anyOf:
            - type: string
            - type: 'null'
          title: Event Slug
        event_title:
          anyOf:
            - type: string
            - type: 'null'
          title: Event Title
        outcomes:
          items:
            $ref: '#/components/schemas/PolymarketOutcome'
          type: array
          title: Outcomes
        total_volume_usd:
          type: number
          title: Total Volume Usd
          default: 0
        liquidity_usd:
          type: number
          title: Liquidity Usd
          default: 0
        tags:
          items:
            type: string
          type: array
          title: Tags
        is_neg_risk:
          type: boolean
          title: Is Neg Risk
          default: false
        rolling_metrics:
          anyOf:
            - $ref: '#/components/schemas/MarketRollingMetrics'
            - type: 'null'
          description: Rolling window metrics (1D/7D/30D) from hourly cron refresh
      type: object
      required:
        - condition_id
        - market_id
        - market_slug
        - title
        - status
        - outcomes
      title: PolymarketMarket
      description: Polymarket market in list response.
    PolymarketOutcome:
      properties:
        label:
          type: string
          title: Label
        token_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Token Id
        predexon_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Predexon Id
        price:
          anyOf:
            - type: number
            - type: 'null'
          title: Price
      type: object
      required:
        - label
      title: PolymarketOutcome
      description: Outcome for a Polymarket market.
    MarketRollingMetrics:
      properties:
        volume_1d:
          type: number
          title: Volume 1D
          description: Volume in USD over last 24 hours
          default: 0
        volume_7d:
          type: number
          title: Volume 7D
          description: Volume in USD over last 7 days
          default: 0
        volume_30d:
          type: number
          title: Volume 30D
          description: Volume in USD over last 30 days
          default: 0
        buy_volume_1d:
          type: number
          title: Buy Volume 1D
          description: Buy volume (USD) last 24h
          default: 0
        buy_volume_7d:
          type: number
          title: Buy Volume 7D
          description: Buy volume (USD) last 7d
          default: 0
        buy_volume_30d:
          type: number
          title: Buy Volume 30D
          description: Buy volume (USD) last 30d
          default: 0
        sell_volume_1d:
          type: number
          title: Sell Volume 1D
          description: Sell volume (USD) last 24h
          default: 0
        sell_volume_7d:
          type: number
          title: Sell Volume 7D
          description: Sell volume (USD) last 7d
          default: 0
        sell_volume_30d:
          type: number
          title: Sell Volume 30D
          description: Sell volume (USD) last 30d
          default: 0
        trades_1d:
          type: integer
          title: Trades 1D
          description: Trade count last 24h
          default: 0
        trades_7d:
          type: integer
          title: Trades 7D
          description: Trade count last 7d
          default: 0
        trades_30d:
          type: integer
          title: Trades 30D
          description: Trade count last 30d
          default: 0
        buys_1d:
          type: integer
          title: Buys 1D
          description: Buy trades last 24h
          default: 0
        buys_7d:
          type: integer
          title: Buys 7D
          description: Buy trades last 7d
          default: 0
        buys_30d:
          type: integer
          title: Buys 30D
          description: Buy trades last 30d
          default: 0
        sells_1d:
          type: integer
          title: Sells 1D
          description: Sell trades last 24h
          default: 0
        sells_7d:
          type: integer
          title: Sells 7D
          description: Sell trades last 7d
          default: 0
        sells_30d:
          type: integer
          title: Sells 30D
          description: Sell trades last 30d
          default: 0
        oi_change_1d:
          type: number
          title: Oi Change 1D
          description: OI change over last 24h (USD)
          default: 0
        oi_change_7d:
          type: number
          title: Oi Change 7D
          description: OI change over last 7d (USD)
          default: 0
        oi_change_30d:
          type: number
          title: Oi Change 30D
          description: OI change over last 30d (USD)
          default: 0
        computed_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Computed At
          description: ISO 8601 timestamp when metrics were last computed
      type: object
      title: MarketRollingMetrics
      description: >-
        Rolling window metrics from market_metrics_summary (hourly cron
        refresh).
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````