Prediction Markets Reports API

Retrieve Octagon's research reports for prediction markets directly over REST — list the report versions available for an event, pull the markdown for one of them, check the status of a generation run, or trigger fresh report generation without going through the Prediction Markets Agent.

The report body is the same markdown research memo the agent produces.

Field style, timestamps, and probability scales follow the Conventions. Base URL:

Base URL

https://api.octagonai.co/v1

Endpoints

Each marketplace has its own endpoints, addressed by that marketplace's native event key.

Method	Path	Description	Credits
GET	/predictions/reports/kalshi/{event_ticker}	Report versions for a Kalshi event	Free
GET	/predictions/reports/polymarket/{event_slug}	Report versions for a Polymarket event	Free
GET	/predictions/reports/status/{run_id}	Status of a generation run (no report body)	Free
POST	/predictions/reports/kalshi/{event_ticker}	Generate a fresh Kalshi report (asynchronous)	3
POST	/predictions/reports/polymarket/{event_slug}	Generate a fresh Polymarket report (asynchronous)	3

Credits per call are listed above. See the Prediction Markets Agent for plan eligibility.

Event Keys

Endpoints	Key	Example
/reports/kalshi/…	Event ticker	KXBTC-25DEC31
/reports/polymarket/…	Event slug	fed-decision-in-september

Address markets by event key. The Prediction Markets Agent also accepts market URLs.

Retrieve Report Versions

GET /predictions/reports/kalshi/{event_ticker}
GET /predictions/reports/polymarket/{event_slug}

Returns the report version snapshots for the event, newest first — up to the 6 most recent. The version list is always returned; the markdown body is opt-in via the version query parameter.

Query Parameters

Parameter	Type	Required	Description
version	string	No	latest for the newest version, or a run_id to pin an exact version. Include it to get markdown_report.

Response Fields

Field	Type	Description
event_ticker	string	The resolved event key.
venue	string	kalshi or polymarket, matching the endpoint called.
requested_url	string | null	The resolved market URL on the marketplace.
versions	array	Report version snapshots, newest first (up to 6). Empty when nothing has been generated yet.
markdown_report	string | null	The full report as markdown. Populated only when version is supplied and resolves to a version.
run_id	string | null	The run that markdown_report corresponds to; null when no body was requested.

Each entry in versions is a lightweight snapshot of the report at that run:

Field	Type	Description
run_id	string (UUID)	The run that produced this version. Pass it back as ?version=.
event_ticker	string	The event key for the snapshot.
name	string	Human-readable event name.
captured_at	string	When the snapshot was captured.
analysis_last_updated	string	When the underlying analysis was last refreshed.
market_probability	float	Market-implied probability.
model_probability	float	Octagon model probability.
confidence_score	float	Octagon's confidence in the model output.
total_volume	float	Total trading volume at capture time.
key_takeaway	string	One-line summary of the analysis.
outcome_probabilities	array | null	Per-market probability breakdown for the event.

Status Codes

Status	Meaning
200	The event key resolved. versions may be empty when nothing has been generated for it yet.
400	Malformed event key, or an unknown query parameter (invalid_value).
404	The event key matches nothing (not_found), or ?version=<run_id> is not one of the event's versions.

Check a Run's Status

GET /predictions/reports/status/{run_id}

Returns the status of a generation run. Poll it after triggering fresh generation. When status is "completed", fetch the markdown from the marketplace endpoint using the returned venue and event_ticker, with ?version=latest or ?version=<run_id>.

Parameter	Type	Required	Description
run_id	string (UUID)	Yes	The run ID returned by a POST to /reports.

Response Fields

Field	Type	Description
run_id	string (UUID)	The requested run.
status	string	"processing", "completed", or "failed".
venue	string	kalshi or polymarket — which marketplace endpoint to fetch from.
event_ticker	string | null	The resolved event key for the run.
requested_url	string | null	The resolved market URL for the run.

A known run always returns 200 — poll until status leaves "processing". A "failed" run means generation did not complete. 404 (not_found) means the run_id is unknown.

TIP

If you only need the report body as soon as it's ready, you can skip this endpoint and poll the marketplace endpoint with ?version=latest directly — markdown_report stays null until the new version lands.

Generate a Fresh Report

POST /predictions/reports/kalshi/{event_ticker}
POST /predictions/reports/polymarket/{event_slug}

Triggers fresh report generation for a market. There is no request body — the market is identified entirely by the path. Generation is asynchronous. The request returns 202 Accepted immediately with a run_id.

Response Fields (202 Accepted)

Field	Type	Description
run_id	string (UUID)	The generation run. Poll GET /predictions/reports/status/{run_id} with it.
status	string	Always "processing" on acceptance.
event_ticker	string	The resolved event key.
venue	string	kalshi or polymarket, matching the endpoint called.

The 3-credit charge is applied when the 202 is returned. If generation subsequently fails, the credits are automatically refunded.

Requirements

• Market status: the market must be open on the marketplace.

Errors

Status	Code	Meaning
400	invalid_value	Malformed event key.
400	kalshi_url_required	No event matches the key.
400	kalshi_reference_ambiguous	The key matches multiple events.
401	no_subscription	No active subscription on the API key.
403	insufficient_plan	Fresh generation requires a Plus, Pro, or Enterprise plan.
404	kalshi_market_not_found	The market could not be found on the marketplace.
409	kalshi_market_not_open	The market is not open on the marketplace (expired).
429	insufficient_credits	Not enough credits for the 3-credit charge.
503	service_unavailable	The generation service could not be reached.

Errors use the envelope {"error": {"message", "type", "param", "code"}}.

Notes

• Poll every 30–60 seconds; fresh generation typically takes several minutes.
• The run_id returned by a POST is the single join key: use it to check run status, to pin a version on retrieval (?version=<run_id>), and to reconcile the credit charge.