> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt).

## This page

- **On-site (HTML):** <https://www.socialfetch.dev/platforms/polymarket/markets-conditionid-holders>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/platforms/polymarket/markets-conditionid-holders.mdx>

---

# Polymarket Holders API

The largest holders of each outcome, with optional cost and PnL fields.

`GET /v1/polymarket/markets/{conditionId}/holders` returns `data.outcomes`, one group per outcome token. Each group has `tokenId`, `outcomeIndex` and `holders`, largest first. A holder row carries `trader` (`wallet`, `name`, `pseudonym`, `image`), `verified` and `shares`. With `includePnl=true` it also carries `averagePrice`, `entryCost`, `currentValue`, `realizedPnl`, `unrealizedPnl` and `totalPnl`.

`minBalance` keeps holders with at least that many shares. `limit` is 1 to 1000 and defaults to 20; with `includePnl` the maximum is 100. An unknown condition id, or a market with no holders, returns `lookupStatus: not_found`.

## Request

- **Endpoint:** `GET /v1/polymarket/markets/{conditionId}/holders`
- **Credits:** 1 credit
Failed requests are free
- **Input:** by condition id
- **Full reference:** [docs](https://www.socialfetch.dev/docs/api/v1/polymarket/markets/conditionid/holders/get)
- **Platform page:** [/platforms/polymarket](https://www.socialfetch.dev/platforms/polymarket)

## FAQ

### Why is the limit lower with includePnl?

Polymarket allows at most 100 holders a page when profit fields are included. The route rejects a larger limit with that combination, so lower the limit or drop includePnl.

### Are holders grouped by outcome?

Yes. data.outcomes has one entry per outcome token, and each entry has its own holders list. A binary market usually has two groups, one for Yes and one for No.

### What do the PnL fields mean?

entryCost is dollars paid in, currentValue is the position's value now, and totalPnl is realized plus unrealized profit. averagePrice is the average entry price. These fields are null or absent without includePnl.

### What does lookupStatus mean on this route?

found means the object or list was returned. not_found means no matching object exists. HTTP 200 only means the request finished, so branch on data.lookupStatus before storing a row.

### How much does this route cost?

Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged: that field is the billing source of truth.