STAT-API

Polymarket GraphQL Reference

Polymarket's on-chain prediction markets — events and the YES/NO outcome tokens that trade against them, with token-level snapshots, OHLC candles, price history, order books, and the full public trade tape.

Every GraphQL type, relation, and argument — generated from the served schema, so it can never disagree with the API. Root fields take the same filters as REST; requests are metered by rows resolved, nested lists included.

Main

eventsPolymarketEvents
A real-world event that anchors a set of Polymarket markets — a single sports game, an election, a futures question, or any other resolvable scenario. E.g., "Mavericks vs Suns" game event or "2026 NBA Champion" futures event.
REST endpoint →Field dictionary (22 fields) →Open in playground →
Required filters: one of league_code.
Relations
  • markets[PolymarketMarkets!]!polymarket.markets rows whose event_id references this row.
  • tokens[PolymarketTokens!]!polymarket.tokens rows whose event_id references this row.
  • competitionCompetitionThe sporting event this row prices, resolved through the cross-sport competition registry via (league_code, competition_id); null when the row is not linked to a game or tournament.
Arguments (6)
  • firstIntPage size; clamped to the table's REST default/max limits.
  • afterBigIntKeyset cursor — returns rows with id > after, ordered by id ascending.
  • league_codeStringFilter to events for a single league/sport slug (e.g., "nba", "nfl", "soccer").
  • competition_idIntFilter to events linked to a specific competition (cross-schema game; resolved from slug).
  • statusStringFilter by event status — "active" or "closed".
  • game_dateStringFilter to events scheduled on a specific date (YYYY-MM-DD).
Columns (19) — full docs in the data dictionary
id: BigInt
condition_id: String
slug: String
title: String
description: String
start_date: String
end_date: String
status: String
neg_risk: Boolean
competition_id: BigInt
game_date: String
home_team: String
away_team: String
league_code: String
volume: BigInt
liquidity: BigInt
market_count: Int
created_at: String
updated_at: String
tokensPolymarketTokens
The tradable outcome tokens within a Polymarket market — YES and NO for binary markets, or one token per outcome for multi-outcome markets (e.g., each team in a championship futures market). The clobTokenId is used to query CLOB API for pricing and trades.
REST endpoint →Field dictionary (13 fields) →Open in playground →
Required filters: one of market_id.
Relations
  • marketPolymarketMarketsThe polymarket.markets row referenced by market_id; null when unlinked.
  • eventPolymarketEventsThe polymarket.events row referenced by event_id; null when unlinked.
Arguments (4)
  • firstIntPage size; clamped to the table's REST default/max limits.
  • afterBigIntKeyset cursor — returns rows with id > after, ordered by id ascending.
  • market_idIntFilter to outcome tokens for a single Polymarket market.
  • event_idIntFilter to tokens linked to a single event (denormalized for direct event queries).
Columns (11) — full docs in the data dictionary
id: BigInt
token_id: String
market_id: BigInt
event_id: BigInt
outcome: String
outcome_index: Int
price_bps: Int
winner: Boolean
created_at: String
updated_at: String
final_price_bps: Int
marketsPolymarketMarkets
An individual prediction market on Polymarket — a specific question tied to an event, resolved on-chain, with one or more tradable outcome tokens. Each market has 2+ tokens representing outcome positions.
REST endpoint →Field dictionary (29 fields) →Open in playground →
Required filters: one of event_id | competition_id.
Relations
  • eventPolymarketEventsThe polymarket.events row referenced by event_id; null when unlinked.
  • tokens[PolymarketTokens!]!polymarket.tokens rows whose market_id references this row.
  • candles[PolymarketCandles!]!polymarket.candles rows whose market_id references this row.
  • price_histories[PolymarketPriceHistories!]!polymarket.price_histories rows whose market_id references this row.
  • public_trades[PolymarketPublicTrades!]!polymarket.public_trades rows whose market_id references this row.
  • order_book_snapshots[PolymarketOrderBookSnapshots!]!polymarket.order_book_snapshots rows whose market_id references this row.
  • market_snapshots[PolymarketMarketSnapshots!]!polymarket.market_snapshots rows whose market_id references this row.
Arguments (6)
  • firstIntPage size; clamped to the table's REST default/max limits.
  • afterBigIntKeyset cursor — returns rows with id > after, ordered by id ascending.
  • event_idIntFilter to all markets that belong to a single Polymarket event.
  • competition_idIntFilter to markets linked to a specific competition (denormalized from event).
  • statusStringFilter by market status — "active" or "closed" ("resolved" appears only on 22 legacy rows that carry no resolution data; resolution fields live on closed rows).
  • activeBooleanFilter by active status (defaults to true to show only currently-active rows; pass active=false to include inactive).
Columns (22) — full docs in the data dictionary
id: BigInt
condition_id: String
event_id: BigInt
question: String
slug: String
competition_id: BigInt
neg_risk: Boolean
status: String
result: String
outcome_count: Int
active: Boolean
closed: Boolean
volume: BigInt
liquidity: BigInt
best_bid_bps: Int
best_ask_bps: Int
last_trade_price_bps: Int
created_at: String
updated_at: String
resolved_at: String
resolution_source: String
payout_token_id: String

Markets

candlesPolymarketCandles
OHLC candlestick price summaries for Polymarket outcome tokens — the open, high, low, close, and volume over standard time bins (1 minute, 5 minute, 1 hour, 1 day). Bucketed by (token_id, period_interval, end_period_ts).
REST endpoint →Field dictionary (14 fields) →Open in playground →
Required filters: one of market_id.
Relations
  • marketPolymarketMarketsThe polymarket.markets row referenced by market_id; null when unlinked.
