Return markets across covered platforms, filtered by title substring, platform and category.
Query parameters
Query parameters
Name
Type
Description
q
string
Title substring match. This is a plain substring filter on the market title, not semantic or natural-language matching, so a full question will usually return nothing.
platform
string
Comma-separated list of platforms to include, for example kalshi,polymarket.
category
string
Restrict results to a single category.
status
string
open, retained, past_resolution or all, defaulting to open. open returns state=open: in Riddle's retained feed, seen by an ingestion pass within the last 10 minutes, and no stored scheduled resolution has passed. retained returns state=retained_unobserved: retained and not past schedule, but not seen in the last 10 minutes. past_resolution returns contracts whose stored scheduled resolution time has passed, in the feed or not. all applies no lifecycle filter. None of these is a venue-verified trading status.
limit
integer
Results per page. Defaults to 50, maximum 200.
cursor
string
Opaque cursor taken from page.next_cursor on the previous response. Do not parse it.
sort
string
market_id is the only supported sort field. Defaults to market_id.
Platform-native market identifier. Combined with platform, this addresses the market.
platform
string
The platform the market is listed on.
title
string
Market title as published by the platform.
category
string | null
Category assigned to the market.
event_ticker
string | null
Platform event grouping identifier, where the platform publishes one.
market_ticker
string | null
Platform market ticker, where the platform publishes one.
yes_probability
number | null
Indicative probability of the yes side as a fraction between 0 and 1. Null when unavailable.
no_probability
number | null
Indicative probability of the no side as a fraction between 0 and 1. Null when unavailable.
price_change_24h
number | null
Change in the yes probability over the change window, in the same 0 to 1 units.
price_change_window_hours
number | null
Length in hours of the window that price_change_24h was measured over.
volume_24h_usd
number | null
Volume over 24 hours in US dollars where the platform publishes a documented window figure. Polymarket only today; null on Kalshi and Limitless. Null means unavailable, not zero.
volume_7d_usd
number | null
Volume over 7 days in US dollars where the platform publishes a documented window figure. Polymarket only today; null on Kalshi and Limitless. Null means unavailable, not zero.
resolution_date
timestamp | null
Venue-stated resolution or expiry timestamp, RFC 3339 UTC, as Riddle stored it. Null when not retrieved. Venue close time, settlement time and venue status are not retrieved.
venue_url
string | null
Link to the market on the platform, for verification by a human. Nullable, and emitted only when the URL validates against the expected HTTPS venue host. Kalshi grouped event links carry the exact outcome ticker when that ticker has been verified.
in_current_feed
boolean
Whether the market is in Riddle's retained feed membership. It stays true while the market is ranked, watchlisted, held in a position, a sibling of a ranked market, or was ranked in the previous 24 hours, so it is not limited to the latest refresh and can stay true after the venue has closed or resolved the market. A Riddle ingestion fact, not a venue tradable status.
last_seen_in_feed_at
timestamp | null
Last time the market appeared in a ranked ingestion pass. It does not advance while the market is only retained. Distinct from observed_at.
observed_at
timestamp | null
Nullable. When Riddle materialised the values on this record, which is a Riddle-side time and not a venue timestamp. Read it with the probabilities, never without, and handle the null case.
state
string
Riddle lifecycle classification computed at request time: open, retained_unobserved, past_scheduled_resolution or not_in_current_feed. open means retained, seen by ingestion within 10 minutes and no stored schedule passed. past_scheduled_resolution is never read as resolved. Not a venue-verified tradable status.
Return Riddle observations of a market over a requested window.
Query parameters
Query parameters
Name
Type
Description
days
integer
Length of the requested window in days. Defaults to 30, maximum 365. This is the window you are asking for, not a guarantee that observations exist across it.
limit
integer
Maximum observations returned, up to 2000.
Observation fields
Observation fields
Name
Type
Description
observed_at
timestamp
Never null on a returned point. When Riddle recorded the observation, RFC 3339 UTC. It is a Riddle-side time, not a venue timestamp.
yes_probability
number
Indicative probability of the yes side at that observation, as a fraction between 0 and 1. Never null on a returned point: observations that are invalid or of an unapproved type are omitted from the series rather than returned with a null value.
indicative_basis
string | null
What the indicative probability was derived from for that observation.
price_semantics_version
integer | null
Version of the price semantics in force when the observation was recorded, so older points are interpreted under the rules that produced them.
Response envelope
Response envelope
Name
Type
Description
data
array
Observations in time order. History is not paginated and returns no page object or cursor.
meta.platform
string
The platform the requested market is listed on.
meta.market_id
string
The platform-native market id that was requested.
meta.days
integer
The window applied to this response, in days.
meta.window.requested_days
integer
The window length you asked for, echoed back after defaulting and clamping.
meta.window.since
timestamp
ISO start of the requested window, computed at request time. It bounds what was looked at, not what exists.
meta.window.until
timestamp
ISO end of the requested window, computed at request time.
meta.returned_points
integer
Number of observations in the data array.
meta.first_observation_at
timestamp | null
Observation time of the first returned point, or null when the series is empty.
meta.last_observation_at
timestamp | null
Observation time of the last returned point, or null when the series is empty.
meta.rows_examined
integer
How many stored rows were examined to build this response.
meta.excluded_invalid_points
integer
Invalid or unapproved observations dropped from the examined slice. It counts only the rows examined for this request and says nothing about data outside the window or beyond the point limit.
meta.limits.requested_limit
integer
The limit you asked for on this request.
meta.limits.effective_point_limit
integer
The limit actually applied after clamping.
meta.limits.max_points
integer
Hard ceiling on points in one history response. Currently 2000.
meta.truncated
boolean
Whether the series was cut short by the point limit rather than by the window.
meta.completeness
string
Always partial_by_construction. History is a Riddle observation series, so it is partial by design.
meta.completeness_note
string
Prose restating that the series carries no claim of full venue retention or of complete coverage across the requested window.
meta.series_type
string
Always riddle_observations, marking the series as Riddle observations rather than venue market data.
Read the meta block before you analyse the series. The window fields tell you what was looked at, returned_points and the observation bounds tell you what came back, and truncated with excluded_invalid_points tells you whether the slice you are holding is the whole of what was examined. A window you asked for is not evidence that observations exist across it, so treat these series as partial by construction rather than as backtest coverage.
resp = session.get(
f"{BASE}/v1/markets/{platform}/{market_id}/history",
params={"days": 90, "limit": 2000},
timeout=20,
)
payload = resp.json()
meta = payload["meta"]
if meta["truncated"]:
print("series hit the point limit", meta["limits"]["effective_point_limit"])
if meta["excluded_invalid_points"]:
print("dropped from the examined slice:", meta["excluded_invalid_points"])
if meta["returned_points"] == 0:
raise SystemExit("no observations in this window")
print("requested", meta["window"]["since"], "to", meta["window"]["until"])
print("observed", meta["first_observation_at"], "to", meta["last_observation_at"])
# Analyse against the observed bounds, not the requested window.
points = payload["data"]
Return the research projection for one exactly addressed market.
Research uses the same x-api-key header and the same account quota as the rest of v1. It is addressed the same way as detail and history: the exact platform (kalshi, polymarket or limitless) and the market_id exactly as returned by /v1/markets, URL-encoded as one path segment. There is no title matching.
Query parameters
Query parameters
Name
Type
Description
related_limit
integer
Maximum related-contract members on this page. 1 to 50, default 20.
related_after
string
Continue strictly after the previous page's related_contracts.page.next_after_market_id. Maximum 200 characters. Pages are not frozen snapshots if feed membership changes.
Fields on data
Fields on data
Name
Type
Description
model_version
string
research-v1.2.0.
retrieved_at
timestamp
Server clock reading when the projection was built. Ages are measured against it.
identity
object
platform, market_id, title, venue_url, in_current_feed and last_seen_in_feed_at for the exact identity requested.
quote
null
Always null in research-v1.2.0. No quote numbers are returned and no feed probability is substituted while typed and feed observation alignment is under review.
quote_availability
string
withheld (an exact typed row exists but its economics are suppressed) or not_retrieved (no matching typed row; typed coverage is a subset of the feed).
quote_unavailable_reason
string | null
Why no quote numbers are present.
quote_source
string | null
Ingestion path for an exact typed row, or null if none was retrieved.
staleness
object
state (fresh, stale, unknown or reference_timestamp_in_future), threshold_seconds (default 300), reference_field, reference_at, age_seconds and note. The threshold is a labelling convention; apply your own rule to age_seconds.
rules
object
availability (retrieved or not_retrieved), text, text_truncated and provenance. provenance.record_updated_at is when Riddle's record changed, not a venue publication time; venue_publication_timestamp is always null.
resolution
object
resolution_date (RFC 3339, nullable) and resolution_date_source. close_time and settlement_time are always null because no Riddle path retrieves them.
equivalence_note
string
States that the projection asserts no equivalence between contracts.
related_contracts
object
status (available, ungrouped or source_not_current), source, candidate_group_id, equivalence_established (always false), note, members (platform, market_id, title, resolution_date) and page (limit, returned, truncated, next_after_market_id).
# Placeholder identity: substitute a market_id returned by /v1/markets.
MARKET_ID="KXPRESPERSON-28-JVAN"
ENCODED=$(python3 -c 'import sys,urllib.parse;print(urllib.parse.quote(sys.argv[1],safe=""))' "$MARKET_ID")
curl -G "$RIDDLE_API_BASE/v1/markets/kalshi/$ENCODED/research" \
--data-urlencode "related_limit=20" \
-H "x-api-key: $RIDDLE_API_KEY"
Request a research projection (identity is a placeholder; substitute one from /v1/markets)
An authenticated workspace at https://app.getriddle.ai/research sits alongside this endpoint. It compares two exactly addressed market identities, works through conditional binary settlement scenarios, and exports the working as JSON or CSV so a result can be reproduced.
Payout is a fixed, disclosed assumption of $1 per winning unit. It is not configurable.
Fees and slippage are the totals you enter yourself, per leg.
USD and USDC are treated at parity; no conversion or basis is modelled.