> ## 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 market holders > Retrieve holders of a market grouped by outcome, sorted by shares held. Identify the market with either `condition_id` or `market_slug` — exactly one must be provided. Set `include_pnl=true` to include a per-holder `pnl` object. Uses cursor-based pagination. ## OpenAPI ````yaml https://api.struct.to/openapi.json get /polymarket/holders/markets 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/holders/markets: get: tags: - Holders summary: Get market holders description: >- Retrieve holders of a market grouped by outcome, sorted by shares held. Identify the market with either `condition_id` or `market_slug` — exactly one must be provided. Set `include_pnl=true` to include a per-holder `pnl` object. Uses cursor-based pagination. operationId: get_market_holders parameters: - name: condition_id in: query description: Market condition ID (0x-prefixed hex) required: false schema: type: string - name: market_slug in: query description: Market slug required: false schema: type: string - name: limit in: query description: 'Results limit per outcome (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: min_shares in: query description: Minimum shares held (decimal string) required: false schema: type: string - name: max_shares in: query description: Maximum shares held (decimal string) required: false schema: type: string - name: include_pnl in: query description: 'Include nested holder PnL data (default: false)' required: false schema: type: boolean responses: '200': description: Market holders grouped by outcome (sorted by shares DESC). content: application/json: schema: $ref: '#/components/schemas/MarketHoldersResponse' '404': description: Market not found components: schemas: MarketHoldersResponse: type: object description: Response for market (condition_id) holders endpoint. required: - condition_id - total_holders - outcomes properties: condition_id: type: string description: Market condition ID. question: type: - string - 'null' description: Market question / title. slug: type: - string - 'null' description: Market slug. total_holders: type: integer format: int64 description: Total unique holders across all outcomes of this market. outcomes: type: array items: $ref: '#/components/schemas/OutcomeHolders' description: Holders grouped by outcome. OutcomeHolders: type: object description: Holders grouped by outcome. required: - outcome_index - outcome_name - position_id - total_holders - holders properties: outcome_index: type: integer format: int32 description: Outcome index (0, 1, etc.). outcome_name: type: string description: Outcome name (Yes, No, etc.). position_id: type: string description: Position ID for this outcome. price: type: - number - 'null' format: double description: Current price / probability. total_holders: type: integer format: int64 description: Total holders for this outcome. holders: type: array items: $ref: '#/components/schemas/MarketHolder' description: Top holders for this outcome. MarketHolder: type: object description: Market outcome holder. required: - trader - shares properties: trader: $ref: '#/components/schemas/Trader' description: Trader profile. shares: type: string description: Position shares held (raw balance as decimal string for precision). shares_usd: type: - string - 'null' description: USD value of shares (shares × latest price). usd_balance: type: - string - 'null' description: USD balance of the holder's wallet. pnl: oneOf: - type: 'null' - $ref: '#/components/schemas/MarketHolderPnl' description: Market-level PnL for this holder. 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 MarketHolderPnl: type: object description: Market-level PnL for a holder, included when `include_pnl=true`. required: - realized_pnl_usd - total_pnl_usd - unrealized_pnl_usd - total_volume_usd - buy_volume_usd - sell_volume_usd - redemption_volume_usd - merge_volume_usd - convert_collateral_usd - total_fees - total_buys - total_sells - total_splits - total_shares_bought - total_shares_sold - buy_count - sell_count - redeem_count - merge_count - split_count - split_volume_usd - converted_count - converted_shares_gained - converted_shares_lost - outcomes_traded - resolved properties: realized_pnl_usd: type: number format: double description: Realized PnL in USD. total_pnl_usd: type: number format: double description: Total PnL in USD. unrealized_pnl_usd: type: number format: double description: Unrealized PnL in USD. realized_pnl_pct: type: - number - 'null' format: double description: Realized PnL percent. total_pnl_pct: type: - number - 'null' format: double description: Total PnL percent. total_volume_usd: type: number format: double description: Total volume in USD. buy_volume_usd: type: number format: double description: Buy volume in USD. sell_volume_usd: type: number format: double description: Sell volume in USD. redemption_volume_usd: type: number format: double description: Redemption volume in USD. merge_volume_usd: type: number format: double description: Merge volume in USD. convert_collateral_usd: type: number format: double description: Convert collateral in USD. total_fees: type: number format: double description: Total fees. total_buys: type: integer format: int64 description: Total buys. minimum: 0 total_sells: type: integer format: int64 description: Total sells. minimum: 0 total_splits: type: integer format: int64 description: Total splits. minimum: 0 total_shares_bought: type: number format: double description: Total shares bought. total_shares_sold: type: number format: double description: Total shares sold. buy_count: type: integer format: int64 description: Buy count. minimum: 0 sell_count: type: integer format: int64 description: Sell count. minimum: 0 redeem_count: type: integer format: int64 description: Redeem count. minimum: 0 merge_count: type: integer format: int64 description: Merge count. minimum: 0 split_count: type: integer format: int64 description: Split count. minimum: 0 split_volume_usd: type: number format: double description: Split volume in USD. converted_count: type: integer format: int64 description: Converted count. minimum: 0 converted_shares_gained: type: number format: double description: Converted shares gained. converted_shares_lost: type: number format: double description: Converted shares lost. outcomes_traded: type: integer format: int64 description: Outcomes traded. minimum: 0 resolved: type: boolean description: Resolved. won: type: - boolean - 'null' description: Won. first_trade_at: type: - integer - 'null' format: int64 description: First trade at timestamp. last_trade_at: type: - integer - 'null' format: int64 description: Last trade at timestamp. ````