List reports
GET
https://dash.alethman.com/api/v1/reportsThe workspace’s compiled reports, newest first. Page back through older ones with before, set to the created_at of the last report you have.
Request
Section titled “Request”| Parameter | In | Type | Default | Values | What it does |
|---|---|---|---|---|---|
limit |
query | integer | 20 |
1 to 100 | How many reports to return, 1 to 100. |
before |
query | string (time) | Only reports compiled before this time, as ISO 8601. |
Example
Section titled “Example”curl "https://dash.alethman.com/api/v1/reports?limit=5" \ -H "Authorization: Bearer $ALETHMAN_KEY"import osimport requests
r = requests.get( "https://dash.alethman.com/api/v1/reports", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, params={"limit": 5}, timeout=30,)r.raise_for_status()print(r.json())const url = new URL("https://dash.alethman.com/api/v1/reports");url.search = new URLSearchParams({ limit: "5" });
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": "d35a4dc6-3109-41cf-a2a9-b9a7850ca1d1", "title": "Weekly report, 10 Nov to 17 Nov 2026", "trigger": "scheduled", "period_start": "2026-11-10T03:42:23.800Z", "period_end": "2026-11-17T03:42:23.800Z", "created_at": "2026-11-17T03:42:28.840Z" }, { "id": "e64e8f99-0464-4bf3-a423-189e4041b0ef", "title": "Weekly report, 2 Nov to 9 Nov 2026", "trigger": "scheduled", "period_start": "2026-11-02T03:30:22.932Z", "period_end": "2026-11-09T03:30:22.932Z", "created_at": "2026-11-09T03:30:37.749Z" }, { "id": "bde58b9c-86ae-4e1b-87e1-5a0b204eedf3", "title": "Weekly report, 19 Oct to 26 Oct 2026", "trigger": "scheduled", "period_start": "2026-10-19T03:30:14.125Z", "period_end": "2026-10-26T03:30:14.125Z", "created_at": "2026-10-26T03:30:18.907Z" } ]}Fields
Section titled “Fields”| Field | Type | Values | What it is |
|---|---|---|---|
data |
array of objects | Reports, newest first. | |
data[].id |
string (uuid) | The report’s id. | |
data[].title |
string | The report’s title. | |
data[].trigger |
string | scheduled, on_demand |
scheduled (the workspace’s report schedule) or on_demand (someone asked for it). |
data[].period_start |
string (time) | Start of the period it covers. | |
data[].period_end |
string (time) | End of the period it covers. | |
data[].created_at |
string (time) | When it was compiled. |
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 page back, pass the
created_atof the oldest report you have asbefore. - Reports are compiled on the workspace’s schedule (
reports.frequencyon GET /workspace) or when someone asks for one in the dashboard.
From an AI assistant
Section titled “From an AI assistant”The MCP tool list_reports runs this endpoint’s code and returns the same JSON.