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

# Search events, markets, traders, and builders

> Search across markets, events, traders, and builders. Use `type` to limit which categories are searched. Event and market search support exact slug lookup when `q` is slug-shaped. Trader search supports wallet address lookup or name search; builder search matches against builder name and builder_code. Results for each category are independently paginated. Only requested categories are included in the response.



## OpenAPI

````yaml https://api.struct.to/openapi.json get /polymarket/search
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/search:
    get:
      tags:
        - Search
      summary: Search events, markets, traders, and builders
      description: >-
        Search across markets, events, traders, and builders. Use `type` to
        limit which categories are searched. Event and market search support
        exact slug lookup when `q` is slug-shaped. Trader search supports wallet
        address lookup or name search; builder search matches against builder
        name and builder_code. Results for each category are independently
        paginated. Only requested categories are included in the response.
      operationId: search
      parameters:
        - name: q
          in: query
          description: >-
            Search query (min 2 characters). Slug-shaped values match
            event/market slugs. Prefix with 0x for exact wallet address lookup.
          required: true
          schema:
            type: string
        - name: type
          in: query
          description: >-
            Comma-separated categories to search: events, markets, traders,
            builders (default: all four). Example: type=markets,builders
          required: false
          schema:
            type: string
        - name: include_pnl
          in: query
          description: 'Include lifetime PnL summary for each trader (default: false)'
          required: false
          schema:
            type: boolean
        - name: sort_by
          in: query
          description: >-
            Sort field applied to both events and markets (default: volume).
            Fields marked events-only or markets-only fall back to volume on the
            other category.
          required: false
          schema:
            $ref: '#/components/schemas/SearchSortBy'
        - name: sort_dir
          in: query
          description: 'Sort direction (default: desc)'
          required: false
          schema:
            $ref: '#/components/schemas/SortDirection'
        - name: timeframe
          in: query
          description: >-
            Metrics timeframe used for volume/txns/unique_traders sort (default:
            24h)
          required: false
          schema:
            $ref: '#/components/schemas/MetricsTimeframe'
        - name: limit
          in: query
          description: 'Results limit per category (default: 10, max: 250)'
          required: false
          schema:
            type: integer
            format: int32
        - name: events_pagination_key
          in: query
          description: >-
            Cursor for the next page of events, obtained from previous
            response's events_pagination.pagination_key
          required: false
          schema:
            type: string
        - name: markets_pagination_key
          in: query
          description: >-
            Cursor for the next page of markets, obtained from previous
            response's markets_pagination.pagination_key
          required: false
          schema:
            type: string
        - name: traders_pagination_key
          in: query
          description: >-
            Cursor for the next page of traders, obtained from previous
            response's traders_pagination.pagination_key
          required: false
          schema:
            type: string
        - name: builders_pagination_key
          in: query
          description: >-
            Cursor for the next page of builders, obtained from previous
            response's builders_pagination.pagination_key
          required: false
          schema:
            type: string
      responses:
        '200':
          description: >-
            Search results. Only requested categories (via `type`) are included
            in the response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Bad request — q is missing or shorter than 2 characters
