GET
/v2/holdersList a market's top holders
Top holders of a market, netted per user and grouped by outcome token. `?condition=` (CSV of `condition_id`) is required (400 otherwise). `?limit=` (default 100, max 1000; v2 family-uniform) sizes the page **per outcome token**; `?min_balance=` filters the served amount.
- Base URL
- https://data-api.polymarket.com
- Auth
- Public, no key
- Rate limit
- 800 req / 10s (80 per second)
- Limit applies to
- General (all /v2 endpoints)
Things to know
Every v2 response wraps its payload in a data field. Paginated reads return an opaque cursor in pagination and do not accept offset. Under load the API answers 429 with a Retry-After header.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| condition | query | stringnull | yes | Comma-separated `condition_id`s (at most 20 distinct values; exactly one with `include_pnl=true`). Required. `condition` is the unified key across v2 (same as the feeds and `/v2/oi`); `condition_id` / `conditionId` are accepted aliases. |
| limit | query | integernull | no | Rows per outcome token; defaults to 100, maximum 1000 (100 with `include_pnl=true`). |
| cursor | query | stringnull | no | Opaque pagination cursor from a prior response's `next_cursor`; carries the per-token `(limit, offset)` window and overrides `limit`. Paging past the first page is cursor-only. |
| min_balance | query | numbernull | no | Minimum net balance in shares (default 0), applied post-netting. With `include_pnl=true` it applies to the served per-side gross amount instead. |
| include_pnl | query | booleannull | no | Opt into per-holder position economics (default `false`; `includePnl` is an accepted alias). Adds `avg_price`, `entry_cost_usdc`, `current_price`, `current_value`, `realized_pnl`, `unrealized_pnl` and `total_pnl` to every holder row, and switches the served amounts to per-side gross balances: a… |
condition is listed as optional in Polymarket's OpenAPI spec, but the API returns 400 without it (checked 2026-10-04).
Example
curl -X GET "https://data-api.polymarket.com/v2/holders?condition=<condition>"Returns a list of objects with these fields
| Field | Type | Description |
|---|---|---|
| holders | object[] | Top holders of that token, amount descending (net by default, per-side gross with `include_pnl=true`). |
| token_id | string | The outcome token this group ranks. |
Responses
| Status | Meaning |
|---|---|
| 200 | A page of top holders per outcome token |
| 400 | Missing 'condition', invalid params, or invalid cursor, or a malformed 'condition' id; with 'include_pnl', also more than one 'condition' or a limit above 100 (including a cursor that carries a wider… |
| 429 | Service is at heavy-query capacity; retry after `Retry-After` |
| 500 | Internal server error |
| 503 | Timed out (the request deadline, the datastore statement timeout, or the connection pool's acquire budget) or a serving dependency is unavailable; retry after `Retry-After` |
Related endpoints
- GET /holders Data API v1
From Polymarket's published OpenAPI spec and rate-limit tables, synced 2026-10-04.