Prediction Markets Events API

Retrieve Octagon's analyzed prediction market events over REST. The Events API exposes three endpoints:

• List events — the latest snapshot of every analyzed event, including model/market probabilities, confidence scores, analysis summaries, and per-market outcome breakdowns.
• Get an event — one event as of one analysis run, with each market's quote and status from that run.
• Event history — the historical snapshots for a single event by ticker, for time-series analysis and backtesting.

Like the Chat Completions and Responses endpoints, these are direct REST endpoints called relative to the Octagon API base URL:

Base URL

https://api.octagonai.co/v1

List Events

GET /predictions/events

Returns the latest snapshot of every analyzed prediction market event tracked by Octagon, ordered by most recently captured first.

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Number of records to return. Default 10; minimum 1; maximum 200.
cursor	string	No	Cursor for pagination. Use the cursor returned from a previous response to continue.
has_history	boolean	No	When true, only return events that have multiple historical snapshots available for time-series use.
include	string	No	Comma-separated list of optional per-row field groups. Supported: eligibility (see below).

Response Fields

Each event in the data array includes:

Field	Type	Description
history_id	integer	Unique identifier for this snapshot.
run_id	string (UUID)	The export run that produced this snapshot.
captured_at	string (ISO 8601)	When this snapshot was captured.
event_ticker	string	Ticker identifier for the event.
name	string	Human-readable event name.
slug	string	URL-friendly slug.
image_url	string	Event image URL.
series_category	string	Category (e.g., "Politics", "Crypto", "Economics").
available_on_brokers	boolean	Whether the event is available on supported brokers.
mutually_exclusive	boolean	Whether the event's outcomes are mutually exclusive.
analysis_last_updated	string (ISO 8601)	When the analysis was last refreshed.
confidence_score	float	Octagon's confidence in the model output (0–10 scale).
model_probability	float	Octagon model probability for the event's primary/most-liquid market (0–100 percentage scale). See outcome_probabilities for the full per-market breakdown.
market_probability	float	Market-implied probability for the event's primary/most-liquid market (0–100 percentage scale). See outcome_probabilities for the full per-market breakdown.
edge_pp	float	Model edge in percentage points (model_probability - market_probability). See Interpreting the model probability.
expected_return	float	Expected return if the model is correct.
r_score	float	Risk-adjusted score.
total_volume	float	Total trading volume.
total_open_interest	float	Total open interest.
close_time	string	When the event closes.
key_takeaway	string	One-line summary of the model's view.
current_state_summary_richtext	string	Rich-text summary of the current state.
short_answer_richtext	string	Rich-text short answer.
executive_summary_richtext	string	Rich-text executive summary.
outcome_probabilities	array	Per-market outcome breakdown (see below). null if unavailable.
has_history	boolean	Whether this event has multiple historical snapshots for time-series analysis.

The response envelope also includes next_cursor and has_more for pagination.

Eligibility fields

Present only when include=eligibility is set:

Field	Type	Description
eligible	boolean | null	Whether a fresh report can be generated for this event.
eligibility_status	string | null	Market state on the marketplace: open, paused, unopened, closed, settled, or unknown.
eligibility_reason	string | null	Human-readable explanation for the eligible value.

Generate fresh reports with the Reports API.

Get an Event

GET /predictions/events/{event_ticker}

Returns one event as of one analysis run: its metadata, the run's headline numbers, and each market's quote and status from that run. Every number is as of captured_at. The report itself and its Trust Index come from the Reports API.

The path accepts a Kalshi event ticker or a Polymarket event slug, in any letter case.

Query Parameters

Parameter	Type	Required	Description
run_id	string (UUID)	No	Return the event as of this run. Defaults to the latest run.

Response Fields

