Skip to content

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

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_cursor is null when a page comes back short (fewer rows than limit): 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 data as 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 os
import 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"])

To keep your own copy of the articles:

  1. Backfill once: page with cursor until it runs out (add since to bound how far back).
  2. Poll every few minutes with since set to the newest published_at you hold. New articles arrive newest first; page with cursor if more than one page came in.
  3. Upsert by id. An article’s story can 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.