GET
/v2/biggest-winnersList the biggest wins
The biggest single winning positions. One row per winning POSITION, not per user: `pnl` is `final_value - initial_value` for that position, and the window (`?time_period=`, default `day`) is on when it resolved. `?category=` narrows to a market category. Deeper pages come only from `?cursor=`, which **pins the window and category it was minted on**; restating a different one is a `400`, not a silent re-point.
- 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 |
|---|---|---|---|---|
| time_period | query | stringnull | no | Window on `resolved_at`: `day` | `week` | `month` | `all`. Defaults to `day`. |
| category | query | stringnull | no | `overall` (default), a Gamma market category (e.g. `sports`), or a synthetic category: `combos` (combinatorial wins get their own full top-500 per window) or `esports` (promoted subcategory). |
| limit | query | integernull | no | First-page size. Ignored when `cursor` is supplied. |
| cursor | query | stringnull | no | Opaque pagination cursor from a prior response's `next_cursor`. |
Example
curl -X GET "https://data-api.polymarket.com/v2/biggest-winners"Returns a list of objects with these fields
| Field | Type | Description |
|---|---|---|
| condition_id | string | On-chain condition id of the market (combo rows: the combo condition). |
| event_id | integer | Gamma event id of the parent event; `0` on combo rows. |
| event_slug | string | Parent event slug; empty on combo rows. |
| event_title | string | Parent event title; on combo rows, the `' / '`-joined leg questions. |
| final_value | number | Value at resolution, in USDC. |
| initial_value | number | Cost basis of the winning position, in USDC. |
| kind | string | `market` or `combo`; combo rows carry no Gamma event (`event_id` 0, empty `event_slug`), so branch on this before building event links. |
| pnl | number | `final_value - initial_value`, in USDC. |
| position_id | string | Token id of the winning position. |
| profile_image | string | Profile image URL. |
| resolved_at | integer | Unix seconds; when the position resolved. |
| user_id | string | The winning wallet. |
| user_name | string | Profile display name of the wallet. |
| win_rank | integer | Unique 1-based ordinal within the window/category; `row_number()`, so equal PnL does not share a rank (unlike the leaderboard's `rank`). |
Responses
| Status | Meaning |
|---|---|
| 200 | A page of the biggest winning positions |
| 400 | Invalid time_period or cursor, or a param that contradicts the cursor pin |
| 429 | Too many requests; 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` |
From Polymarket's published OpenAPI spec and rate-limit tables, synced 2026-10-04.