Field	Type	Description
history_id	integer	Unique identifier for this snapshot.
run_id	string (UUID)	The analysis run this snapshot belongs to.
captured_at	string (ISO 8601)	When this snapshot was captured.
event_ticker	string	The event key: a Kalshi event ticker or a Polymarket event slug.
venue	string	kalshi or polymarket.
name	string	Human-readable event name.
title	string	Same as name.
slug	string	URL-friendly slug.
subtitle	string	Event subtitle.
image_url	string	Event image URL.
event_url	string	The event's page on the marketplace.
series_category	string	The venue's category for the event.
meta_category	string	Octagon's category, shared across venues.
resolution_cadence	string | null	How often markets of this kind resolve: five_min, fifteen_min, hourly, four_hour, daily, or weekly. null when none applies.
canonical_market_page	string | null	The category path the event's report is published under on octagonai.co/markets, e.g. politics/geopolitics.
mutually_exclusive	boolean	Whether the event's outcomes are mutually exclusive.
available_on_brokers	boolean	Whether the event is available on supported brokers.
analysis_last_updated	string (ISO 8601)	When the analysis behind this snapshot was produced.
model_probability	float	Octagon model probability for the event's primary market (0–100).
market_probability	float	Market-implied probability for the event's primary market (0–100).
edge_pp	float	model_probability - market_probability, in percentage points.
expected_return	float	Expected return if the model is correct.
r_score	float	Risk-adjusted score.
confidence_score	float	Octagon's confidence in the model output (0–10).
key_takeaway	string	One-line summary of the model's view.
total_volume	float	Total trading volume.
total_volume_24h	float	Trading volume over the 24 hours before capture.
total_open_interest	float	Total open interest.
close_time	string	When the event closes.
markets	array	Each market's model and market probability, quote, and status from this run (see below).

The response also carries the venue's own series, contract-terms and link fields as the venue publishes them: series_ticker, series_title, series_frequency, series_tags_raw, collateral_return_type, strike_date, strike_period, fee_type, fee_multiplier, settlement_sources_raw, additional_prohibitions_raw, contract_url, and contract_terms_url. kalshi_event_url and event_category_deprecated are legacy fields kept for existing clients. Read event_url for the event's page.

markets items

One item per market in the event:

Field	Type	Description
market_ticker	string	Ticker for this market.
outcome_name	string	Human-readable name for the outcome.
model_probability	float | null	Octagon model probability for this outcome (0–100). null when the run didn't model this market.
market_probability	float | null	Market-implied probability for this outcome (0–100).
model_probability_source	string | null	Provenance of model_probability — see Interpreting the model probability.
evidence_grade	string | null	Evidence quality behind model_probability (A–D).
reason	string | null	The model's one-line rationale for this outcome's probability.
volume	float | null	Total trading volume for this market.
volume_24h	float | null	Trading volume over the 24 hours before capture.
yes_bid	float | null	Best YES bid, as a price per $1 contract (0–1).
yes_ask	float | null	Best YES ask (0–1).
no_bid	float | null	Best NO bid (0–1).
no_ask	float | null	Best NO ask (0–1).
status	string	active, closed, determined, or terminated. Markets in one event resolve independently.

A determined market's market_probability is fixed at 0 or 100 by its result.

Status Codes

Status	Meaning
200	The event, as of the latest run or the run run_id names.
400	An unknown query parameter, or a malformed run_id (invalid_value).
404	No event matches the key, or the event has no snapshot for run_id (not_found).

Event History

GET /predictions/events/{event_ticker}/history

Returns historical snapshots for a single prediction market event by its ticker, newest first.

Finding the event ticker in a Kalshi URL. A Kalshi event URL has the form /markets/<series-ticker>/<event-slug>/<event-ticker>. In https://kalshi.com/markets/kxfeddecision/fed-meeting/kxfeddecision-26jun, the event ticker is KXFEDDECISION-26JUN. Market deeplinks end in a market ticker instead, which is the event ticker plus an outcome suffix: strip the suffix to get the event ticker (kxoaianth-40-oai → KXOAIANTH-40).

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Number of records to return. Default 50; minimum 1; maximum 200.
cursor	string	No	Cursor for pagination. Use the cursor returned from a previous response to continue.
captured_from	datetime (ISO 8601)	No	Start timestamp filter (inclusive) for snapshot capture time.
captured_to	datetime (ISO 8601)	No	End timestamp filter (inclusive) for snapshot capture time.
include	string	No	Set to analysis to include the analysis fields in the response.
days	integer	No	Exclude snapshots where close_time is before now minus this many days. Snapshots with no close_time are always included. Minimum 1.
exclude_empty_model	boolean	No	When true, exclude snapshots where model_probability is null (incomplete analysis). Default true.

Response Fields

Each snapshot in the data array includes:

Field	Type	Description
history_id	integer	Unique identifier for this snapshot.
run_id	string (UUID)	The export run that produced this snapshot.
captured_at	string (ISO 8601)	When this snapshot was captured.
event_ticker	string	Ticker identifier for the event.
name	string	Human-readable event name.
slug	string	URL-friendly slug.
series_category	string	Category (e.g., "Politics", "Crypto", "Economics").
close_time	string	When the event closes.
confidence_score	float	Octagon's confidence in the model output (0–10 scale).
model_probability	float	Octagon model probability for the event (0–100 percentage scale).
market_probability	float	Current market-implied probability (0–100 percentage scale).
edge_pp	float	Model edge in percentage points (model_probability - market_probability). See Interpreting the model probability.
expected_return	float	Expected return if the model is correct.
r_score	float	Risk-adjusted score.
total_volume	float	Total trading volume.
total_open_interest	float	Total open interest.
outcome_probabilities	array	Per-market outcome breakdown (see below). null if unavailable.

