timeline.list · Umwelt docs

Reference/Queries/timeline.list

timeline.listquerysince 0.1

Every timeline of a project, main first.

Command lineTypeScript.NET

Request

umwelt call story.umw timeline.list '{
  "projectId": "ball"
}'

Request

const result = await client.timelineList({ projectId: 'ball' });

Request

var result = engine.TimelineList(new TimelineListPayload { ProjectId = "ball" });

Response

[
  {
    "kind": "main",
    "id": "main",
    "status": "active",
    "projectId": "ball",
    "createdAt": "2026-11-11T18:21:58.5898875Z",
    "depth": 0,
    "headVersion": 17,
    "maxTick": 11
  },
  {
    "kind": "draft",
    "id": "chapter-2",
    "status": "promoted",
    "projectId": "ball",
    "label": "Chapter 2",
    "baseVersion": 16,
    "closedAt": "2026-11-11T18:21:58.6788929Z",
    "createdAt": "2026-11-11T18:21:58.6687174Z",
    "depth": 1,
    "headVersion": 17,
    "maxTick": 11,
    "parentTimelineId": "main"
  },
  {
    "kind": "draft",
    "id": "other-ending",
    "status": "active",
    "projectId": "ball",
    "label": "Another ending",
    "baseVersion": 17,
    "createdAt": "2026-11-11T18:21:58.6818065Z",
    "depth": 1,
    "headVersion": 18,
    "maxTick": 12,
    "parentTimelineId": "main"
  }
]

Payload

Field	Type	Description
`projectId`required	string	The project to read.
`status`	"active" \| "promoted" \| "discarded"	Only timelines with this status: `active`, `promoted` or `discarded`.

Result

A list of Timeline, each with:

Field	Type	Description
`id`always	string	The timeline’s id. Main is always `main`.
`projectId`always	string	The project it belongs to.
`kind`always	"main" \| "draft"	`main` or `draft`.
`status`always	"active" \| "promoted" \| "discarded"	`active`, `promoted` or `discarded`. Only an active timeline accepts writes.
`label`	string	Its label.
`parentTimelineId`	string	The timeline it branched from: `main` or another draft. Absent for main.
`depth`always	integer	Drafts from main down to it: 0 for main, 1 for a draft of main, at most 4.
`baseVersion`	integer	The parent’s head when it was opened. Absent for main.
`headVersion`always	integer	The version of its latest commit, or its base when it has none.
`maxTick`always	integer	The highest tick it sees.
`createdAt`always	string	When it was opened (UTC).
`closedAt`	string	When it was promoted or discarded.
`purgedAt`	string	When its rows were purged.

Errors

VALIDATION_FAILEDThe payload is malformed.

NOT_FOUNDThe project does not exist.

HANDSHAKE_REQUIREDOver the protocol, hello was not sent first.

Every code is listed in Errors.

Payload

Result

Errors

See also