'%20d='M0%200H100C119%200%20128%209%20128%2028V39C128%2050%20122%2057%20110%2061C122%2065%20128%2074%20128%2087V100H92V88C92%2077%2088%2073%2077%2073H34V100H0ZM34%2025V49H79C89%2049%2092%2045%2092%2037C92%2029%2089%2025%2079%2025Z'/%3e%3cpath%20transform='translate(144)'%20d='M0%200H38V100H0Z'/%3e%3cpath%20transform='translate(198)'%20d='M0%200H107C130%200%20140%2010%20140%2033V67C140%2090%20130%20100%20107%20100H0ZM35%2027V73H96C103%2073%20106%2070%20106%2063V37C106%2030%20103%2027%2096%2027Z'/%3e%3cpath%20transform='translate(354)'%20d='M0%200H107C130%200%20140%2010%20140%2033V67C140%2090%20130%20100%20107%20100H0ZM35%2027V73H96C103%2073%20106%2070%20106%2063V37C106%2030%20103%2027%2096%2027Z'/%3e%3cpath%20transform='translate(510)'%20d='M0%200H34V73H120V100H0Z'/%3e%3cpath%20transform='translate(646)'%20d='M0%200H128V25H34V38H118V62H34V75H128V100H0Z'/%3e%3c/g%3e%3c/svg%3e)
Data semantics
The conventions behind the fields, so the numbers are not quietly misread.
Probabilities are indicative, not quotesPermalink to this section
yes_probability and no_probability are fractions between 0 and 1, whatever the platform's own convention. A value of 0.42 means the observation implies about a 42 percent chance under that contract's wording. It is an indicative observation with a timestamp, not an executable quote, and not a price you can trade at. Where a value is unavailable the field is null rather than zero.
- Always read a probability together with observed_at, and treat that field as nullable. It records when Riddle materialised the value, not a venue timestamp.
- Null means unavailable. Treating null as 0 will quietly poison an average.
- A probability is not a forecast from Riddle. It is what the platform was showing when we looked.
- Spreads, fees and available size sit at the venue. The API does not model what a fill would cost.
Price changePermalink to this section
price_change_24h is expressed in the same 0 to 1 units as the probabilities, so a value of -0.03 is three probability points, not three percent of the level. Read it with price_change_window_hours, which states the window the change was actually measured over.
IdentifiersPermalink to this section
| Identifier | Scope | Use it for |
|---|---|---|
| platform + market_id | Riddle | Addressing the detail and history endpoints. Neither part is unique on its own. |
| event_ticker | Platform | Grouping markets that belong to the same platform event, where published. |
| market_ticker | Platform | Reconciling with a platform feed you already hold, where published. |
| venue_url | Platform | Human verification of wording and settlement rules at the source. |
Store the platform alongside the market id everywhere. Market ids are platform-native, so an integration that keys on market_id alone will collide the first time two platforms use the same string.
Timestamps and datesPermalink to this section
Timestamps such as observed_at and last_seen_in_feed_at are RFC 3339 in UTC and nullable, and observed_at is a Riddle materialisation time rather than a venue timestamp. resolution_date is the resolution date as the platform publishes it, which is the platform's claim rather than a Riddle guarantee, and platforms do move dates. There is no venue trading status, close time or settlement field in the API.
Feed presencePermalink to this section
in_current_feed says whether the market was present in the most recent refresh, and last_seen_in_feed_at says when it was last seen. A market that drops out of the feed has not necessarily resolved or been delisted; it means Riddle did not see it in that refresh. Check the venue before drawing a conclusion from its absence.
VolumePermalink to this section
volume_24h_usd and volume_7d_usd carry a documented window figure in US dollars only where the platform publishes one. Where it does not, the field is null. Null means the figure is unavailable, not that volume was zero, and a null must never be coerced to 0 in an average or a ranking.
| Platform | volume_24h_usd | volume_7d_usd | Why |
|---|---|---|---|
| Polymarket | Documented window, USD | Documented window, USD | The platform publishes both windows in US dollars. |
| Kalshi | null | null | No established unit for the 24 hour figure, and the stored 7 day figure is a lifetime proxy rather than a window. |
| Limitless | null | null | The stored figure is lifetime rather than a window, so neither window can be reported honestly. |
What a search result meansPermalink to this section
The q parameter matches a substring of the market title. It is a text filter, not semantic matching, and it is not an assertion that the returned contracts address the same question or are economically equivalent. Two platforms can carry a similar headline and settle on different sources, dates or thresholds.
What the API does not carryPermalink to this section
Not returned: venue trading status, close times, settlement fields, order books, OHLCV and volume time series. Out of scope: order placement, routing or execution of any kind, any assertion that two markets are economically equivalent, and any streaming or websocket transport. Riddle is a research and information platform, not a broker, exchange or trading venue.
Storing what you pullPermalink to this section
- Record observations append-only and keep observed_at with every value.
- Keep price_semantics_version with historical observations so older points stay interpretable.
- Retain corrections rather than overwriting, and mark which version is current.
- Keep the outcome alongside any forecast you made, so later evaluation can be audited.