When include=analysis is set, these additional fields are included:

Field	Type	Description
key_takeaway	string	One-line summary of the model's view.
current_state_summary_richtext	string	Rich-text summary of the current state.
short_answer_richtext	string	Rich-text short answer.
executive_summary_richtext	string	Rich-text executive summary.

The response envelope also includes the requested event_ticker, plus next_cursor and has_more for pagination.

outcome_probabilities items

Each item in the outcome_probabilities array represents one market/outcome within the event:

Field	Type	Description
market_ticker	string	Ticker for this specific market/outcome.
outcome_name	string	Human-readable name for the outcome.
model_probability	float	Octagon model probability for this outcome (0–100 percentage scale).
model_probability_source	string	Provenance of model_probability — see Interpreting the model probability. null on rows written before this field existed.
evidence_grade	string	Evidence quality behind model_probability (A–D), which bounds how far it may deviate from the market-derived anchor. null when unavailable.
market_probability	float	Market-implied probability for this outcome (0–100 percentage scale).
reason	string	The model's one-line rationale for this outcome's probability. null when unavailable.

Interpreting the model probability

model_probability is market-anchored: it starts from the contract's own market price and is adjusted for the research evidence on that outcome. It is a calibrated read on the price, not a second estimate derived independently of it — treat it as correlated with market_probability rather than as an independent opinion.

For a second opinion to weigh against your own model, use rows where model_probability_source is recalibrated and evidence_grade is A or B. Those are the rows where research evidence moved the value furthest from the market-derived anchor. Other combinations track the market price closely by construction.

ladder_model answers a narrower question. Its fitted parameters come from the ladder's own prices, so a rung is independent of its own quote but not of the market as a whole. Use it to compare rungs within a ladder — relative levels and ordering — rather than as an independent read on whether the ladder is priced correctly. The two fields:

model_probability_source	Meaning
ladder_model	A threshold ladder priced from barrier-touch geometry. The value follows from the contract's own threshold, not its own quote — see Ladder-priced rows.
recalibrated	Research evidence moved the value away from the market-derived anchor.
market_baseline	The market price re-expressed. Carries no signal beyond the price.
unmodeled / out_of_scope	Not modelled; do not read as a forecast.
determined	The market has settled; the outcome is known.

evidence_grade bounds the maximum deviation from the anchor, so a low grade means the value is close to the market price by construction regardless of what the research said:

Grade	Maximum deviation from anchor
A	±20pp
B	±12pp
C	±7pp
D	±3pp

Ladder-priced rows

On a threshold ladder — a set of contracts on the same underlying at different levels ("above $95,000", "above $120,000") — rows marked ladder_model are derived differently from every other source. One spot and one volatility are fitted to the ladder as a whole, and each rung's probability is then the first-passage probability of reaching its own threshold under that single view.

Two consequences that matter when you consume these:

• Two rungs quoted at the same price receive different probabilities, because the value follows from the threshold rather than from the quote. Contrast market_baseline, where equal prices give equal model probabilities by construction. (recalibrated rows may differ at equal prices when their evidence differs, but nothing guarantees it — only ladder_model separates them structurally.)
• Ordering is guaranteed. P(above $95k) >= P(above $120k) holds as an identity, not as a best effort, so you can rely on monotonicity across a ladder without re-sorting.

One limit, stated plainly: the fitted spot and volatility come from the ladder's own prices. A rung's value is independent of its own quote, but the ladder's overall level is still market-derived, so this will not tell you that an entire ladder is mispriced. Rows fall back to recalibrated or market_baseline whenever the fit does not describe the book.

Use Cases

• Discover all events currently tracked and analyzed by Octagon, or build a catalog/dashboard of active events.
• Monitor the latest model probabilities, confidence scores, and analysis across all events.
• Filter to events with historical data (has_history=true), then drill into each event's time-series via the history endpoint.
• Build time-series views of model vs. market probability for a specific event ticker.
• Backtest signal quality (for example, edge_pp and expected_return) across historical snapshots.
• Backtest multi-outcome events using outcome_probabilities per snapshot.
• Track how confidence and liquidity metrics evolve as an event approaches resolution.

Notes

• On Event History, prefer bounded time windows (captured_from and captured_to) for predictable page sizes.
• Probability and score scales follow the Kalshi Search API conventions.