Get a story
GET
https://dash.alethman.com/api/v1/stories/{id}One story in full: how Alethman read it (sectors, event type, risk and what it rests on, the parties the reporting names), a summary, its places and every article, how coverage divides, the coverage by country, and the forecasts made about it. A story outside the workspace’s sectors and states answers 404, as if it did not exist. When two stories merge, the old id still answers with the merged story; compare id with requested_id.
Request
Section titled “Request”| Parameter | In | Type | Default | Values | What it does |
|---|---|---|---|---|---|
id required |
path | string | up to 12 digits | The story id, from GET /stories, a signal’s story.id, an outlook driver or a coordination finding. A whole number of up to 12 digits. |
Example
Section titled “Example”curl "https://dash.alethman.com/api/v1/stories/297641" \ -H "Authorization: Bearer $ALETHMAN_KEY"import osimport requests
r = requests.get( "https://dash.alethman.com/api/v1/stories/297641", 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/stories/297641";
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.
{ "id": 297641, "requested_id": 297641, "label": "EPFO approves systematic PF withdrawal plan", "proposition": "The EPFO's systematic withdrawal plan will benefit retiring provident fund members.", "independent_outlets": 35, "articles_count": 89, "trajectory": "steady", "first_seen": "2026-11-18T22:24:07.000Z", "last_seen": "2026-11-21T03:51:15.000Z", "tag": { "sectors": [ "banking_finance_markets", "politics_governance" ], "event_type": "policy_decision", "theme": "epfo-provident-fund-withdrawal-reforms", "risk_score": 12, "risk_level": "low", "risk_basis": "A routine approval of pension-fund withdrawal flexibility and investment rules by the EPFO board, with no disruption or market shock described.", "reading": "The EPFO board approved reforms easing PF withdrawals, including a systematic withdrawal plan, lower minimum balance and limited alternative fund investment.", "coordinated": false, "coordination_basis": null, "named_by_reporting": [ { "kind": "state_agency", "name": "Employees' Provident Fund Organisation", "role": "responder", "article_ids": [ 132167016, 131536578, 131475996 ], "attribution": "official_statement" } ] }, "summary": "The EPFO's Central Board of Trustees met in New Delhi on 19 November 2026 and approved a Systematic Withdrawal Plan letting retiring members draw their provident fund savings in monthly, quarterly or annual instalments while the remainder keeps earning EPF interest. The board also cut the minimum balance to be retained during partial withdrawals from 25% to 10% and restored a two-month wait for final settlement after job loss, down from 12 months; it did not raise the EPS pension. These changes take effect only after formal notification. Nobody disputes the decisions. Where outlets differ is in emphasis: The Times of India, DNA India, Prameya News and The Economic Times present the plan as a clear gain in retirement income and security, while Hindustan Times, India Today, Business Today and others focus on the larger share of savings members can now withdraw. No report so far says when the rules will be notified, and none carries criticism of the plan.", "places": [ { "name": "Delhi", "kind": "city", "state": "delhi", "primary": true }, { "name": "Mumbai", "kind": "city", "state": "maharashtra", "primary": false }, { "name": "Guwahati", "kind": "city", "state": "assam", "primary": false } ], "articles": [ { "id": 135003766, "title": "Explained | Major overhaul of PF withdrawals", "url": "https://www.deccanherald.com/india/explained-major-overhaul-of-pf-withdrawals-4225245", "outlet": "Deccan Herald", "published_at": "2026-11-20T09:39:06.000Z", "language": "en", "wire": "PTI" }, { "id": 133556770, "title": "EPFO approves systematic PF withdrawal plan, cuts minimum balance requirement to 10%", "url": "https://www.greaterkashmir.com/business/epfo-approves-systematic-pf-withdrawal-plan-cuts-minimum-balance-requirement-to-10-12825076", "outlet": "Greater Kashmir", "published_at": "2026-11-20T02:25:40.000Z", "language": "en", "wire": "PTI" }, { "id": 133480577, "title": "EPFO approves periodic PF payouts for retirees, eases withdrawal norms", "url": "https://www.hindustantimes.com/india-news/epfo-approves-periodic-pf-payouts-for-retirees-eases-withdrawal-norms-101795138227494.html", "outlet": "Hindustan Times", "published_at": "2026-11-20T01:44:24.000Z", "language": "en", "wire": null } ], "bloc_finding": { "statement": "Coverage does not split. 8 independent outlets (DNA India, Mathrubhumi, Mint, Odisha Bytes, Prameya News, The Economic Times, The Indian Express, The Times of India) support the proposition \"The EPFO's systematic withdrawal plan will benefit retiring provident fund members.\" and frame it as Steady retirement income.", "evidence_grade": "D", "coordination_likelihood": "low", "what_would_change": "three or more independent outlets carrying the opposing frame would make this a split." }, "by_country": [ { "country": "IND", "articles": 89, "voices": 35, "supports": 10, "opposes": 0, "neutral": 8, "labelled": 24, "frame": "Easier access to PF savings" } ], "forecasts": []}Fields
Section titled “Fields”| Field | Type | Values | What it is |
|---|---|---|---|
id |
integer | The story’s current id. Differs from requested_id when the story you asked for was merged into this one. | |
requested_id |
integer | The id you asked for. | |
label |
string | The story’s headline. | |
proposition |
string or null | The claim at the centre of the coverage, as one sentence outlets can agree or disagree with. | |
independent_outlets |
integer | Independent outlets carrying it. | |
articles_count |
integer | Every article in it. | |
trajectory |
string or null | new, rising, steady, decaying |
Where coverage is heading: new, rising, steady or decaying. |
first_seen |
string (time) | The first article’s time. | |
last_seen |
string (time) | The latest article’s time. | |
tag |
object or null | How Alethman read the story, or null before it is read. | |
tag.sectors |
array of strings | a sector key | Sectors it touches. |
tag.event_type |
string or null | protest, strike_bandh, violence_attack, security_operation, policy_decision, court_ruling, election_politics, economic_indicator, corporate_move, trade_action, disaster_accident, crime, diplomatic, other |
What kind of event the story is. |
tag.theme |
string or null | A slug for its theme. | |
tag.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. | |
tag.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. |
tag.risk_basis |
string or null | One sentence: what in the reporting the risk reading rests on. | |
tag.reading |
string or null | One sentence: what happened. | |
tag.coordinated |
boolean | True when the story is part of a coordination finding. | |
tag.coordination_basis |
string or null | Why, when coordinated is true; else null. | |
tag.named_by_reporting |
array of objects | The parties the reporting names, each with its role and how it is attributed. | |
tag.named_by_reporting[].kind |
string | What the party is (as Party.kind). | |
tag.named_by_reporting[].name |
string | The party’s name. | |
tag.named_by_reporting[].role |
string | Its role (as Party.role). | |
tag.named_by_reporting[].article_ids |
array of integers | The articles that name it so. | |
tag.named_by_reporting[].attribution |
string | official_statement, claim_by_actor, reported, alleged_by_opponent, speculation |
How the reporting attributes the role, strongest first: official_statement, claim_by_actor (the party’s own claim), reported (plain reporting), alleged_by_opponent, speculation. |
summary |
string or null | A paragraph: what happened, where outlets agree and where they differ. | |
places |
array of objects | Places the story names. | |
places[].name |
string | The place’s name. | |
places[].kind |
string | city, district, state and so on. |
|
places[].state |
string or null | The state it is in. | |
places[].primary |
boolean | True for the story’s main place. | |
articles |
array of objects | Every article in the story, newest first. | |
articles[].id |
integer | The article’s id. | |
articles[].title |
string | Its headline. | |
articles[].url |
string (url) | Its address. | |
articles[].outlet |
string | The outlet’s name. | |
articles[].published_at |
string (time) | When it was published. | |
articles[].language |
string or null | Its language. | |
articles[].wire |
string or null | The news agency it credits (PTI, ANI, Reuters …), or null for the outlet’s own reporting. | |
bloc_finding |
object or null | How coverage of the proposition divides, or null when not yet read. | |
bloc_finding.statement |
string | Whether coverage splits into camps, and how. | |
bloc_finding.evidence_grade |
string | A, B, C, D |
A to D, strongest first: how clearly coverage splits. D: no split. |
bloc_finding.coordination_likelihood |
string | low, moderate, elevated |
low, moderate or elevated: how far the split looks organised rather than ordinary disagreement. |
bloc_finding.what_would_change |
string | What new coverage would change the finding. | |
by_country |
array of objects | The coverage by the home country of its outlets. | |
by_country[].country |
string | ISO 3166-1 alpha-3 code of the outlets’ home country. | |
by_country[].articles |
integer | Articles from that country’s outlets. | |
by_country[].voices |
integer | Independent outlets from that country. | |
by_country[].supports |
integer | Of those read for stance: outlets that support the proposition. | |
by_country[].opposes |
integer | Outlets that oppose it. | |
by_country[].neutral |
integer | Outlets that report it without a side. | |
by_country[].labelled |
integer | Articles read for stance. | |
by_country[].frame |
string or null | How that country’s outlets frame the story, in a few words. | |
forecasts |
array of objects | Forecasts made about this story. | |
forecasts[].id |
integer | The forecast’s id. | |
forecasts[].sector |
string | a sector key | A sector key. See Countries and scopes for the list. |
forecasts[].question |
string | A yes-or-no question with a date in it. | |
forecasts[].probability |
number | 0 to 1 | The probability of yes when the forecast was made, 0 to 1. It is never revised. |
forecasts[].made_at |
string (time) | When the forecast was made. | |
forecasts[].resolves_by |
string (time) | The deadline. | |
forecasts[].resolution_rule |
string | What counts as yes, written before the outcome was known. | |
forecasts[].status |
string | open, awaiting, resolved |
open: the deadline is ahead. awaiting: the deadline has passed and no verdict is in yet. resolved: judged. |
forecasts[].resolved_at |
string (time) or null | When it was judged, or null. | |
forecasts[].outcome |
boolean or null | True if it came true, false if not; null until resolved, or when a resolved forecast was voided. | |
forecasts[].verdict |
string or null | The judgement in a sentence, with what it rests on, or null. | |
forecasts[].rationale |
string | Why the probability was set where it was, written when it 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. |
| 404 | not_found |
No story with that id, an id that is not a whole number of up to 12 digits, or a story outside the workspace’s sectors and states. Message: “No story with that id.” |
| 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 story outside the workspace’s sectors and states answers 404, exactly like one that does not exist, so ids never leak another workspace’s scope.
- When two stories are merged, the old id keeps answering with the merged story. Store
id, notrequested_id, from then on. tagandbloc_findingare null while a new story is still being read; they fill in within the hour.named_by_reportingrecords who the reporting names and how it attributes them. It is never Alethman’s own finding about a party.
From an AI assistant
Section titled “From an AI assistant”The MCP tool get_story runs this endpoint’s code and returns the same JSON.