Prediction Markets Events History

Use this endpoint to retrieve historical snapshots for a prediction market event by its ticker, including model/market probability deltas, per-market outcome breakdowns, and time-series context for deeper analysis.

Like the Chat Completions and Responses endpoints, this is a direct REST endpoint and is called relative to the Octagon API base URL:

Base URL

https://api.octagonai.co/v1

Endpoint

GET /prediction-markets/events/<event_ticker>/history

Where <event_ticker> is the ticker of the prediction market event for which you want to retrieve the historical snapshots.

As a general rule, the event ticker is the last part of the market URL. See the examples below for more details.

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 heavier analysis columns in the response payload.
days	integer	No	Exclude snapshots where close_time is before now minus this many days. Minimum 1. Useful for filtering out markets that resolved long ago.
exclude_empty_model	boolean	No	When true, exclude snapshots where model_probability is null (incomplete analysis). Default false.

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.
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 (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).
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.
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.

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).
market_probability	float	Market-implied probability for this outcome (0–100 percentage scale).

Use Cases

• 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.
• Track how confidence and liquidity metrics evolve as an event approaches resolution.
• Use outcome_probabilities per snapshot for multi-outcome backtesting — compare per-market model vs. market probabilities over time.
• Filter to recent, high-quality snapshots with days and exclude_empty_model for cleaner backtesting data.

Examples

For the Kalshi market with URL https://kalshi.com/markets/kxbtcminy/how-low-will-bitcoin-get-in-2026/kxbtcminy-27jan01.

Get recent history for an event

Python

import requests

url = "https://api.octagonai.co/v1/prediction-markets/events/kxbtcminy-27jan01/history"
headers = {"Authorization": "Bearer your-octagon-api-key"}
params = {"limit": 50}

response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
print(response.json())

JavaScript

const params = new URLSearchParams({
  limit: "50",
});

const response = await fetch(
  `https://api.octagonai.co/v1/prediction-markets/events/kxbtcminy-27jan01/history?${params}`,
  {
    headers: {
      Authorization: "Bearer your-octagon-api-key",
    },
  }
);

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

cURL

curl -G "https://api.octagonai.co/v1/prediction-markets/events/kxbtcminy-27jan01/history" \
  -H "Authorization: Bearer <your-octagon-api-key>" \
  --data-urlencode "limit=50"

Example response (truncated for brevity):

{
  "event_ticker": "kxbtcminy-27jan01",
  "data": [
    {
      "history_id": 8926,
      "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "captured_at": "2026-03-18T19:03:37.293044Z",
      "event_ticker": "KXBTCMINY-27JAN01",
      "name": "How low will Bitcoin get in 2026?",
      "slug": "how-low-will-bitcoin-get-in-2026",
      "series_category": "Crypto",
      "close_time": "2027-01-01T05:00:00Z",
      "confidence_score": 7.5,
      "model_probability": 12.3,
      "market_probability": 15.0,
      "edge_pp": -2.7,
      "expected_return": -0.18,
      "r_score": -0.45,
      "total_volume": 850000.0,
      "total_open_interest": 210000.0,
      "outcome_probabilities": [
        { "market_ticker": "KXBTCMINY-27JAN01-B26JUL", "outcome_name": "Before July 2026", "model_probability": 7.0, "market_probability": 5.5 },
        { "market_ticker": "KXBTCMINY-27JAN01-B27JAN", "outcome_name": "Before 2027", "model_probability": 12.3, "market_probability": 15.0 }
      ]
    }
  ],
  "next_cursor": "eyJjYXB0dXJlZF9hdCI6IjIwMjYtMDMtMThUMTk6MDM6MzcuMjkzMDQ0WiIsImhpc3RvcnlfaWQiOjg5MjZ9",
  "has_more": true
}

Get a time-windowed history with analysis fields

Python

import requests

url = "https://api.octagonai.co/v1/prediction-markets/events/kxbtcminy-27jan01/history"
headers = {"Authorization": "Bearer your-octagon-api-key"}
params = {
    "captured_from": "2026-01-01T00:00:00Z",
    "captured_to": "2026-01-31T23:59:59Z",
    "limit": 100,
    "include": "analysis",
}

response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
print(response.json())

JavaScript

const params = new URLSearchParams({
  captured_from: "2026-01-01T00:00:00Z",
  captured_to: "2026-01-31T23:59:59Z",
  limit: "100",
  include: "analysis",
});

const response = await fetch(
  `https://api.octagonai.co/v1/prediction-markets/events/kxbtcminy-27jan01/history?${params}`,
  {
    headers: {
      Authorization: "Bearer your-octagon-api-key",
    },
  }
);

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

cURL

curl -G "https://api.octagonai.co/v1/prediction-markets/events/kxbtcminy-27jan01/history" \
  -H "Authorization: Bearer your-octagon-api-key" \
  --data-urlencode "captured_from=2026-01-01T00:00:00Z" \
  --data-urlencode "captured_to=2026-01-31T23:59:59Z" \
  --data-urlencode "limit=100" \
  --data-urlencode "include=analysis"

Filter for backtesting (recent markets with model data)

Python

import requests

url = "https://api.octagonai.co/v1/prediction-markets/events/FEDHIKE/history"
headers = {"Authorization": "Bearer your-octagon-api-key"}
params = {
    "days": 90,
    "exclude_empty_model": "true",
    "limit": 100,
}

response = requests.get(url, headers=headers, params=params)
response.raise_for_status()

for snapshot in response.json()["data"]:
    print(f"{snapshot['captured_at']}: model={snapshot['model_probability']}, market={snapshot['market_probability']}")

JavaScript

const params = new URLSearchParams({
  days: "90",
  exclude_empty_model: "true",
  limit: "100",
});

const response = await fetch(
  `https://api.octagonai.co/v1/prediction-markets/events/FEDHIKE/history?${params}`,
  {
    headers: {
      Authorization: "Bearer your-octagon-api-key",
    },
  }
);

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
data.data.forEach((snapshot) => {
  console.log(`${snapshot.captured_at}: model=${snapshot.model_probability}, market=${snapshot.market_probability}`);
});

cURL

curl -G "https://api.octagonai.co/v1/prediction-markets/events/FEDHIKE/history" \
  -H "Authorization: Bearer <your-octagon-api-key>" \
  --data-urlencode "days=90" \
  --data-urlencode "exclude_empty_model=true" \
  --data-urlencode "limit=100"

Notes

• Use cursor for pagination when the response is truncated by limit.
• Start with the default payload and only set include=analysis when those heavier fields are required.
• Prefer bounded time windows (captured_from and captured_to) for more stable and predictable retrieval.
• Use days to exclude markets that closed/resolved more than N days ago — useful for keeping backtesting data relevant. Markets with no close_time (still open) are always included.
• Use exclude_empty_model=true to filter out snapshots with incomplete analysis (null model_probability).
• All probability values (model_probability, market_probability, and those within outcome_probabilities) are expressed as percentages on a 0–100 scale (e.g., 37.7 means 37.7%).
• outcome_probabilities is null when outcome data is not available for a snapshot.