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

# List combo markets

> Returns combo (parlay) markets with leg metadata, status, volume, trader activity, prices, and lifecycle statistics. Use `timeframe` to choose the activity window and `pagination_key` from the previous response to request the next page.



## OpenAPI

````yaml https://api.struct.to/openapi.json get /polymarket/combos
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/combos:
    get:
      tags:
        - Combos
      summary: List combo markets
      description: >-
        Returns combo (parlay) markets with leg metadata, status, volume, trader
        activity, prices, and lifecycle statistics. Use `timeframe` to choose
        the activity window and `pagination_key` from the previous response to
        request the next page.
      operationId: list_combo_markets
      parameters:
        - name: timeframe
          in: query
          description: 'Metrics window. Default: lifetime'
          required: false
          schema:
            $ref: '#/components/schemas/ComboMarketTimeframe'
        - name: sort_by
          in: query
          description: 'Sort field. Default: usd_volume'
          required: false
          schema:
            $ref: '#/components/schemas/ComboMarketSortBy'
        - name: sort_dir
          in: query
          description: 'Sort direction. Default: desc'
          required: false
          schema:
            $ref: '#/components/schemas/SortDirection'
        - name: status
          in: query
          description: Filter by combo state
          required: false
          schema:
            $ref: '#/components/schemas/ComboMarketStatusFilter'
        - name: condition_id
          in: query
          description: Return one combo by condition id
          required: false
          schema:
            type: string
        - name: creator
          in: query
          description: Only return combos created by this wallet address
          required: false
          schema:
            type: string
        - name: leg_condition_id
          in: query
          description: Only return combos that include this market condition id
          required: false
          schema:
            type: string
        - name: market_slug
          in: query
          description: Only return combos that include this market slug
          required: false
          schema:
            type: string
        - name: event_slug
          in: query
          description: Only return combos that include this event slug
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Page size. Default 50, max 250
          required: false
          schema:
            type: integer
            format: int64
        - name: pagination_key
          in: query
          description: Cursor from the previous response's pagination.pagination_key
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Combo markets and pagination metadata
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ComboMarket'
        '400':
          description: Invalid parameter
