Pagination
Lists come back newest first. How you get the next page depends on the list:
| Endpoint | How it pages | Page size |
|---|---|---|
GET /signals |
cursor, from the next_cursor of the page before |
limit 1 to 200, default 50 |
GET /reports |
before, the created_at of the oldest report you have |
limit 1 to 100, default 20 |
GET /sources/items |
since, a time; no cursor |
limit 1 to 200, default 50 |
GET /stories |
does not page; narrow with hours, sector, state |
limit 1 to 100, default 20 |
GET /forecasts |
does not page; filter with status, sector |
limit 1 to 200, default 100 |
GET /coordination |
does not page | limit 1 to 60, default 30 |
GET /outlooks, GET /sources |
one short list, whole | all of it |
Cursors
Section titled “Cursors”GET /signals returns a next_cursor beside data. Pass it back unchanged as cursor with the same filters to get the next page:
{ "data": [ … 50 articles … ], "next_cursor": "MjAyNi0xMS0yMVQwNDo0NjoyNi4wMDBafDEzODYyNjk0OA"}next_cursoris null when a page comes back short (fewer rows thanlimit): there is nothing more.- A page that comes back exactly full always carries a cursor, even if nothing follows; the next page is then empty. Stop on an empty
dataas well as on a null cursor. - A cursor is opaque. Do not build or edit one; a cursor the API did not give answers
400 bad_request(“cursor is not valid. Use the next_cursor from a previous page.”). - A cursor points at a place in time, not a page number, so articles published while you page never shift what you see or make you read one twice. Cursors do not expire.
- Keep the other parameters the same from page to page. A cursor with different filters still works, but walks the new filters from that point.
import osimport requests
API = "https://dash.alethman.com/api/v1"s = requests.Session()s.headers["Authorization"] = f"Bearer {os.environ['ALETHMAN_KEY']}"
def every_article(**filters): params = {"limit": 200, **filters} while True: r = s.get(f"{API}/signals", params=params, timeout=30) r.raise_for_status() page = r.json() yield from page["data"] if not page["data"] or not page["next_cursor"]: return params["cursor"] = page["next_cursor"]
for a in every_article(sector="energy_power", since="2026-11-14T00:00:00Z"): print(a["id"], a["title"])const API = "https://dash.alethman.com/api/v1";const headers = { Authorization: `Bearer ${process.env.ALETHMAN_KEY}` };
async function* everyArticle(filters = {}) { let cursor = null; do { const url = new URL(`${API}/signals`); url.search = new URLSearchParams({ limit: "200", ...filters, ...(cursor ? { cursor } : {}) }); const res = await fetch(url, { headers }); if (!res.ok) throw new Error((await res.json()).error.message); const page = await res.json(); yield* page.data; cursor = page.data.length ? page.next_cursor : null; } while (cursor);}
for await (const a of everyArticle({ sector: "energy_power", since: "2026-11-14T00:00:00Z" })) console.log(a.id, a.title);Keeping a mirror in sync
Section titled “Keeping a mirror in sync”To keep your own copy of the articles:
- Backfill once: page with
cursoruntil it runs out (addsinceto bound how far back). - Poll every few minutes with
sinceset to the newestpublished_atyou hold. New articles arrive newest first; page withcursorif more than one page came in. - Upsert by
id. An article’sstorycan change after you first see it (it joins a story, or two stories merge), so update rows you already hold rather than skipping them.
Every time is ISO 8601 in UTC (2026-11-21T04:46:26.000Z). Parameters that take a time (since, before) accept any ISO 8601 form, with or without milliseconds or an offset: 2026-11-21T10:00:00+05:30 is the same instant as 2026-11-21T04:30:00Z.