timeline · Umwelt docs

Reference/Queries/timeline

timelinequerysince 0.1

The events visible at a position, in story order, one page at a time.

Command lineTypeScript.NET

Request

umwelt call story.umw timeline '{
  "projectId": "ball",
  "at": { "tick": 2 },
  "page": { "limit": 2 }
}'

Request

const result = await client.timeline({ projectId: 'ball', at: { tick: 2 }, page: { limit: 2 } });

Request

var result = engine.Timeline(new TimelinePayload
{
    ProjectId = "ball",
    At = new At { Tick = 2 },
    Page = new Page { Limit = 2 },
});

Response

{
  "items": [
    {
      "id": "arrivals",
      "projectId": "ball",
      "timelineId": "main",
      "title": "The guests arrive",
      "position": { "tick": 0 },
      "on": { "reading": 1 },
      "evidence": [],
      "participants": ["bob", "duchess", "maid", "butler"],
      "provenance": { "origin": { "kind": "human" } },
      "recordedAt": 1,
      "type": "scene"
    },
    {
      "id": "scene-1",
      "projectId": "ball",
      "timelineId": "main",
      "title": "The ball",
      "position": { "tick": 1 },
      "evidence": [],
      "participants": ["ana", "bob", "duchess"],
      "provenance": { "origin": { "kind": "human" } },
      "recordedAt": 2,
      "type": "scene"
    }
  ],
  "nextCursor": "310a320a7363656e652d31"
}

Payload

Field	Type	Description
`projectId`required	string	The project to read.
`at`	Atdefault {}	Where to read: `tick`, an optional `axis`, and `asOfVersion`. Defaults to the latest.
`page`	Pagedefault {"limit":100}	How many items to return (`limit`, 1 to 1000) and where to continue (`cursor`, the `nextCursor` of the previous page).
`timelineId`	stringdefault "main"	The timeline to read.

Result

Field	Type	Description
`items`always	Event[]	The events.
`nextCursor`	string	More events follow; pass it as `page.cursor`.

Rules

Reading order on another axis. On an additional axis, the page is ordered by the position on that axis, and events without one are left out.

Pages are stable. A cursor stays valid when later writes arrive.

Errors

VALIDATION_FAILEDThe payload is malformed, or the page limit is outside 1 to 1000.

NOT_FOUNDThe project or timeline does not exist, or the draft read was purged.

INVALID_STATEThe timeline read is a draft that was promoted. details.promotedInto names the timeline to read instead.

HANDSHAKE_REQUIREDOver the protocol, hello was not sent first.

Every code is listed in Errors.

Payload

Result

Rules

Errors

See also