Get a report
GET
https://dash.alethman.com/api/v1/reports/{id}One report, as structured JSON (the default) or as the Markdown the dashboard prints. Markdown is the one to read, file or hand to a model; JSON is the one to compute on.
Request
Section titled “Request”| Parameter | In | Type | Default | Values | What it does |
|---|---|---|---|---|---|
id required |
path | string (uuid) | The report id, from GET /reports. | ||
format |
query | string | json |
json, markdown |
json: the report with its structured content. markdown: the report as written, text/markdown. |
Example
Section titled “Example”curl "https://dash.alethman.com/api/v1/reports/d35a4dc6-3109-41cf-a2a9-b9a7850ca1d1?format=markdown" \ -H "Authorization: Bearer $ALETHMAN_KEY"import osimport requests
r = requests.get( "https://dash.alethman.com/api/v1/reports/d35a4dc6-3109-41cf-a2a9-b9a7850ca1d1", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, params={"format": "markdown"}, timeout=30,)r.raise_for_status()print(r.text)const url = new URL("https://dash.alethman.com/api/v1/reports/d35a4dc6-3109-41cf-a2a9-b9a7850ca1d1");url.search = new URLSearchParams({ format: "markdown" });
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.text());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.
{ "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", "content": { "version": 1, "title": "Weekly report, 10 Nov to 17 Nov 2026", "org": "Risk desk", "period": { "end": "2026-11-17T03:42:23.800Z", "hours": 168, "start": "2026-11-10T03:42:23.800Z" }, "data_through": "2026-11-17T03:41:59.024Z", "generated_at": "2026-11-17T03:42:23.839Z", "judgements": [ { "flag": true, "link": "/sectors/crime_law_enforcement", "text": "Crime and law enforcement reads severe at 80, up 5 from the reading before. Risk is rising on multiple fronts." } ], "memo": { "has": { "stories": true, "readings": true, "coordination": true }, "moves": [ { "href": "/sectors/infrastructure_transport", "name": "Infrastructure and transport", "delta": 18, "score": 58, "sector": "infrastructure_transport", "previous": 40 }, { "href": "/sectors/real_estate_construction", "name": "Real estate and construction", "delta": 8, "score": 17, "sector": "real_estate_construction", "previous": 9 } ] } }}# Weekly report, 10 Nov to 17 Nov 2026
Risk desk. Period 10 Nov to 17 Nov 2026 (IST). Compiled 17 Nov 2026, 09:12 IST from Alethman's standing readings.
Sectors: Textiles and apparel, Metals and mining, Trade, imports and exports, Agriculture and food, Energy and power, Infrastructure and transport, Manufacturing and industry, IT, telecom and technology, Pharma and health, Banking, finance and markets, Real estate and construction, Public order and unrest, Insurgency and terrorism, Crime and law enforcement, Defence, borders and foreign relations, Politics and governance, Environment and disasters, Labour, employment and education, Media and the information space. States: all of India, with national coverage.
## Memo summary
**What changed most** (sector readings against the reading before):- Infrastructure and transport: 40 to 58, up 18- Real estate and construction: 9 to 17, up 8- Manufacturing and industry: 15 to 22, up 7
…Fields
Section titled “Fields”| Field | Type | Values | What it is |
|---|---|---|---|
id |
string (uuid) | The report’s id. | |
title |
string | The report’s title. | |
trigger |
string | scheduled, on_demand |
scheduled (the workspace’s report schedule) or on_demand (someone asked for it). |
period_start |
string (time) | Start of the period it covers. | |
period_end |
string (time) | End of the period it covers. | |
created_at |
string (time) | When it was compiled. | |
content |
object | The report’s structured content, as the dashboard renders it. It carries version (the content format; fields are added within a version, never renamed), title, org, period, data_through, generated_at, and one key per section the workspace’s reports include: judgements, memo, outlooks, stories, states, forecasts, coordination, sources, products, settings. For a report to read, ask for format=markdown. |
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. |
| 404 | not_found |
No report with that id in this workspace. Message: “No report with that id in this workspace.” |
| 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”format=markdownanswerstext/markdown; charset=utf-8, not JSON; errors are still JSON.content.versionis the content format. Fields are added within a version and never renamed or removed.- Which sections
contentcarries follows the workspace’s report settings, so check for a key before reading it.
From an AI assistant
Section titled “From an AI assistant”The MCP tool get_report runs this endpoint’s code and returns the same JSON, with Markdown as its default format.