Skip to content

List reports

GEThttps://dash.alethman.com/api/v1/reports
MCP tool
list_reports

The workspace’s compiled reports, newest first. Page back through older ones with before, set to the created_at of the last report you have.

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.
Terminal window
curl "https://dash.alethman.com/api/v1/reports?limit=5" \
-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": "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"
}
]
}
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.

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 page back, pass the created_at of the oldest report you have as before.
  • Reports are compiled on the workspace’s schedule (reports.frequency on GET /workspace) or when someone asks for one in the dashboard.

The MCP tool list_reports runs this endpoint’s code and returns the same JSON.