Browse all documentation

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_per_barrel 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://api.narwhalapi.com. 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

WhatEvery account
Accuracy of all topicsIncluded. One call
Accuracy of one topicIncluded. 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_abs_error and median_abs_error are null and reason is too_few_events. events is 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 events and of the rate.
  • A quote is only used when it is fresh at its lead point: for 1h it must have been stored in the hour before one hour ahead of the close, and for 1d and 7d in 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 at 1h and is then not counted there. That is why 1h has fewer events than 1d on 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_settled and nowhere else.
  • 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_few_events there.
  • events_settled 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.
  • 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_settled 0 and every figure null.
  • 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_list_accuracy.

Parameters

This route takes no parameters.

Response fields

FieldTypeSentMeaning
topicslist of objectAlwaysEvery topic with at least one settled event, ended topics included, ordered by topic id.
topics[].topic_idstringAlwaysThe topic, as the topics route lists it.
topics[].shapeone of scalar, extreme, timing, binary, categorical, setAlwaysHow the topic's markets are shaped: scalar, binary, extreme or timing.
topics[].measureone of median_error, favourite_wonAlwaysWhat 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[].unitstringOptionalCombined unit text such as usd_per_barrel; the unit of the two error figures.
topics[].events_settledintegerAlwaysSettled events of the topic that this plan can see. Void events are not counted.
topics[].leadslist of objectAlwaysThree rows, one for each lead time: 1h, 1d and 7d.
topics[].leads[].leadone of 1h, 1d, 7dAlwaysHow 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[].eventsintegerAlwaysSettled 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_won_ratestringAlwaysYes/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_abs_errorstringAlwaysPrice 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_abs_errorstringAlwaysPrice 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[].reasonone of too_few_events, shape_not_measuredAlwaysWhy 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.
Request
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/predictions/accuracy"
Example response
{
  "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_id is a topic from the topics route. An unknown topic is 404 event_not_found.

MCP: tool predictions_get_accuracy.

Parameters

ParameterWhereRequiredTypeMeaning
topic_idpathYesstringThe topic, as the topics route lists it, for example wti-settle.

Response fields

FieldTypeSentMeaning
topic_idstringAlwaysThe topic, as the topics route lists it.
shapeone of scalar, extreme, timing, binary, categorical, setAlwaysHow the topic's markets are shaped: scalar, binary, extreme or timing.
measureone of median_error, favourite_wonAlwaysWhat 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.
unitstringOptionalCombined unit text such as usd_per_barrel; the unit of the two error figures.
events_settledintegerAlwaysSettled events of the topic that this plan can see. Void events are not counted.
leadslist of objectAlwaysThree rows, one for each lead time: 1h, 1d and 7d.
leads[].leadone of 1h, 1d, 7dAlwaysHow 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[].eventsintegerAlwaysSettled 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_won_ratestringAlwaysYes/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_abs_errorstringAlwaysPrice 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_abs_errorstringAlwaysPrice 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[].reasonone of too_few_events, shape_not_measuredAlwaysWhy 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.
Request
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/predictions/accuracy/wti-settle"
Example response
{
  "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_id. See Errors and credits for the shape and the credit headers. Failed requests are not charged.

CodeStatusMeaning
event_not_found404No topic has this id.
predictions_unavailable503The prediction data cannot answer right now. Try again shortly. This is not charged.
insufficient_credits402Your credit balance is less than the request costs.

Was this page helpful?