List stories
GET
https://dash.alethman.com/api/v1/storiesStories 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.
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. | |
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. |
Example
Section titled “Example”curl "https://dash.alethman.com/api/v1/stories?state=manipur&order=risk&limit=10" \ -H "Authorization: Bearer $ALETHMAN_KEY"import osimport requests
r = requests.get( "https://dash.alethman.com/api/v1/stories", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, params={"state": "manipur", "order": "risk", "limit": 10}, timeout=30,)r.raise_for_status()print(r.json())const url = new URL("https://dash.alethman.com/api/v1/stories");url.search = new URLSearchParams({ state: "manipur", order: "risk", limit: "10" });
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": 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" } ]}Fields
Section titled “Fields”| 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. |
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 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_outletsis the number to sort and threshold on: it counts syndicated wire copy once, wherearticlescounts every copy.- This list does not page. Narrow it with
sector,stateandhours, or raiselimitto 100.
From an AI assistant
Section titled “From an AI assistant”The MCP tool list_stories runs this endpoint’s code and returns the same JSON.