> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codex.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Predictions Overview
> How prediction events, markets, outcomes, and traders fit together, and which query to reach for
The prediction endpoints are organized around four things: **events**, **markets**, **traders**, and the **trades** that connect them. Knowing which one you're asking about tells you which query you want.
**Prediction Market data is currently in beta**. It is actively being worked on and improved, but may be unreliable. Polymarket and Kalshi data are live.
At least for the time being, these endpoints require a Growth or Enterprise plan. [Learn more](https://dashboard.codex.io/dashboard/billing?utm_source=codex\&utm_medium=docs\&utm_campaign=billing).
## The data model
An **event** is a real-world topic. It holds one or more **markets**, each a single yes/no or multi-way question. Every market resolves through its **outcomes**, and each outcome has a price that reads as an implied probability. **Traders** take positions in those outcomes, and every position change is a **trade**.
```
Event "2026 World Cup"
└─ Market "Will Brazil win?"
├─ Outcome "Yes" ($0.34 → 34% implied)
└─ Outcome "No" ($0.66 → 66% implied)
└─ Trades who bought or sold, when, and at what price
```
The practical consequence: event-level data aggregates across every market underneath it. If you want the headline number for "2026 World Cup" you query the event. If you want the odds on a specific team, you query the market.
## Pick your endpoint
Each group in the sidebar maps to one layer of that model.
### Events
| The data you need | Find it with this |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Discover events by topic, protocol, status, or trending score | [`filterPredictionEvents`](/api-reference/queries/filterpredictionevents) |
| Volume, liquidity, and trader counts for one event, windowed and all-time | [`detailedPredictionEventStats`](/api-reference/queries/detailedpredictioneventstats) |
| Event-level price history for charting | [`predictionEventBars`](/api-reference/queries/predictioneventbars) |
| One chart series per leading market inside an event, for a comparison view | [`predictionEventTopMarketsBars`](/api-reference/queries/predictioneventtopmarketsbars) |
| The category and subcategory vocabulary used to browse and filter events | [`predictionCategories`](/api-reference/queries/predictioncategories) |
### Markets
| The data you need | Find it with this |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Discover markets across every event by volume, liquidity, or ranking | [`filterPredictionMarkets`](/api-reference/queries/filterpredictionmarkets) |
| Markets within a single event, with entrant, segment, and ladder metadata already parsed | [`eventScopedFilterPredictionMarkets`](/api-reference/queries/eventscopedfilterpredictionmarkets) |
| Full records for markets you already have IDs for | [`predictionMarkets`](/api-reference/queries/predictionmarkets) |
| Windowed and all-time stats for one market | [`detailedPredictionMarketStats`](/api-reference/queries/detailedpredictionmarketstats) |
| OHLC price history for a market | [`predictionMarketBars`](/api-reference/queries/predictionmarketbars) |
| Latest price, or price at a specific timestamp | [`predictionMarketPrice`](/api-reference/queries/predictionmarketprice) |
| Who holds the outcome tokens for a market, and how much | [`predictionTokenHolders`](/api-reference/queries/predictiontokenholders) |
Reach for `eventScopedFilterPredictionMarkets` instead of `filterPredictionMarkets` when you're rendering a single event page. It returns structured classification metadata (country codes, period and stat grouping, parsed numeric and date rungs) so you don't have to parse market labels client-side.
### Traders
| The data you need | Find it with this |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Leaderboards: rank traders by volume, realized PnL, trade count, or biggest win | [`filterPredictionTraders`](/api-reference/queries/filterpredictiontraders) |
| Full records for traders you already have IDs for | [`predictionTraders`](/api-reference/queries/predictiontraders) |
| Aggregate performance for one trader | [`detailedPredictionTraderStats`](/api-reference/queries/detailedpredictiontraderstats) |
| How one trader has performed market by market | [`predictionTraderMarketsStats`](/api-reference/queries/predictiontradermarketsstats) |
| Trader-market records filtered across traders, markets, and events at once | [`filterPredictionTraderMarkets`](/api-reference/queries/filterpredictiontradermarkets) |
| Everything a trader currently holds | [`predictionTraderHoldings`](/api-reference/queries/predictiontraderholdings) |
| A trader's performance over time, for charting | [`predictionTraderBars`](/api-reference/queries/predictiontraderbars) |
### Trades and order books
| The data you need | Find it with this |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Trade history, filterable by market, event, or trader, with cursor pagination | [`predictionTrades`](/api-reference/queries/predictiontrades) |
| Live bids and asks for a set of outcomes, pulled from the venue's CLOB | [`predictionOutcomeOrderBooks`](/api-reference/queries/predictionoutcomeorderbooks) |
## Staying live
Five subscriptions mirror the queries above for real-time updates: [`onPredictionTradesCreated`](/api-reference/subscriptions/onpredictiontradescreated), [`onDetailedPredictionMarketStatsUpdated`](/api-reference/subscriptions/ondetailedpredictionmarketstatsupdated), [`onDetailedPredictionEventStatsUpdated`](/api-reference/subscriptions/ondetailedpredictioneventstatsupdated), [`onPredictionMarketBarsUpdated`](/api-reference/subscriptions/onpredictionmarketbarsupdated), and [`onPredictionEventBarsUpdated`](/api-reference/subscriptions/onpredictioneventbarsupdated).
## Venue coverage
| Platform | Protocol filter | Status |
| -------------------------------------------- | --------------- | ------ |
| [Polymarket](/prediction-markets/polymarket) | `POLYMARKET` | Live |
| [Kalshi](/prediction-markets/kalshi) | `KALSHI` | Live |
Coverage is not identical across venues. Kalshi runs as a CFTC-regulated exchange and does not expose individual trader identity, so trader data is unavailable for Kalshi entirely: the Traders queries above cannot be used with it, `traderId` filtering is unavailable, and Kalshi trades carry no maker and no buy/sell direction (every trade returns as `TRADE`). Event, market, and trade data work the same on both venues. `predictionOutcomeOrderBooks` covers Polymarket and Kalshi, and returns `null` for outcomes from anywhere else.
See [Supported Prediction Markets](/prediction-markets/index) for the full platform breakdown.
## Recipes
Browse categories, trending events, and filter markets.
Build a complete event detail page with real-time data.
Outcome probability charts, multi-market comparisons, and OHLC data.
Trader leaderboards, profiles, and performance analytics.