Skip to content

Get a story

GEThttps://dash.alethman.com/api/v1/stories/{id}
MCP tool
get_story

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.

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.
Terminal window
curl "https://dash.alethman.com/api/v1/stories/297641" \
-H "Authorization: Bearer $ALETHMAN_KEY"

200 OK, application/json, with the rate-limit headers. A real response, shortened: long lists are cut to a few items.

200 OK
{
"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": []
}
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.

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.
  • 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, not requested_id, from then on.
  • tag and bloc_finding are null while a new story is still being read; they fill in within the hour.
  • named_by_reporting records who the reporting names and how it attributes them. It is never Alethman’s own finding about a party.

The MCP tool get_story runs this endpoint’s code and returns the same JSON.