List forecasts
GET
https://dash.alethman.com/api/v1/forecastsDated yes-or-no forecasts in the workspace’s sectors, each with its probability, deadline, resolution rule and, once judged, its outcome. counts and track_record cover every forecast in those sectors, not only the page returned, so they stay the same whatever limit you pass.
Request
Section titled “Request”| Parameter | In | Type | Default | Values | What it does |
|---|---|---|---|---|---|
sector |
query | string | a sector key | Only this sector. It must be one the workspace follows; another sector returns an empty list, not an error. | |
status |
query | string | all |
open, awaiting, resolved, all |
open: deadline ahead. awaiting: deadline passed, verdict not in. resolved: judged. all: every forecast. |
limit |
query | integer | 100 |
1 to 200 | How many forecasts to return, 1 to 200. |
Example
Section titled “Example”curl "https://dash.alethman.com/api/v1/forecasts?status=open&limit=20" \ -H "Authorization: Bearer $ALETHMAN_KEY"import osimport requests
r = requests.get( "https://dash.alethman.com/api/v1/forecasts", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, params={"status": "open", "limit": 20}, timeout=30,)r.raise_for_status()print(r.json())const url = new URL("https://dash.alethman.com/api/v1/forecasts");url.search = new URLSearchParams({ status: "open", limit: "20" });
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.ALETHMAN_KEY}`, },});if (!res.ok) throw new Error((await res.json()).error.message);console.log(await res.json());Response
Section titled “Response”200 OK, application/json, with the rate-limit headers. A real response, shortened: long lists are cut to a few items.
{ "data": [ { "id": 8419, "sector": "energy_power", "question": "Will Cyclone Akvan make landfall on the Andhra Pradesh coast by 21 November 2026?", "probability": 0.65, "made_at": "2026-11-16T15:55:38.996Z", "resolves_by": "2026-11-23T15:55:38.996Z", "resolution_rule": "Yes if IMD or Andhra Pradesh government confirms landfall by the deadline; no if the system weakens or veers away.", "status": "open", "resolved_at": null, "outcome": null, "verdict": null, "rationale": "IMD forecasts intensification and landfall around 20 November, consistent with its track record this season." }, { "id": 9610, "sector": "public_order_unrest", "question": "Will Maharashtra's subordinate court employees call off their indefinite strike by 25 Nov 2026?", "probability": 0.4, "made_at": "2026-11-17T22:24:27.754Z", "resolves_by": "2026-11-24T22:24:27.754Z", "resolution_rule": "Resolves yes if reporting confirms the strike is called off or suspended statewide by the deadline.", "status": "open", "resolved_at": null, "outcome": null, "verdict": null, "rationale": "Pay-parity strikes halting hearings usually draw quick government talks, but indefinite action with no reported negotiation yet suggests it could run longer." }, { "id": 4253, "sector": "energy_power", "question": "Will the World Meteorological Organization confirm El Niño has reached record strength in a formal bulletin by 22 Nov 2026?", "probability": 0.25, "made_at": "2026-10-22T21:54:44.291Z", "resolves_by": "2026-11-21T21:54:44.291Z", "resolution_rule": "Yes if WMO issues an updated bulletin explicitly stating record-strength El Niño conditions have been reached.", "status": "open", "resolved_at": null, "outcome": null, "verdict": null, "rationale": "WMO's 22 Oct statement used conditional language ('may reach'); formal confirmation of record strength typically lags initial warnings by months." } ], "counts": { "open": 90, "due_this_week": 42, "awaiting": 71, "resolved": 351 }, "track_record": { "resolved": 294, "void": 57, "brier_score": 0.22685238095238117 }}Fields
Section titled “Fields”| Field | Type | Values | What it is |
|---|---|---|---|
data |
array of objects | Forecasts, newest first. | |
data[].id |
integer | The forecast’s id. | |
data[].sector |
string | a sector key | A sector key. See Countries and scopes for the list. |
data[].question |
string | A yes-or-no question with a date in it. | |
data[].probability |
number | 0 to 1 | The probability of yes when the forecast was made, 0 to 1. It is never revised. |
data[].made_at |
string (time) | When the forecast was made. | |
data[].resolves_by |
string (time) | The deadline. | |
data[].resolution_rule |
string | What counts as yes, written before the outcome was known. | |
data[].status |
string | open, awaiting, resolved |
open: the deadline is ahead. awaiting: the deadline has passed and no verdict is in yet. resolved: judged. |
data[].resolved_at |
string (time) or null | When it was judged, or null. | |
data[].outcome |
boolean or null | True if it came true, false if not; null until resolved, or when a resolved forecast was voided. | |
data[].verdict |
string or null | The judgement in a sentence, with what it rests on, or null. | |
data[].rationale |
string | Why the probability was set where it was, written when it was made. | |
counts |
object | Counts over every forecast in the sectors. | |
counts.open |
integer | Deadline ahead. | |
counts.due_this_week |
integer | Open, with the deadline in the next 7 days. | |
counts.awaiting |
integer | Deadline passed, verdict not in. | |
counts.resolved |
integer | Judged, voided included. | |
track_record |
object | How the forecasts have done. | |
track_record.resolved |
integer | Judged true or false. | |
track_record.void |
integer | Judged but voided: the question could not be settled as asked. | |
track_record.brier_score |
number or null | The Brier score of the forecasts judged true or false: the mean squared gap between probability and outcome, 0 (perfect) to 1. 0.25 is what always saying 50% earns. Null before any is judged. |
Errors
Section titled “Errors”Every error has the body {"error": {"code": …, "message": …}}; branch on code. See Errors for how to handle each.
| Status | Code | When |
|---|---|---|
| 400 | bad_request |
A parameter is out of range, not an allowed value, too long, or not an ISO 8601 time (for cursor: not one the API gave). The message names the parameter and what it accepts. |
| 401 | unauthenticated |
No Authorization header, or one that is not Bearer <key>. Answered with WWW-Authenticate: Bearer realm="alethman". |
| 401 | invalid_key |
The key is unknown, revoked or expired, its workspace is suspended, or the person who made it is no longer an active owner or admin. Answered with WWW-Authenticate: Bearer realm="alethman", error="invalid_token". |
| 403 | insufficient_scope |
The key is valid but does not carry the scope this endpoint needs. The message names the scope. |
| 409 | workspace_not_ready |
The workspace has not been set up yet. An owner or admin finishes the setup walkthrough in the dashboard first. |
| 429 | rate_limited |
More than 120 requests in a minute on one key (wait for Retry-After seconds), or more than 30 failed key attempts in a minute from one address (wait 60 seconds). |
| 500 | internal |
Something failed on Alethman’s side. Retry with backoff; if it persists, write to Alethman with the time of the request. |
Good to know
Section titled “Good to know”- A probability is fixed when the forecast is made and never revised. A changed view is a new forecast.
countsandtrack_recordcover every forecast in the workspace’s sectors (or the onesectorasked for), not just the page returned.awaitingforecasts have passed their deadline and are waiting for a verdict. They move toresolvedwhen judged.- A voided forecast is
resolvedwithoutcomenull: the question could not be settled as asked. It does not count toward the Brier score.
From an AI assistant
Section titled “From an AI assistant”The MCP tool list_forecasts runs this endpoint’s code and returns the same JSON. Its default limit differs: The REST default is 100.