List trails
Returns the project's trails, newest activity first. A trail is the unit of shipping: an outcome that takes several items, pull requests and release tools,…
Returns the project's trails, newest activity first. A trail is the unit of shipping: an outcome that takes several items, pull requests and release tools, with a lead, start and target dates, a health and a progress (items done over items on the trail). The phase, health and counts on each row are a snapshot; read one trail with trails get for the live state.
Dashboard table read. view=table is the contract every dashboard list table shares: the endpoint applies f, sort and cursor in SQL and answers { data, next_cursor, section_counts?, grouped? }. Filters and sorts are never applied in the browser, so a condition the server cannot evaluate is a 400.
f— a JSON array of{ "f": field, "o": operator, "v": value }conditions, all ANDed. Fields are the snapshot columns:phase,status,type,priority,owner,health,targetDate,changesOpen,changesMergeable,findingsOpenHigh,itemsOpen,itemsTotal,itemsDone,releasedPct,updatedAt.sort— a column id,-prefixed for descending:number,title,phase,priority,owner,health,progress(items done over items on the trail),target(the target date),changes,findings,items,released,updated,created. Defaults to-updated.cursor— the previous page'snext_cursor;limitis the page size (1–200, default 50).
Scopes (scope) are the dashboard's tabs: mine (trails you own), reviewing, ready, releasing, shipped, closed, or all (the default).
Attribution. mergedSince and touches list the trails that merged inside a window and changed a path or linked a resource — the candidates for an error or alert that started after a release.
Find the trail already shipping a feature before creating another, or list what merged in the last 72 hours to attribute a new alert.
Authorization
bearerSdkKey Pass an admin SDK key as Authorization: Bearer sdk_admin_…. Mint via POST /api/admin/keys with type: "admin".
In: header
Query Parameters
table answers the dashboard table read (f, sort, cursor, limit, section_counts, grouped). Omitted, f and sort are still honoured and the envelope is { data, next_cursor }.
"table"A dashboard tab: mine (owned by the caller), reviewing, ready, releasing, shipped, closed, or all (the default, no narrowing).
"all""all" | "mine" | "reviewing" | "ready" | "releasing" | "shipped" | "closed"Narrow to one phase.
"planning" | "building" | "reviewing" | "ready" | "releasing" | "shipped" | "closed"Narrow to one trail type.
"feature" | "bug" | "task"Narrow to one health (the snapshot's effective health, set or derived).
"on_track" | "at_risk" | "off_track"Narrow to trails owned by one person OR one agent — a users.id, email or display name, or a connector id, display name or handle. Case-insensitive exact match.
Case-insensitive substring filter across the trail's title and body.
length <= 100ISO-8601 timestamp. Narrow to trails with a change merged at or after it.
date-timeA file path (or path prefix) a merged change changed, or a resource key the trail links. Narrow to trails that touch it.
length <= 500The table's filter conditions: a JSON array of { "f", "o", "v" } objects, ANDed. See the operation description for the fields.
length <= 8000A column id, - prefixed for descending (-updated). An unknown column is a 400.
length <= 32Opaque cursor returned in the previous page's next_cursor. Omit for the first page.
Page size (1–200). A page shorter than limit is the last one.
501 <= value <= 200Header Parameters
Project the request operates on. Optional — defaults to the project the SDK key belongs to; pass it only to scope a multi-project key (the generated client sets it once from its configuration, so per-call callers never thread it).
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://shipeasy.ai/api/admin/trails"{
"data": [
{
"id": "6f1c7d52-3a6e-4b6f-9c0e-5d9c1e7a2b10",
"number": 12,
"handle": "T-12",
"title": "Retry failed webhook deliveries",
"body": "Failed deliveries retry with backoff and surface in the delivery log",
"type": "feature",
"priority": "high",
"owner": {
"user": {
"id": "usr_01j7w8a1b2c3d4e5f6g7h8i9j0",
"email": "alice@acme.dev",
"name": "Alice"
},
"agent": null
},
"status": "open",
"closedReason": null,
"phase": "reviewing",
"phaseReason": "1 of 2 changes can merge",
"origin": null,
"repos": [
"acme/api"
],
"changesOpen": 2,
"changesMergeable": 1,
"findingsOpenHigh": 0,
"itemsOpen": 1,
"resourcesCount": 3,
"startDate": "2026-11-02",
"targetDate": "2026-11-20",
"health": "on_track",
"healthSource": "derived",
"itemsTotal": 6,
"itemsDone": 2,
"goal": {
"metric": {
"id": "met_01j7w8k2m3n4p5q6r7s8t9v0w1",
"key": "webhook_delivery_success_rate"
},
"direction": "increase",
"baseline": 97.2,
"target": 99.5,
"unit": "%"
},
"releasedPct": null,
"mergedAt": null,
"shippedAt": null,
"closedAt": null,
"snapshotAt": "2026-11-03T10:02:44.000Z",
"createdAt": "2026-11-02T09:14:08.000Z",
"updatedAt": "2026-11-03T10:02:44.000Z"
}
],
"next_cursor": null
}{
"error": "Malformed request (bad JSON, missing project scope).",
"code": "BAD_REQUEST"
}{
"error": "Missing or invalid admin SDK key.",
"code": "UNAUTHORIZED"
}{
"error": "Key is valid but not allowed to act on this project.",
"code": "FORBIDDEN"
}{
"error": "The request body failed structural (schema) validation.",
"code": "VALIDATION"
}