List articles
GET
https://dash.alethman.com/api/v1/signalsArticles 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.
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. | |
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. |
Example
Section titled “Example”curl "https://dash.alethman.com/api/v1/signals?sector=energy_power&since=2026-11-20T00:00:00Z&limit=50" \ -H "Authorization: Bearer $ALETHMAN_KEY"import osimport requests
r = requests.get( "https://dash.alethman.com/api/v1/signals", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, params={"sector": "energy_power", "since": "2026-11-20T00:00:00Z", "limit": 50}, timeout=30,)r.raise_for_status()print(r.json())const url = new URL("https://dash.alethman.com/api/v1/signals");url.search = new URLSearchParams({ sector: "energy_power", since: "2026-11-20T00:00:00Z", limit: "50" });
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": 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"}Fields
Section titled “Fields”| 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). |
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”- To mirror coverage into your own store, page with
cursoruntilnext_cursoris null, then poll withsinceset to the newestpublished_atyou hold. next_cursoris set whenever a page comes back full. A full last page therefore gives a cursor whose next page is empty: stop on an emptydataas well as on a null cursor.qmatches 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.nationalon GET /workspace).
From an AI assistant
Section titled “From an AI assistant”The MCP tool list_signals runs this endpoint’s code and returns the same JSON. Its default limit differs: The REST default is 50.