Shipeasy
APIOperations

Read a trail's timeline

Everything that happened on the trail, newest first: created, plans approved, questions asked and answered (on the trail and on its items), runs, items…

Everything that happened on the trail, newest first: created, plans approved, questions asked and answered (on the trail and on its items), runs, items filed and done, pull requests opened, approved and merged, every rollout step, pull-back and autopilot action, the goal watched and met or missed, errors attributed. Each event says whether it was a decision — a choice a person (or autopilot on a person's authority) made — and a decided question carries every option it offered and which one was picked.

Pass decisions=true for the decisions only. Page with before (the next of the previous page).

Safe for the restricted ops key.

Use case

Before re-planning, an agent reads what was tried and decided on the trail so the next revision does not repeat it.

GET
/api/admin/trails/{handle}/timeline

Authorization

bearerSdkKey
AuthorizationBearer <token>

Pass an admin SDK key as Authorization: Bearer sdk_admin_…. Mint via POST /api/admin/keys with type: "admin".

In: header

Path Parameters

handle*string

The trail's handle (T-12) or its id.

Match^(?:T-[0-9]+|[0-9a-fA-F-]{32,36})$
Length1 <= length <= 64

Query Parameters

before?string

ISO-8601 time; only events strictly before it (the next of the previous page).

Length1 <= length <= 40
limit?integer

Most events to return (1-200). Defaults to 50.

Range1 <= value <= 200
decisions?boolean

Only the decisions.

Header Parameters

X-Project-Id?string

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/string/timeline"
{
  "events": [
    {
      "id": "q:5c1d:answered",
      "at": "2026-11-04T10:20:00.000Z",
      "kind": "question_answered",
      "actor": "alice@acme.dev",
      "decision": true,
      "detail": null,
      "item": null,
      "change": null,
      "question": {
        "id": "5c1d",
        "header": "Release approach",
        "question": "How should T-12 ship?",
        "on": "trail",
        "options": [
          {
            "label": "Behind a flag",
            "description": "Recommended: touches every checkout",
            "picked": true
          },
          {
            "label": "Straight to main",
            "description": "No flag. It reaches everyone on merge",
            "picked": false
          }
        ],
        "other": null
      },
      "revision": null,
      "run": null,
      "release": null
    }
  ],
  "next": 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 resource does not exist or is not visible to the caller.",
  "code": "NOT_FOUND"
}
Was this page helpful?