List coordination findings
GET
https://dash.alethman.com/api/v1/coordinationCoordination findings touching the workspace’s scope (Veritos’s campaign view): stories the reporting links into one pattern, each naming who the reporting says runs it, the outlets carrying it hardest and its target, with an evidence grade. limit is applied before grade, so grade=A&limit=10 returns the A findings among the latest ten, which may be none.
Request
Section titled “Request”| Parameter | In | Type | Default | Values | What it does |
|---|---|---|---|---|---|
grade |
query | string | A, B, C |
Only findings of this evidence grade. | |
limit |
query | integer | 30 |
1 to 60 | How many findings to read (before the grade filter) to return, 1 to 60. |
Example
Section titled “Example”curl "https://dash.alethman.com/api/v1/coordination?limit=10" \ -H "Authorization: Bearer $ALETHMAN_KEY"import osimport requests
r = requests.get( "https://dash.alethman.com/api/v1/coordination", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, params={"limit": 10}, timeout=30,)r.raise_for_status()print(r.json())const url = new URL("https://dash.alethman.com/api/v1/coordination");url.search = new URLSearchParams({ limit: "10" });
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": 1582, "label": "Idbi bank privatisation fairfax sale strike in Delhi", "pattern": "same_actor", "theme": "idbi-bank-privatisation-fairfax-sale-strike", "grade": "C", "verdict": "Organised by United Forum of IDBI Officers and Employees. Aimed at Government of India. Pushed hardest by Asianet Newsable, Daily Excelsior and Dainik Jagran.", "orchestrator": { "kind": "union", "name": "United Forum of IDBI Officers and Employees", "role": "organiser", "stories": 2, "attribution": "claim_by_actor" }, "orchestrator_allies": [], "mediums": [ { "outlet": "Asianet Newsable", "articles": 1, "stories": 1, "share": 0.083, "lift": null }, { "outlet": "Daily Excelsior", "articles": 1, "stories": 1, "share": 0.083, "lift": null }, { "outlet": "Dainik Jagran", "articles": 1, "stories": 1, "share": 0.083, "lift": null } ], "target": { "kind": "state_agency", "name": "Government of India", "role": "target", "stories": 2, "attribution": "claim_by_actor" }, "statement": "Organised by United Forum of IDBI Officers and Employees. Aimed at Government of India. Pushed hardest by Asianet Newsable, Daily Excelsior and Dainik Jagran. 2 stories in 1 place, 18 Nov to 20 Nov, 10 independent outlets. United Forum of IDBI Officers and Employees: organiser in 2 of 2 (the actor's own claim); Government of India: target in 2 of 2 (the actor's own claim). Grade C.", "what_would_change": "a second place would make this a multi-site pattern; a third story would raise the grade; a wire or press-release origin for the shared reporting would lower it; actor and theme labels are model readings of the text; a hand check of the articles confirms or overturns the link.", "sectors": [ "banking_finance_markets", "public_order_unrest" ], "states": [ "delhi" ], "story_ids": [ 300502, 298063 ], "independent_outlets": 10, "first_seen": "2026-11-18T10:18:00.000Z", "last_seen": "2026-11-19T22:30:58.000Z", "attributed_by_reporting": [ { "name": "United Forum of IDBI Officers and Employees", "kind": "union", "roles": [ "organiser" ], "carried_as": "claim_by_actor" }, { "name": "Government of India", "kind": "state_agency", "roles": [ "target" ], "carried_as": "claim_by_actor" }, { "name": "All India IDBI Officers Association", "kind": "union", "roles": [ "organiser" ], "carried_as": "claim_by_actor" }, { "name": "All India Industrial Development Bank Employees Association", "kind": "union", "roles": [ "organiser" ], "carried_as": "claim_by_actor" } ] }, { "id": 1604, "label": "Sugarcane procurement price dispute in Haryana", "pattern": "called_action", "theme": "sugarcane-procurement-price-dispute", "grade": "C", "verdict": "Organised by Bharatiya Kisan Union (Doaba). Pushed hardest by The Tribune and Hindustan Times.", "orchestrator": { "kind": "organisation", "name": "Bharatiya Kisan Union (Doaba)", "role": "organiser", "stories": 1, "attribution": "reported" }, "orchestrator_allies": [], "mediums": [ { "outlet": "The Tribune", "articles": 4, "stories": 1, "share": 0.5, "lift": null }, { "outlet": "Hindustan Times", "articles": 2, "stories": 1, "share": 0.25, "lift": null } ], "target": null, "statement": "Organised by Bharatiya Kisan Union (Doaba). Pushed hardest by The Tribune and Hindustan Times. 1 story in 1 place, 18 Nov to 21 Nov, 4 independent outlets. Bharatiya Kisan Union (Doaba): organiser in 1 of 1 (plain reporting). Grade C.", "what_would_change": "an official statement or the actor's own claim carried by two or more outlets would raise the grade; a second place would make this a multi-site pattern; a third story would raise the grade; a wire or press-release origin for the shared reporting would lower it; actor and theme labels are model readings of the text; a hand check of the articles confirms or overturns the link.", "sectors": [ "agriculture_food", "public_order_unrest" ], "states": [ "haryana" ], "story_ids": [ 295895 ], "independent_outlets": 4, "first_seen": "2026-11-18T02:11:40.000Z", "last_seen": "2026-11-20T20:29:17.000Z", "attributed_by_reporting": [ { "name": "Sugarcane Growers' Coordination Committee", "kind": "organisation", "roles": [ "organiser" ], "carried_as": "reported" }, { "name": "Swabhimani Shetkari Sanghatana", "kind": "organisation", "roles": [ "organiser" ], "carried_as": "reported" }, { "name": "Bharatiya Kisan Union (Doaba)", "kind": "organisation", "roles": [ "organiser" ], "carried_as": "reported" }, { "name": "Haryana Kisan Mazdoor Sangharsh Morcha", "kind": "organisation", "roles": [ "organiser" ], "carried_as": "reported" } ] } ], "note": "Each finding names its orchestrator, mediums and target from the roles the reporting gives each party; a medium's lift is its share of the finding against its usual share of protest, strike and attack coverage."}Fields
Section titled “Fields”| Field | Type | Values | What it is |
|---|---|---|---|
data |
array of objects | Findings, newest first. | |
data[].id |
integer | The finding’s id. | |
data[].label |
string | A short label for the finding. | |
data[].pattern |
string | same_actor, same_theme, called_action |
What joins its stories: same_actor (the reporting names one party in each), same_theme (a shared theme and sector), or called_action (one action described as called or multi-site). |
data[].theme |
string or null | A slug for the shared theme. | |
data[].grade |
string | A, B, C |
The evidence grade, strongest first. A: strongest support in the reporting. B: a pattern across stories or places. C: an early pattern to watch, not yet a finding to rely on. A grade says how much the reporting supports a pattern, not that anyone coordinated it. |
data[].verdict |
string | The finding in a sentence or two. | |
data[].orchestrator |
object or null | The party the reporting names as running it, or null when no one is named. | |
data[].orchestrator.kind |
string | organisation, movement, party, state_agency, armed_group, union, company, public_official, public_figure |
What the party is: an organisation, movement, party, state agency, armed group, union, company, public official or public figure. |
data[].orchestrator.name |
string | The party’s name as the reporting gives it. | |
data[].orchestrator.role |
string | organiser, claimant, blamed, accused, target, responder |
The role the reporting gives it in this finding. |
data[].orchestrator.stories |
integer | In how many of the finding’s stories it has that role. | |
data[].orchestrator.attribution |
string | official_statement, claim_by_actor, reported, alleged_by_opponent, speculation |
How the reporting attributes the role, strongest first: official_statement, claim_by_actor (the party’s own claim), reported (plain reporting), alleged_by_opponent, speculation. |
data[].orchestrator_allies |
array of objects | Parties named alongside the orchestrator in the same role. | |
data[].orchestrator_allies[].kind |
string | organisation, movement, party, state_agency, armed_group, union, company, public_official, public_figure |
What the party is: an organisation, movement, party, state agency, armed group, union, company, public official or public figure. |
data[].orchestrator_allies[].name |
string | The party’s name as the reporting gives it. | |
data[].orchestrator_allies[].role |
string | organiser, claimant, blamed, accused, target, responder |
The role the reporting gives it in this finding. |
data[].orchestrator_allies[].stories |
integer | In how many of the finding’s stories it has that role. | |
data[].orchestrator_allies[].attribution |
string | official_statement, claim_by_actor, reported, alleged_by_opponent, speculation |
How the reporting attributes the role, strongest first: official_statement, claim_by_actor (the party’s own claim), reported (plain reporting), alleged_by_opponent, speculation. |
data[].mediums |
array of objects | The outlets carrying the finding hardest, most first. | |
data[].mediums[].outlet |
string | The outlet’s name. | |
data[].mediums[].articles |
integer | Its articles in the finding. | |
data[].mediums[].stories |
integer | The finding’s stories it carried. | |
data[].mediums[].share |
number | Its share of the finding’s articles, 0 to 1. | |
data[].mediums[].lift |
number or null | Its share of this finding against its usual share of protest, strike and attack coverage: above 1 means it carries this more than usual. Null when there is too little history to compare. | |
data[].target |
object or null | The party the reporting names as its target, or null. | |
data[].target.kind |
string | organisation, movement, party, state_agency, armed_group, union, company, public_official, public_figure |
What the party is: an organisation, movement, party, state agency, armed group, union, company, public official or public figure. |
data[].target.name |
string | The party’s name as the reporting gives it. | |
data[].target.role |
string | organiser, claimant, blamed, accused, target, responder |
The role the reporting gives it in this finding. |
data[].target.stories |
integer | In how many of the finding’s stories it has that role. | |
data[].target.attribution |
string | official_statement, claim_by_actor, reported, alleged_by_opponent, speculation |
How the reporting attributes the role, strongest first: official_statement, claim_by_actor (the party’s own claim), reported (plain reporting), alleged_by_opponent, speculation. |
data[].statement |
string | The full finding as one paragraph, citable as it stands. | |
data[].what_would_change |
string | What new reporting would raise, lower or overturn the grade. | |
data[].sectors |
array of strings | a sector key | Sectors its stories touch. |
data[].states |
array of strings | a state slug | States its stories are in. |
data[].story_ids |
array of integers | Its stories; pass each to GET /stories/{id}. | |
data[].independent_outlets |
integer | Independent outlets across its stories. | |
data[].first_seen |
string (time) | The first article’s time. | |
data[].last_seen |
string (time) | The latest article’s time. | |
data[].attributed_by_reporting |
array of objects | Every party the reporting names in the finding’s stories, with how it is attributed. | |
data[].attributed_by_reporting[].name |
string | The party’s name. | |
data[].attributed_by_reporting[].kind |
string | What the party is (as Party.kind). | |
data[].attributed_by_reporting[].roles |
array of strings | The roles the reporting gives it. | |
data[].attributed_by_reporting[].carried_as |
string | official_statement, claim_by_actor, reported, alleged_by_opponent, speculation |
How the reporting attributes the role, strongest first: official_statement, claim_by_actor (the party’s own claim), reported (plain reporting), alleged_by_opponent, speculation. |
note |
string | How to read the parties and lift, in one sentence. |
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”limitis applied beforegrade:grade=A&limit=10returns the A findings among the latest ten. Ask for the maximum (60) when filtering by grade.- A grade is how strongly the reporting supports the pattern, not a claim that anyone coordinated anything. Read
statementandwhat_would_changewith it. - Parties, mediums and targets come from the roles the reporting gives each party.
attributed_by_reportingshows every party and how it was attributed. - Only events of the kinds that can be organised (protests, strikes, attacks and security operations) are considered.
From an AI assistant
Section titled “From an AI assistant”The MCP tool list_coordination runs this endpoint’s code and returns the same JSON. Its default limit differs: The REST default is 30.