components:
  schemas:
    SearchSortBy:
      type: string
      description: Combined sort options valid for both events and markets in search
      enum:
        - volume
        - txns
        - unique_traders
        - relevance
        - title
        - creation_date
        - start_date
        - end_date
        - liquidity
        - holders
        - end_time
        - start_time
        - created_time
    SortDirection:
      type: string
      enum:
        - asc
        - desc
    MetricsTimeframe:
      type: string
      enum:
        - 1m
        - 5m
        - 30m
        - 1h
        - 6h
        - 24h
        - 7d
        - 30d
        - lifetime
    SearchResponse:
      type: object
      properties:
        events:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/PolymarketEvent'
        events_pagination:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/PaginationMeta'
        markets:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/MarketResponse'
        markets_pagination:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/PaginationMeta'
        traders:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/TraderWithPnl'
        traders_pagination:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/PaginationMeta'
        builders:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/BuilderMetadata'
        builders_pagination:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/PaginationMeta'
    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
    PaginationMeta:
      type: object
      description: Pagination metadata to include in API responses
      required:
        - has_more
      properties:
        has_more:
          type: boolean
          description: Whether there are more results available
        pagination_key:
          type:
            - string
            - 'null'
          description: Pagination key for the next page (if has_more is true)
    MarketResponse:
      type: object
      description: >-
        Formatted market response with structured metrics, tags, outcomes, and
        event
      properties:
        condition_id:
          type: string
          description: Condition ID.
          default: ''
        id:
          type:
            - string
            - 'null'
          description: ID.
          default: null
        market_slug:
          type:
            - string
            - 'null'
          description: Market slug.
          default: null
        question:
          type:
            - string
            - 'null'
          description: Question.
          default: null
        title:
          type:
            - string
            - 'null'
          description: Title.
          default: null
        description:
          type:
            - string
            - 'null'
          description: Description.
          default: null
        image_url:
          type:
            - string
            - 'null'
          description: Image URL.
          default: null
        oracle:
          type:
            - string
            - 'null'
          description: Oracle.
          default: null
        status:
          type: string
          description: Status.
          default: ''
        created_time:
          type:
            - integer
            - 'null'
          format: int64
          description: Created time timestamp.
          default: null
        start_time:
          type:
            - integer
            - 'null'
          format: int64
          description: Start time timestamp.
          default: null
        game_start_time:
          type:
            - integer
            - 'null'
          format: int64
          description: Game start time timestamp.
          default: null
        closed_time:
          type:
            - integer
            - 'null'
          format: int64
          description: Closed time timestamp.
          default: null
        end_time:
          type:
            - integer
            - 'null'
          format: int64
          description: End time timestamp.
          default: null
        accepting_orders:
          type:
            - boolean
            - 'null'
          description: Accepting orders.
          default: null
        uma_resolution_status:
          type:
            - string
            - 'null'
          description: Uma resolution status.
          default: null
        is_neg_risk:
          type:
            - boolean
            - 'null'
          description: Whether neg risk is true.
          default: null
        market_maker_address:
          type:
            - string
            - 'null'
          description: Market maker address.
          default: null
        creator:
          type:
            - string
            - 'null'
          description: Creator.
          default: null
        category:
          type:
            - string
            - 'null'
          description: Category.
          default: null
        volume_usd:
          type:
            - number
            - 'null'
          format: double
          description: Volume in USD.
          default: null
        liquidity_usd:
          type:
            - number
            - 'null'
          format: double
          description: Liquidity in USD.
          default: null
        highest_probability:
          type:
            - number
            - 'null'
          format: double
          description: Highest probability.
          default: null
        total_holders:
          type:
            - integer
            - 'null'
          format: int64
          description: Total holders.
          default: null
        total_daily_rate:
          type:
            - number
            - 'null'
          format: double
          description: Total daily rate.
          default: null
        winning_outcome:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/MarketOutcome'
              description: Winning outcome.
          default: null
        outcomes:
          type: array
          items:
            $ref: '#/components/schemas/MarketOutcome'
          description: Outcomes.
        clob_rewards:
          type: array
          items:
            $ref: '#/components/schemas/ClobReward'
          description: Clob rewards.
        tags:
          type: array
          items:
            type: string
          description: Tags.
        event_slug:
          type:
            - string
            - 'null'
          description: Event slug.
          default: null
        resolution_source:
          type:
            - string
            - 'null'
          description: Resolution source.
          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'
        relevance_score:
          type:
            - number
            - 'null'
          format: double
          description: Relevance score.
          default: null
    TraderWithPnl:
      allOf:
        - $ref: '#/components/schemas/Trader'
          description: Trader wallet or profile.
        - type: object
          properties:
            pnl:
              description: PnL.
    BuilderMetadata:
      type: object
      description: |-
        One row of `polymarket_builder_metadata`. Includes `builder_code` since
        it's used as the keying field on the standalone metadata endpoints.
      required:
        - builder_code
        - name
      properties:
        builder_code:
          type: string
        name:
          type: string
        website:
          type:
            - string
            - 'null'
        twitter:
          type:
            - string
            - 'null'
        icon_url:
          type:
            - string
            - 'null'
        description:
          type:
            - string
            - '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: ''
        active:
          type:
            - boolean
            - 'null'
          default: null
        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
    MarketOutcome:
      type: object
      description: Outcome for market API responses
      properties:
        name:
          type: string
          description: Name.
          default: ''
        price:
          type:
            - number
            - 'null'
          format: double
          description: Price.
          default: null
        position_id:
          type:
            - string
            - 'null'
          description: Position ID.
          default: null
        outcome_index:
          type:
            - integer
            - 'null'
          format: int32
          description: Outcome index.
          default: null
        latest_block:
          type:
            - integer
            - 'null'
          format: int64
          description: Block of the most recent price update for this outcome.
          default: null
        latest_confirmed_at:
          type:
            - integer
            - 'null'
          format: int64
          description: Unix-seconds timestamp of the most recent price update.
          default: null
    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
    Trader:
      type: object
      description: |-
        Trader profile info embedded in API responses.

        Used in:
        - holders endpoints (market/event holders)
        - trades endpoints
        - leaderboard endpoints
      required:
        - address
      properties:
        address:
          type: string
        name:
          type:
            - string
            - 'null'
        pseudonym:
          type:
            - string
            - 'null'
        profile_image:
          type:
            - string
            - 'null'
        x_username:
          type:
            - string
            - 'null'
        verified_badge:
          type: boolean
    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

````