List sector outlooks
GET
https://dash.alethman.com/api/v1/outlooksThe latest reading for each sector the workspace follows: a risk score and level, the direction against the reading before, a verdict, and the stories driving it. One row per sector, in the workspace’s sector order. Readings refresh several times a day.
Request
Section titled “Request”This endpoint takes no parameters.
Example
Section titled “Example”curl "https://dash.alethman.com/api/v1/outlooks" \ -H "Authorization: Bearer $ALETHMAN_KEY"import osimport requests
r = requests.get( "https://dash.alethman.com/api/v1/outlooks", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, timeout=30,)r.raise_for_status()print(r.json())const url = "https://dash.alethman.com/api/v1/outlooks";
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": [ { "sector": "energy_power", "name": "Energy and power", "quiet": false, "risk_score": 48, "risk_level": "elevated", "previous_score": 61, "direction": "easing", "verdict": "No new Hormuz attack or Tarali ruling emerged in the last 24 hours; the Petroleum Minister again said India can manage oil and gas supply even if West Asia tensions worsen, while the IEA warned of a major Hormuz-linked supply shock and flagged India as the engine of future demand growth. Haryana's Appellate Tribunal kept Eleven Power's Gurugram-Nuh distribution licence suspended, and Karnataka pressed the Centre again on E20 ethanol testing. Coal, power and core-sector output data were strong and crude prices eased, suggesting near-term supply stress is being managed rather than escalating. Watch Hormuz shipping risk and the Gurugram-Nuh licence fight for the next flashpoint.", "drivers": [ { "story_id": 300584, "label": "How Hormuz oil shock is India's chance to reset its energy future", "why": "IEA flags Hormuz disruption as a major supply shock with India central to demand growth" }, { "story_id": 295835, "label": "Karnataka Flags Excess Ethanol in Petrol Samples, Urges Centre to Review E20 Policy", "why": "Karnataka's renewed E20 challenge keeps fuel-policy friction with the Centre alive" }, { "story_id": 295865, "label": "No immediate relief to Eleven Power in APTEL on parallel-distribution licence", "why": "Tribunal's refusal to Eleven Power prolongs Haryana distribution licence dispute" } ], "stories_read": 18, "open_forecasts": 35, "generated_at": "2026-11-20T22:29:38.066Z" }, { "sector": "public_order_unrest", "name": "Public order and unrest", "quiet": false, "risk_score": 80, "risk_level": "severe", "previous_score": 76, "direction": "rising", "verdict": "Cyclone Akvan is making landfall near Narsapur-Puri in Odisha, with tens of thousands evacuated, trains cancelled and schools shut. Manipur faces compounding shocks: methanol liquor deaths in Chandel have climbed to 11-15 with over 150 hospitalised, while security forces killed a KCP militant and arrested eight in Imphal West. Bangladesh's Awami League supporters torched police vehicles and a station in Gopalganj, adding border-adjacent risk. Political violence persists in Andhra Pradesh's Pulivendula and Kolkata's TMC-BJP clashes continue after a TMC MP's police questioning. Watch cyclone casualty figures, Manipur's liquor-death fallout, and reaction to the Thiruparankundram lamp lighting.", "drivers": [ { "story_id": 299819, "label": "ओडिशा में चक्रवात 'अकवान' का खतरा, अब तक 72 हजार लोगों को सुरक्षित स्थानों पर पहुंचाया गया", "why": "Cyclone landfall near Narsapur-Puri forces mass evacuations and shutdowns" }, { "story_id": 301791, "label": "Manipur Spurious Liquor Tragedy: Death Toll Rises To 11, Over 180 Hospitalised", "why": "Methanol liquor deaths in Chandel climb past 11, over 150 hospitalised" }, { "story_id": 302765, "label": "Manipur: Militant killed, several others arrested after encounter in Imphal West", "why": "Security forces kill KCP militant, arrest eight in Imphal West" } ], "stories_read": 30, "open_forecasts": 25, "generated_at": "2026-11-21T04:51:50.457Z" } ]}Fields
Section titled “Fields”| Field | Type | Values | What it is |
|---|---|---|---|
data |
array of objects | One reading per followed sector. | |
data[].sector |
string | a sector key | A sector key. See Countries and scopes for the list. |
data[].name |
string | The sector’s name. | |
data[].quiet |
boolean | True when the sector had too little reporting in its window to read: the score, level, direction and verdict are then null. | |
data[].risk_score |
integer or null | 0 to 100: how much disruption the reporting describes, read by Alethman. Higher is more severe. Comparable across sectors and over time. | |
data[].risk_level |
string or null | low, guarded, elevated, high, severe |
The band the score falls in: low, guarded, elevated, high or severe. Use it as the headline; band edges are not published and may be tuned. |
data[].previous_score |
integer or null | The score of the reading before this one, or null for a first reading. | |
data[].direction |
string or null | rising, steady, easing, new |
How this reading compares with the one before: rising, steady, easing, or new for a first reading. |
data[].verdict |
string or null | A short paragraph: what is driving the sector now and what to watch. | |
data[].drivers |
array of objects | The stories driving the reading, most important first. | |
data[].drivers[].story_id |
integer | A story id; pass it to GET /stories/{id}. | |
data[].drivers[].label |
string | The story’s headline. | |
data[].drivers[].why |
string | One line: why this story moves the sector. | |
data[].stories_read |
integer | How many stories the reading weighed. | |
data[].open_forecasts |
integer | Open forecasts in this sector. | |
data[].generated_at |
string (time) or null | When the reading was made. |
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 |
|---|---|---|
| 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
quietsector had too little reporting in its window to read; its score, level, direction and verdict are null. That is a finding (nothing moved), not an error. - Compare
risk_scorewithprevious_scorefor the size of a move;directionis the word for it. - Readings refresh several times a day. Polling more than once an hour gains nothing.
From an AI assistant
Section titled “From an AI assistant”The MCP tool list_outlooks runs this endpoint’s code and returns the same JSON.