Prediction accuracy API reference
How well prediction markets called what happened, per topic, 1 hour, 1 day and 7 days before the close
Overview
Prediction accuracy says how far the Kalshi and Polymarket markets were from what happened. For each topic it reads what the market said a fixed time before the close and compares it with the settled result, over every settled event of the topic that Narwhal has stored.
A topic is measured one way, named in measure. A price topic (crude oil at a fixed time, gold) is measured by the miss: the distance between the market's median and the settled value, in the unit of the topic (usd_ for crude oil), as a mean and a median over the events. A yes or no topic (up or down on the day) is measured by how often the favourite won, the favourite being the side above 50 percent. The figures of the other measure are always null.
Each topic is read at three lead times: 1 hour (1h), 1 day (1d) and 7 days (7d) before the close. The market at a lead time is the last stored quote at or before that moment, and it counts only when the quote was live and Narwhal had a blended value for it, and was stored no more than the lead before that moment (at most a day before it, for 1d and 7d). An event listed less than the lead before its close, quoted thin or stale, or whose last quote at that point is older than this, is left out of that lead. Most events are listed a day or less before they close, so 7d has few events. events beside the figures is the number of events they rest on.
Void events never count; only settled ones do. A figure is null, never a number, when fewer than 20 events stand behind it, and reason says why. Extreme and timing topics are not measured, because their settled outcomes cannot be matched to the stored quotes. The page is a record of how the markets did, not a forecast.
Base URL: https:/. Each route below is an MCP tool of its own, with the same parameters.
The topics, events and probabilities these figures are about are on the Predictions API reference.
What every account gets
| What | Every account |
|---|---|
| Accuracy of all topics | Included. One call |
| Accuracy of one topic | Included. One call |
See pricing for what a call costs. A request is charged at the price of its API unless a route says otherwise.
- Both routes are charged like every other prediction route: one call at the Markets price of $2 per 1,000 calls. A topic that does not exist is not charged.
- A figure needs at least 20 events behind it. Below that
favourite_,won_ rate mean_andabs_ error median_are null andabs_ error reasonistoo_.few_ events eventsis the number of events behind the figures of the row. - A yes or no market at exactly 50 percent has no favourite and is left out of
eventsand of the rate. - A quote is only used when it is fresh at its lead point: for
1hit must have been stored in the hour before one hour ahead of the close, and for1dand7din the day before the lead point. Narwhal keeps one quote a day for markets older than 30 days, so an old event can fail this at1hand is then not counted there. That is why1hhas fewer events than1don some topics. - The miss is in the unit of the topic and is the same size as the thing measured: a mean miss of 2.04 on a crude oil market near 94 dollars is about 2 percent. Compare topics in the same unit only.
- The settled value of a price market is the number Kalshi reports as its expiration value. A price topic that settles only on Polymarket has no stored value and is not measured: its events are counted in
events_and nowhere else.settled - Yes or no topics are mostly quoted thin (too little depth for a blended value), so few of their events pass the 1 day lead and none pass 1 hour today; expect null with
too_there.few_ events events_is the number of settled events of the topic that your plan can see. A plan that sees predictions with a delay sees only events that settled before its cutoff, so the figures move as events become visible.settled - The list route returns every topic with at least one settled event, ended topics included, ordered by topic id. A topic with none is left out of the list, and the topic route answers it with
events_0 and every figure null.settled - The figures are recomputed from the stored data on every call. They change as events settle and as new events are measured.
Endpoints
Every route is a GET and needs your key in the Authorization: Bearer header. The examples show the shape of an answer, not live data.
List prediction accuracy by topic
GET /v1/predictions/accuracy
For every prediction topic with a settled event, read 1 hour, 1 day and 7 days before the close: for a price topic how far the market's median was from the settled value, for a yes or no topic how often the favourite won. Void events are not counted. A figure is null with a reason when fewer than 20 events stand behind it.
The example shows two of the topics the route returns.
MCP: tool predictions_.
Parameters
This route takes no parameters.
Response fields
| Field | Type | Sent | Meaning |
|---|---|---|---|
topics | list of object | Always | Every topic with at least one settled event, ended topics included, ordered by topic id. |
topics[].topic_ | string | Always | The topic, as the topics route lists it. |
topics[].shape | one of scalar, extreme, timing, binary, categorical, set | Always | How the topic's markets are shaped: scalar, binary, extreme or timing. |
topics[].measure | one of median_error, favourite_won | Always | What the topic is measured by: median_error for a price topic (how far the market's median was from the settled value), favourite_won for a yes/no topic (how often the favourite won). Null for extreme and timing topics, which are not measured. |
topics[].unit | string | Optional | Combined unit text such as usd_per_barrel; the unit of the two error figures. |
topics[].events_ | integer | Always | Settled events of the topic that this plan can see. Void events are not counted. |
topics[].leads | list of object | Always | Three rows, one for each lead time: 1h, 1d and 7d. |
topics[].leads[].lead | one of 1h, 1d, 7d | Always | How long before the close the market is read: 1h, 1d or 7d. The market is the last stored quote at or before that time, and only when it was live and the topic had a blended value then. |
topics[].leads[].events | integer | Always | Settled events behind the figures of this row: with a live blended quote at this lead and a settled outcome (for a yes/no topic, also one favourite: exactly 50% has none). |
topics[].leads[].favourite_ | string | Always | Yes/no topics (measure favourite_won): the share of events the favourite won, between 0 and 1. Null below 20 events, and always null on a price topic. |
topics[].leads[].mean_ | string | Always | Price topics (measure median_error): the average distance, in the topic's unit, between the market's median and the settled value. Null below 20 events, and always null on a yes/no topic. |
topics[].leads[].median_ | string | Always | Price topics (measure median_error): the middle distance, in the topic's unit, between the market's median and the settled value. Null below 20 events, and always null on a yes/no topic. |
topics[].leads[].reason | one of too_few_events, shape_not_measured | Always | Why the figures are null: too_few_events, or shape_not_measured for extreme and timing topics (their settled outcomes cannot be matched to the stored quotes). Null when the figures are given. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/predictions/accuracy"{
"topics": [
{
"topic_id": "wti-settle",
"shape": "scalar",
"measure": "median_error",
"unit": "usd_per_barrel",
"events_settled": 30,
"leads": [
{
"lead": "1h",
"events": 21,
"favourite_won_rate": null,
"mean_abs_error": "0.4400",
"median_abs_error": "0.3700",
"reason": null
},
{
"lead": "1d",
"events": 29,
"favourite_won_rate": null,
"mean_abs_error": "2.0397",
"median_abs_error": "1.6000",
"reason": null
},
{
"lead": "7d",
"events": 0,
"favourite_won_rate": null,
"mean_abs_error": null,
"median_abs_error": null,
"reason": "too_few_events"
}
]
},
{
"topic_id": "xau-settle",
"shape": "scalar",
"measure": "median_error",
"unit": "usd_per_troy_ounce",
"events_settled": 32,
"leads": [
{
"lead": "1h",
"events": 22,
"favourite_won_rate": null,
"mean_abs_error": "7.1473",
"median_abs_error": "4.7300",
"reason": null
},
{
"lead": "1d",
"events": 31,
"favourite_won_rate": null,
"mean_abs_error": "47.3510",
"median_abs_error": "37.3400",
"reason": null
},
{
"lead": "7d",
"events": 2,
"favourite_won_rate": null,
"mean_abs_error": null,
"median_abs_error": null,
"reason": "too_few_events"
}
]
}
]
}Get the accuracy of one prediction topic
GET /v1/predictions/accuracy/{topic_id}
One topic read 1 hour, 1 day and 7 days before the close: for a price topic how far the market's median was from the settled value, for a yes or no topic how often the favourite won. Void events are not counted. A figure is null with a reason when fewer than 20 events stand behind it.
topic_ is a topic from the topics route. An unknown topic is 404 event_.
MCP: tool predictions_.
Parameters
| Parameter | Where | Required | Type | Meaning |
|---|---|---|---|---|
topic_ | path | Yes | string | The topic, as the topics route lists it, for example wti-settle. |
Response fields
| Field | Type | Sent | Meaning |
|---|---|---|---|
topic_ | string | Always | The topic, as the topics route lists it. |
shape | one of scalar, extreme, timing, binary, categorical, set | Always | How the topic's markets are shaped: scalar, binary, extreme or timing. |
measure | one of median_error, favourite_won | Always | What the topic is measured by: median_error for a price topic (how far the market's median was from the settled value), favourite_won for a yes/no topic (how often the favourite won). Null for extreme and timing topics, which are not measured. |
unit | string | Optional | Combined unit text such as usd_per_barrel; the unit of the two error figures. |
events_ | integer | Always | Settled events of the topic that this plan can see. Void events are not counted. |
leads | list of object | Always | Three rows, one for each lead time: 1h, 1d and 7d. |
leads[].lead | one of 1h, 1d, 7d | Always | How long before the close the market is read: 1h, 1d or 7d. The market is the last stored quote at or before that time, and only when it was live and the topic had a blended value then. |
leads[].events | integer | Always | Settled events behind the figures of this row: with a live blended quote at this lead and a settled outcome (for a yes/no topic, also one favourite: exactly 50% has none). |
leads[].favourite_ | string | Always | Yes/no topics (measure favourite_won): the share of events the favourite won, between 0 and 1. Null below 20 events, and always null on a price topic. |
leads[].mean_ | string | Always | Price topics (measure median_error): the average distance, in the topic's unit, between the market's median and the settled value. Null below 20 events, and always null on a yes/no topic. |
leads[].median_ | string | Always | Price topics (measure median_error): the middle distance, in the topic's unit, between the market's median and the settled value. Null below 20 events, and always null on a yes/no topic. |
leads[].reason | one of too_few_events, shape_not_measured | Always | Why the figures are null: too_few_events, or shape_not_measured for extreme and timing topics (their settled outcomes cannot be matched to the stored quotes). Null when the figures are given. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/predictions/accuracy/wti-settle"{
"topic_id": "wti-settle",
"shape": "scalar",
"measure": "median_error",
"unit": "usd_per_barrel",
"events_settled": 30,
"leads": [
{
"lead": "1h",
"events": 21,
"favourite_won_rate": null,
"mean_abs_error": "0.4400",
"median_abs_error": "0.3700",
"reason": null
},
{
"lead": "1d",
"events": 29,
"favourite_won_rate": null,
"mean_abs_error": "2.0397",
"median_abs_error": "1.6000",
"reason": null
},
{
"lead": "7d",
"events": 0,
"favourite_won_rate": null,
"mean_abs_error": null,
"median_abs_error": null,
"reason": "too_few_events"
}
]
}Errors
Errors use the shared problem shape with a request_. See Errors and credits for the shape and the credit headers. Failed requests are not charged.
| Code | Status | Meaning |
|---|---|---|
event_ | 404 | No topic has this id. |
predictions_ | 503 | The prediction data cannot answer right now. Try again shortly. This is not charged. |
insufficient_ | 402 | Your credit balance is less than the request costs. |
Was this page helpful?