Arguments (5)
  • firstIntPage size; clamped to the table's REST default/max limits.
  • afterBigIntKeyset cursor — returns rows with id > after, ordered by id ascending.
  • market_idIntFilter to candles for all tokens in a single Polymarket market.
  • token_idStringFilter to candles for a single outcome token (clobTokenId).
  • period_intervalIntBin width in seconds. Currently every row is period_interval=1 (event-driven captures, irregular spacing) — resample client-side for fixed OHLC bins.
Columns (13) — full docs in the data dictionary
id: BigInt
token_id: String
market_id: BigInt
period_interval: Int
end_period_ts: Int
open_bps: Int
high_bps: Int
low_bps: Int
close_bps: Int
volume: Int
size: BigInt
created_at: String
updated_at: String
market_snapshotsPolymarketMarketSnapshots
Market-level snapshots on Polymarket — aggregate volume, open interest, last trade price, and resolution status captured over time as the market trades. Tracks bid/ask/last and volume/liquidity over time. Coverage begins 2026-04; cadence is roughly hourly.
REST endpoint →Field dictionary (12 fields) →Open in playground →
Required filters: one of market_id.
Relations
  • marketPolymarketMarketsThe polymarket.markets row referenced by market_id; null when unlinked.
Arguments (3)
  • firstIntPage size; clamped to the table's REST default/max limits.
  • afterBigIntKeyset cursor — returns rows with id > after, ordered by id ascending.
  • market_idIntFilter to snapshots for a single Polymarket market.
Columns (11) — full docs in the data dictionary
id: BigInt
market_id: BigInt
condition_id: String
best_bid_bps: Int
best_ask_bps: Int
last_trade_price_bps: Int
volume: BigInt
liquidity: BigInt
captured_at: String
created_at: String
updated_at: String
order_book_snapshotsPolymarketOrderBookSnapshots
Order-book depth snapshots for Polymarket outcome tokens — the bid and ask ladders captured at a point in time, showing the resting liquidity at each price level. Top 10 levels per side per token at capture time. Coverage begins 2026-04; pregame cadence (captures generally stop shortly after tip-off).
REST endpoint →Field dictionary (13 fields) →Open in playground →
Required filters: one of market_id.
Relations
  • marketPolymarketMarketsThe polymarket.markets row referenced by market_id; null when unlinked.
Arguments (4)
  • firstIntPage size; clamped to the table's REST default/max limits.
  • afterBigIntKeyset cursor — returns rows with id > after, ordered by id ascending.
  • market_idIntFilter to order-book snapshots for all tokens in a single Polymarket market.
  • token_idStringFilter to order-book snapshots for a single outcome token (clobTokenId).
Columns (12) — full docs in the data dictionary
id: BigInt
token_id: String
market_id: BigInt
side: String
price_bps: Int
size: BigInt
depth_rank: Int
spread_bps: Int
midpoint_bps: Int
captured_at: String
created_at: String
updated_at: String
price_historiesPolymarketPriceHistories
Historical price tracks for each Polymarket outcome token — the full time-series of trading prices since the market opened. Analogous to kalshi.candle.
REST endpoint →Field dictionary (13 fields) →Open in playground →
Required filters: one of token_id.
Relations
  • marketPolymarketMarketsThe polymarket.markets row referenced by market_id; null when unlinked.
Arguments (5)
  • firstIntPage size; clamped to the table's REST default/max limits.
  • afterBigIntKeyset cursor — returns rows with id > after, ordered by id ascending.
  • token_idStringFilter to price history for a single Polymarket outcome token (clobTokenId).
  • market_idIntFilter to price history for all tokens in a single market.
  • interval_secondsIntUpstream fetch-window label (currently always 86400) — NOT a bin width; points within a window are irregularly spaced. Resample client-side.
Columns (12) — full docs in the data dictionary
id: BigInt
token_id: String
market_id: BigInt
interval_seconds: Int
period_start: String
open_bps: Int
high_bps: Int
low_bps: Int
close_bps: Int
volume: BigInt
created_at: String
updated_at: String
public_tradesPolymarketPublicTrades
Every executed trade on Polymarket — price, size, side (buy or sell of each token), and timestamp, comprising the public market tape. Represents completed market trades.
REST endpoint →Field dictionary (13 fields) →Open in playground →
Required filters: one of market_id.
Relations
  • marketPolymarketMarketsThe polymarket.markets row referenced by market_id; null when unlinked.
Arguments (4)
  • firstIntPage size; clamped to the table's REST default/max limits.
  • afterBigIntKeyset cursor — returns rows with id > after, ordered by id ascending.
  • market_idIntFilter to trades on a single Polymarket market.
  • token_idStringFilter to trades for a single outcome token (clobTokenId).
Columns (12) — full docs in the data dictionary
id: BigInt
trade_id: String
token_id: String
market_id: BigInt
side: String
price_bps: Int
size: BigInt
traded_at: String
created_at: String
updated_at: String
maker_address: String
taker_address: String
token_snapshotsPolymarketTokenSnapshots
Token-level snapshots on Polymarket — the bid, ask, and last trade price for each outcome token captured over time as the market trades. Critical for multi-outcome markets where each token moves independently. Coverage begins 2026-04; cadence is roughly 1-2 hours.
REST endpoint →Field dictionary (7 fields) →Open in playground →
Required filters: one of token_id.
Arguments (4)
  • firstIntPage size; clamped to the table's REST default/max limits.
  • afterBigIntKeyset cursor — returns rows with id > after, ordered by id ascending.
  • token_idStringFilter to snapshots for a single Polymarket outcome token (clobTokenId).
  • market_idIntFilter to snapshots for all tokens in a single market (denormalized for market-level queries).
Columns (7) — full docs in the data dictionary
id: BigInt
token_id: String
market_id: BigInt
price_bps: Int
captured_at: String
created_at: String
updated_at: String