components:
  schemas:
    ComboMarketTimeframe:
      type: string
      enum:
        - 1m
        - 5m
        - 30m
        - 1h
        - 6h
        - 24h
        - 7d
        - 30d
        - lifetime
    ComboMarketSortBy:
      type: string
      enum:
        - usd_volume
        - shares_volume
        - unique_traders
        - status
        - builder_usd_volume
        - fees
        - txns
    SortDirection:
      type: string
      enum:
        - asc
        - desc
    ComboMarketStatusFilter:
      type: string
      description: >-
        Combo status filter.


        `open` means the combo has not reached a final outcome.

        `resolved_yes` means the YES side resolved as the winning side.

        `resolved_no` means the NO side resolved as the winning side.

        `resolved_split` means both YES and NO sides resolved with non-zero
        payouts.

        `resolved_zero` means both YES and NO sides resolved with zero payout.
      enum:
        - open
        - resolved_yes
        - resolved_no
        - resolved_split
        - resolved_zero
    ComboMarket:
      type: object
      required:
        - condition_id
        - timeframe
        - combo_type
        - yes_position_id
        - no_position_id
        - leg_count
        - legs_won
        - legs_lost
        - legs_pending
        - legs
        - usd_volume
        - usd_buy_volume
        - usd_sell_volume
        - shares_volume
        - shares_buy_volume
        - shares_sell_volume
        - fees
        - builder_fees
        - builder_usd_volume
        - builder_usd_buy_volume
        - builder_usd_sell_volume
        - builder_shares_volume
        - builder_shares_buy_volume
        - builder_shares_sell_volume
        - txns
        - buys
        - sells
        - builder_txns
        - builder_buys
        - builder_sells
        - unique_traders
        - unique_makers
        - unique_takers
        - unique_builder_traders
        - lifecycle_shares
        - redeemed_payout
        - compressed_collateral_out
        - execution_count
        - status_update_count
        - positions_split_count
        - positions_merged_count
        - split_on_condition_count
        - merged_on_condition_count
        - extracted_count
        - injected_count
        - converted_to_yes_basket_count
        - merged_from_yes_basket_count
        - compressed_count
        - redeemed_count
        - wrapped_count
        - unwrapped_count
        - horizontal_split_count
        - horizontal_merge_count
        - position_converted_count
        - migrated_count
        - updated_at
      properties:
        condition_id:
          type: string
          description: Combo condition id.
        creator:
          type:
            - string
            - 'null'
          description: Address that created the combo.
        timeframe:
          type: string
          description: Metrics window used for this row.
        combo_type:
          type: string
          description: Combo type.
        yes_position_id:
          type: string
          description: Yes-side position id.
        no_position_id:
          type: string
          description: No-side position id.
        timestamp:
          type: integer
          format: int64
          description: Window timestamp in Unix seconds.
        created_block:
          type:
            - integer
            - 'null'
          format: int64
          description: First block where the combo was seen.
        created_at:
          type:
            - integer
            - 'null'
          format: int64
          description: First timestamp where the combo was seen.
        created_tx:
          type:
            - string
            - 'null'
        first_trade_at:
          type:
            - integer
            - 'null'
          format: int64
        latest_trade_at:
          type:
            - integer
            - 'null'
          format: int64
        status:
          type:
            - string
            - 'null'
          description: >-
            Combo state: open, resolved_yes, resolved_no, resolved_split, or
            resolved_zero.
        leg_count:
          type: integer
          format: int32
        legs_won:
          type: integer
          format: int32
        legs_lost:
          type: integer
          format: int32
        legs_pending:
          type: integer
          format: int32
        legs:
          type: array
          items:
            $ref: '#/components/schemas/ComboMarketLeg'
        implied_probability_yes:
          type:
            - number
            - 'null'
          format: double
        implied_probability_no:
          type:
            - number
            - 'null'
          format: double
        usd_volume:
          type: number
          format: double
        usd_buy_volume:
          type: number
          format: double
        usd_sell_volume:
          type: number
          format: double
        shares_volume:
          type: number
          format: double
        shares_buy_volume:
          type: number
          format: double
        shares_sell_volume:
          type: number
          format: double
        fees:
          type: number
          format: double
        builder_fees:
          type: number
          format: double
        builder_usd_volume:
          type: number
          format: double
        builder_usd_buy_volume:
          type: number
          format: double
        builder_usd_sell_volume:
          type: number
          format: double
        builder_shares_volume:
          type: number
          format: double
        builder_shares_buy_volume:
          type: number
          format: double
        builder_shares_sell_volume:
          type: number
          format: double
        txns:
          type: integer
          format: int64
        buys:
          type: integer
          format: int64
        sells:
          type: integer
          format: int64
        builder_txns:
          type: integer
          format: int64
        builder_buys:
          type: integer
          format: int64
        builder_sells:
          type: integer
          format: int64
        unique_traders:
          type: integer
          format: int64
        unique_makers:
          type: integer
          format: int64
        unique_takers:
          type: integer
          format: int64
        unique_builder_traders:
          type: integer
          format: int64
        price:
          type:
            - number
            - 'null'
          format: double
        avg_trade_usd:
          type:
            - number
            - 'null'
          format: double
        avg_buy_usd:
          type:
            - number
            - 'null'
          format: double
        avg_sell_usd:
          type:
            - number
            - 'null'
          format: double
        avg_trade_shares:
          type:
            - number
            - 'null'
          format: double
        avg_buy_shares:
          type:
            - number
            - 'null'
          format: double
        avg_sell_shares:
          type:
            - number
            - 'null'
          format: double
        lifecycle_shares:
          type: number
          format: double
        redeemed_payout:
          type: number
          format: double
        compressed_collateral_out:
          type: number
          format: double
        execution_count:
          type: integer
          format: int64
        status_update_count:
          type: integer
          format: int64
        positions_split_count:
          type: integer
          format: int64
        positions_merged_count:
          type: integer
          format: int64
        split_on_condition_count:
          type: integer
          format: int64
        merged_on_condition_count:
          type: integer
          format: int64
        extracted_count:
          type: integer
          format: int64
        injected_count:
          type: integer
          format: int64
        converted_to_yes_basket_count:
          type: integer
          format: int64
        merged_from_yes_basket_count:
          type: integer
          format: int64
        compressed_count:
          type: integer
          format: int64
        redeemed_count:
          type: integer
          format: int64
        wrapped_count:
          type: integer
          format: int64
        unwrapped_count:
          type: integer
          format: int64
        horizontal_split_count:
          type: integer
          format: int64
        horizontal_merge_count:
          type: integer
          format: int64
        position_converted_count:
          type: integer
          format: int64
        migrated_count:
          type: integer
          format: int64
        updated_at:
          type: integer
          format: int64
          description: Last refresh time in Unix milliseconds.
    ComboMarketLeg:
      type: object
      required:
        - position_id
        - v2_condition_id
        - leg_market_type
        - outcome_index
      properties:
        position_id:
          type: string
          description: Position id for this leg.
        v2_condition_id:
          type: string
          description: Alternate condition id form for this leg.
        condition_id:
          type:
            - string
            - 'null'
          description: Market condition id for this leg.
        leg_market_type:
          type: string
          description: Type of market this leg belongs to.
        outcome_index:
          type: integer
          format: int32
          description: Outcome index selected for this leg.
          minimum: 0
        outcome:
          type:
            - string
            - 'null'
          description: Display name of the selected outcome.
        last_price:
          type:
            - number
            - 'null'
          format: double
          description: Latest traded price for the selected outcome.
        status:
          type:
            - string
            - 'null'
          description: 'Leg result: won, lost, or pending.'
        market_slug:
          type:
            - string
            - 'null'
        event_slug:
          type:
            - string
            - 'null'
        question:
          type:
            - string
            - 'null'
        title:
          type:
            - string
            - 'null'
        image_url:
          type:
            - string
            - 'null'

````