> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xinsider.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The Markdown of an API reference page leaves out the OpenAPI schema.
> Every object an endpoint returns or a webhook carries, with each field's type, presence and meaning, is on https://docs.0xinsider.com/api-reference/objects.md.
> The full OpenAPI 3.1 spec names each operation's and each webhook's exact parameters, request body and response schema: https://docs.0xinsider.com/api-reference/openapi.json.

# Game holders

> Get the S, A, and B wallets holding up to 25 markets of one game, in the order you request them.

Use this endpoint to read the graded holders of several markets of one game in one request, for example every spread and total line. Take the `condition_id` values from [List game markets](https://docs.0xinsider.com/api-reference/endpoint/list-game-markets.md), and check each result's `status`, because individual markets can fail.

Each `ok` result is what [Market holders](https://docs.0xinsider.com/api-reference/endpoint/get-market-holders.md) returns for that market with no `outcome` or `min_grade` filter, cut to `limit`. To read the next page of one market, or to filter by side or grade, call Market holders with its `condition_id`.

## Parameters

| Parameter | Description |
| - | - |
| `event_slug` | Required. The game's event slug, for example `nba-bos-orl-2026-11-01`. Matching is case-insensitive. |
| `condition_ids` | Required. 1 to 25 market ids, comma-separated or repeated: Polymarket's `condition_id` or the `mkt_` form. Duplicates are allowed, and each one gets its own result row. |
| `limit` | Optional. How many holders to return per market, from 1 to 100. The default is 20, and a value outside the range is clamped. |

An empty list or more than 25 ids fails the whole request with `400` before any market is read. A slug with no stored market is a `404`, as on List game markets.

## Key response fields

| Field | Meaning |
| - | - |
| `data[].index` | Where this market sat in `condition_ids`, counting from 0. |
| `data[].input` | The id exactly as you sent it. |
| `data[].status` | `ok`, with `data`, or `error`, with `error.code`, `error.message`, and `error.param`. |
| `data[].data` | The market's holders: `data` (the holder rows), `has_more`, `total`, `market`, `scan`, `totals`, `category_records_as_of`, `computed_at`, `cached`, and `stale`. Each field but `stale` means what it means on [Market holders](https://docs.0xinsider.com/api-reference/endpoint/get-market-holders.md). |
| `data[].data.market.protocol_version` | The Polymarket protocol the market trades on: `v1` (CTF) or `v2` (Protocol V2), as on [`GET /api/v1/market/{condition_id}/holders`](https://docs.0xinsider.com/api-reference/endpoint/get-market-holders). |
| `data[].data.stale` | `true` when the market's fresh holder list was not ready in time and this is the last list computed for it, up to 15 minutes old. Read `computed_at` for its age. `false` on a fresh list. |
| `data[].error.code` | `not_found` when the market is not one of this game's markets, `bad_request` when an id is malformed, `rate_limit_unavailable` with `error.reason` `read_model_warming` when the market has no holder list from the past 15 minutes and its scan did not finish in time, and `rate_limited` with `error.reason` `cold_read_limited` when the market needed a fresh Polymarket scan over your account's share and has no recent list. Branch on `error.reason`: the `code` of `read_model_warming` is kept for compatibility. The HTTP response remains `200` in each case. |
| `meta.request_cost` | The batch item units charged: 1 for every id you sent, duplicates and bad ids included. |
| `meta.rate_limit` | Your remaining batch item budget: `basis`, `limit`, `remaining`, and `reset`. |

## Markets that are not ready

A market whose holder list is not cached needs a Polymarket scan, and the request waits for it only briefly. When the scan is still running, the market comes back with the last holder list computed for it in the past 15 minutes, marked `stale: true`. The scan keeps running, so the same request a few seconds later returns the fresh list.

A market with no list from the past 15 minutes comes back as a `read_model_warming` error with a retry time instead. A market over your account's scan share is served its last list the same way, and is a `cold_read_limited` error only without one. Uncached markets count against the same scan share as [Market holders](https://docs.0xinsider.com/api-reference/endpoint/get-market-holders.md#uncached-markets).

## Item budget

This route spends from the batch item budget that the batch routes share: 2,500 units a minute per account on Pro, or 10,000 on Max, alongside the request allowance. Going over returns `429` with a `Retry-After` before any market is read.

## Example

```bash theme={null}
curl -sS \
  -H "Authorization: Bearer $OXINSIDER_API_KEY" \
  'https://api.0xinsider.com/api/v1/games/nba-bos-orl-2026-11-01/holders?condition_ids=0x123...,0x456...&limit=10'
```

The `get_game_holders` MCP tool and the SDK's `getGameHolders` method call this endpoint.

## What it does not return

* Holders of a market from another game. Its row is `not_found`.
* An `ETag`. This route has no conditional read.
* More than `limit` holders per market. Page past it with Market holders.


## API Specification

The full API specification for this endpoint is available in the [documentation index](https://docs.0xinsider.com/llms.txt).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.