Skip to content

List stories

GEThttps://dash.alethman.com/api/v1/stories
MCP tool
list_stories

Stories in scope: articles about one event, grouped, with how many independent outlets carry each, where it is, its risk and a one-line reading. The unit most work starts from.

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.
state query string a state slug Only this state or union territory.
hours query integer 72 1 to 720 How far back to look, in hours, 1 to 720 (30 days). A story counts when its latest article falls inside the window.
order query string voices voices, risk, recent voices: most independent outlets first. risk: highest risk first. recent: newest activity first.
limit query integer 20 1 to 100 How many stories to return, 1 to 100.
Terminal window
curl "https://dash.alethman.com/api/v1/stories?state=manipur&order=risk&limit=10" \
-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
{
"data": [
{
"id": 301791,
"label": "Manipur Spurious Liquor Tragedy: Death Toll Rises To 11, Over 180 Hospitalised",
"independent_outlets": 24,
"articles": 41,
"trajectory": "steady",
"first_seen": "2026-11-19T13:45:01.000Z",
"last_seen": "2026-11-21T04:27:58.000Z",
"sectors": [
"public_order_unrest",
"agriculture_food"
],
"states": [
"manipur"
],
"place": "Chandel",
"risk_score": 72,
"risk_level": "high",
"reading": "Suspected methanol-laced local liquor in Chandel district, Manipur, has killed at least 11 to 15 people and hospitalised more than 150.",
"event_type": "disaster_accident"
},
{
"id": 297641,
"label": "EPFO approves systematic PF withdrawal plan",
"independent_outlets": 35,
"articles": 89,
"trajectory": "steady",
"first_seen": "2026-11-18T22:24:07.000Z",
"last_seen": "2026-11-21T03:51:15.000Z",
"sectors": [
"banking_finance_markets",
"politics_governance"
],
"states": [
"delhi"
],
"place": "Delhi",
"risk_score": 12,
"risk_level": "low",
"reading": "The EPFO board approved reforms easing PF withdrawals, including a systematic withdrawal plan, lower minimum balance and limited alternative fund investment.",
"event_type": "policy_decision"
},
{
"id": 302282,
"label": "Supreme Court dismisses Tamil Nadu pleas seeking 11 TMC of Cauvery water from Karnataka",
"independent_outlets": 29,
"articles": 42,
"trajectory": "steady",
"first_seen": "2026-11-19T19:23:01.000Z",
"last_seen": "2026-11-21T01:27:48.000Z",
"sectors": [
"agriculture_food",
"public_order_unrest",
"politics_governance"
],
"states": [
"tamil-nadu",
"karnataka"
],
"place": "Tamil Nadu",
"risk_score": 35,
"risk_level": "guarded",
"reading": "Supreme Court dismissed Tamil Nadu's applications seeking extra Cauvery water from Karnataka for the 2026-27 irrigation year.",
"event_type": "court_ruling"
},
{
"id": 295701,
"label": "Massive fire engulfs Pune’s Timber Market; over 50 shops gutted",
"independent_outlets": 13,
"articles": 26,
"trajectory": "decaying",
"first_seen": "2026-11-18T01:18:12.000Z",
"last_seen": "2026-11-20T03:26:20.000Z",
"sectors": [
"public_order_unrest",
"crime_law_enforcement"
],
"states": [
"maharashtra"
],
"place": "Pune",
"risk_score": 25,
"risk_level": "guarded",
"reading": "A late-night fire gutted dozens of timber and plywood shops and six houses at Pune's Timber Market in Bhavani Peth; no injuries were reported.",
"event_type": "crime"
}
]
}
Field Type Values What it is
data array of objects Stories in the order asked for.
data[].id integer The story’s id. Stable: when two stories merge, the old id still answers on GET /stories/{id}.
data[].label string A headline for the story, from its most representative article.
data[].independent_outlets integer Outlets carrying the story independently: syndicated wire copy and copy credited to a news agency count once.
data[].articles integer Every article in the story, syndicated copies included.
data[].trajectory string or null new, rising, steady, decaying Where coverage is heading: new, rising, steady or decaying.
data[].first_seen string (time) The first article’s publication time.
data[].last_seen string (time) The latest article’s publication time.
data[].sectors array of strings a sector key Sectors the story touches.
data[].states array of strings a state slug States and union territories the story is about.
data[].place string or null The story’s main place (a city, district or state), or 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[].reading string or null One sentence: what happened, in plain English whatever the articles’ language.
data[].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.

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.
  • A story counts toward the window by its latest article, so a long-running story that moved today is included even if it began weeks ago.
  • independent_outlets is the number to sort and threshold on: it counts syndicated wire copy once, where articles counts every copy.
  • This list does not page. Narrow it with sector, state and hours, or raise limit to 100.

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