Skip to content

List articles

GEThttps://dash.alethman.com/api/v1/signals
MCP tool
list_signals

Articles in the workspace’s scope, newest first, each with its outlet, sectors, states and the story it was grouped into. The firehose under every other endpoint: use it to mirror coverage into your own store, or to watch a state or sector article by article. Pages with next_cursor.

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.
q query string up to 120 characters Words to find in the headline.
language query string up to 8 characters Only headlines in this language: an ISO 639-1 code such as en, hi, ta.
since query string (time) Only articles published after this time, as ISO 8601, e.g. 2026-11-21T00:00:00Z.
limit query integer 50 1 to 200 How many articles to return, 1 to 200.
cursor query string The next_cursor from the previous page. Opaque: pass it back unchanged.
Terminal window
curl "https://dash.alethman.com/api/v1/signals?sector=energy_power&since=2026-11-20T00:00:00Z&limit=50" \
-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": 138695177,
"title": "Jammu Kashmir High Court Quashes Withdrawal of NOC for Four Tourist Huts in Pahalgam",
"url": "https://kashmirlife.net/jammu-kashmir-high-court-quashes-withdrawal-of-noc-for-four-tourist-huts-in-pahalgam-462123/",
"published_at": "2026-11-21T05:01:37.000Z",
"language": null,
"outlet": {
"id": "kashmir-life",
"name": "Kashmir Life"
},
"sectors": [
"politics_governance"
],
"states": [],
"story": null
},
{
"id": 138694799,
"title": "Polling Underway Across Ladakh For Panchayat And Municipal Elections 2026",
"url": "https://www.dailyexcelsior.com/polling-underway-across-ladakh-for-panchayat-and-municipal-elections-2026/",
"published_at": "2026-11-21T05:01:23.000Z",
"language": null,
"outlet": {
"id": "daily-excelsior",
"name": "Daily Excelsior"
},
"sectors": [
"politics_governance"
],
"states": [],
"story": null
},
{
"id": 138682757,
"title": "सागर में बिजली कंपनी के स्टोर रूम में भीषण आग:10 फीट ऊंची उठीं लपटें, मीटर-उपकरण जलकर राख; 2 घंटे बाद पाया काबू",
"url": "https://www.bhaskar.com/local/mp/sagar/news/makronia-sagar-electricity-company-store-room-fire-incident-139753300.html",
"published_at": "2026-11-21T04:58:11.000Z",
"language": "hi",
"outlet": {
"id": "dainik-bhaskar",
"name": "Dainik Bhaskar"
},
"sectors": [
"energy_power"
],
"states": [],
"story": null
},
{
"id": 138626948,
"title": "Ladakh votes in panchayat and municipal polls amid bitter chill after eight-year gap",
"url": "https://www.greaterkashmir.com/ladakh/ladakh-votes-in-panchayat-and-municipal-polls-amid-bitter-chill-after-eight-year-gap-12828341",
"published_at": "2026-11-21T04:46:26.000Z",
"language": "en",
"outlet": {
"id": "greater-kashmir",
"name": "Greater Kashmir"
},
"sectors": [
"politics_governance"
],
"states": [
"ladakh"
],
"story": {
"id": 294998,
"label": "Ladakh Elections 2026: 541 candidates file their nomination papers for 100 LAHDC seats in eight districts",
"independent_outlets": 9
}
}
],
"next_cursor": "MjAyNi0xMS0yMVQwNDo0NjoyNi4wMDBafDEzODYyNjk0OA"
}
Field Type Values What it is
data array of objects Articles, newest first.
data[].id integer The article’s id. Stable.
data[].title string The headline as the outlet published it, in its own language.
data[].url string (url) The article’s address on the outlet’s site.
data[].published_at string (time) When the outlet published it (UTC).
data[].language string or null ISO 639-1 code of the headline’s language (en, hi, ta …), or null where it was not detected.
data[].outlet object Who published it.
data[].outlet.id string The outlet’s stable slug.
data[].outlet.name string The outlet’s name.
data[].sectors array of strings a sector key Sectors the article was read as touching. Can be empty.
data[].states array of strings a state slug States and union territories the article is about. Empty when it names none (national or foreign news).
data[].story object or null The story the article was grouped into, or null while it stands alone.
data[].story.id integer The story’s id; pass it to GET /stories/{id}.
data[].story.label string The story’s headline.
data[].story.independent_outlets integer How many independent outlets carry the story.
next_cursor string or null Pass as cursor for the next page. Null when this page is the last (it returned fewer than limit).

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.
  • To mirror coverage into your own store, page with cursor until next_cursor is null, then poll with since set to the newest published_at you hold.
  • next_cursor is set whenever a page comes back full. A full last page therefore gives a cursor whose next page is empty: stop on an empty data as well as on a null cursor.
  • q matches words in the headline as published, so a Hindi query finds Hindi headlines.
  • An article with no states is national or foreign news. It appears only when the workspace follows national news (scope.national on GET /workspace).

The MCP tool list_signals runs this endpoint’s code and returns the same JSON. Its default limit differs: The REST default is 50.