Skip to main content
GET
cURL
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, and check each result’s status, because individual markets can fail. Each ok result is what Market holders 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

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

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.

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

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.

Authorizations

Authorization
string
header
required

Legacy default or named integration API key, or OAuth 2.1 access token, in the Authorization header as Bearer oxi_sk_live_... or Bearer oxi_at_.... Default keys retain full access; integration keys are limited to their approved read, webhooks, export and usage scopes and expire within 90 days. All credentials share the owner's account limits. Data calls require an active Pro subscription and return live data. A 401 carries WWW-Authenticate: Bearer resource_metadata="https://api.0xinsider.com/.well-known/oauth-protected-resource" (RFC 6750 section 3, RFC 9728).

Scopes

read

Read markets, traders, large trades, positions, reports, search, the event stream and every MCP tool

Headers

X-Query-Validation
enum<string>

Opt into strict query-name validation. The default is compatible: unknown names are ignored and reported in X-Query-Ignored. With strict, an unknown name returns 400 bad_request with error.reason unknown_query_parameter before the handler runs, including when its percent escape is incomplete.

Available options:
strict

Path Parameters

event_slug
string
required

The game's event slug from GET /api/v1/games, for example nba-bos-orl-2026-11-01. Matched case-insensitively.

Query Parameters

condition_ids
string[]
required

1 to 25 condition_id values of this game's markets, comma-separated. The key may also repeat (condition_ids=a&condition_ids=b). A raw provider condition_id or the mkt_-prefixed market id.

Required array length: 1 - 25 elements
limit
integer
default:20

Holders per market. Out-of-range values are clamped to 1..100.

Required range: 1 <= x <= 100
as_of
enum<string>

kickoff: each market's roster as it stood at the game's kickoff, as GET /api/v1/market/{condition_id}/holders?as_of=kickoff serves it (#34064), read for every market in one query with no wait, no walk and no cold-read share. Each ok item carries as_of and data_quality, computed_at is its capture, cached is true and stale is false. A market until 30 s after kickoff is an item error with reason kickoff_roster_pending and retry_at at that instant; a market with no stored kickoff roster is an item error with reason kickoff_roster_not_captured. Omit it for the current rosters; any other value is 400 bad_request with param=as_of.

Available options:
kickoff

Response

Ordered batch results, one per requested condition_id

object
string
required
Allowed value: "game_holders_batch"
data
object[]
required
meta
object
required