Get session timeline

Retrieve the full step-attempt history for a session

Retrieve a flat, newest-first list of every step attempt for a session. Each entry includes the step identity, attempt number, outcome status, timestamps, and any data blocks produced by that attempt. Use this endpoint for debugging, audit trails, and understanding retry behaviour — for example, when a step was retried multiple times before completing.

---

Endpoint

GET /api/v1/{environment}/sessions/{sessionId}/timeline

Path parameters

Parameter	Type	Required	Description
sessionId	string	Yes	The unique identifier of the session
environment	string	Yes	Environment name (staging or live)

---

Request

No request body is required for this endpoint.

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

---

Response

The response contains a timeline array, sorted newest-first by clock. Each element represents one attempt on one step.

Response parameters

Parameter	Type	Description
timeline	array	All step attempts for the session, sorted newest-first by clock
timeline[].stepId	string	Unique identifier of the workflow step
timeline[].stepType	string	Step type (e.g. DOC_ID:v4, BIOMETRIC_VERIFICATION:v1)
timeline[].stepDescription	string	Human-readable description of the step as configured in the flow definition
timeline[].stepAttempt	integer	Monotonically increasing attempt number per stepId, starting at 1. Stable across repeated calls for the same session.
timeline[].stepStatus	string	Outcome of this attempt. See Step statuses below.
timeline[].stepStartedAt	string	ISO 8601 timestamp when this attempt started
timeline[].stepConcludedAt	string | null	ISO 8601 timestamp when this attempt concluded. null when stepStatus is STARTED (attempt still in progress).
timeline[].dataBlocks	array	Data blocks produced by this attempt. Empty for attempts that produced no output.
timeline[].dataBlocks[].dataBlockId	string	Unique identifier of the data block (UUID)
timeline[].dataBlocks[].type	string	Data block type (e.g. basicIdentity, documentVerification)
timeline[].dataBlocks[].createdBy	object	Step and clock that produced this data block
timeline[].dataBlocks[].createdAt	string	ISO 8601 timestamp when the data block was created
timeline[].dataBlocks[].status	string	STORED or DELETED
timeline[].dataBlocks[].content	object | null	Data block content as documented in Core concepts: Data blocks. null if deleted.

Step statuses

Value	Meaning
STARTED	Attempt is in progress — stepConcludedAt is null
COMPLETED	Definitive result — step completed and reached a decision
ROLLED_BACK	The flow sent the user back to an earlier step, and this attempt was set aside
ABORTED	Session ended before this step completed
ERROR	Step failed with an unrecoverable error
WORKFLOW_EXPIRED	Session timed out before this step completed

---

Example

curl https://localhost:3000/api/v1/live/sessions/0197c55f-5af6-7e3d-af9b-f2359b104be8/timeline \
-H "Authorization: Bearer YOUR_API_KEY"

---

Response examples

Session with a single completed attempt

{
  "timeline": [
    {
      "stepId": "doc_idv",
      "stepType": "DOC_ID:v4",
      "stepDescription": "Document verification",
      "stepAttempt": 1,
      "stepStatus": "COMPLETED",
      "stepStartedAt": "2026-02-26T22:30:00.000Z",
      "stepConcludedAt": "2026-02-26T22:32:55.206Z",
      "dataBlocks": [
        {
          "dataBlockId": "4d720f95-1548-47fc-8f78-5bec27c24865",
          "type": "documentVerification",
          "createdBy": { "stepId": "doc_idv", "clock": 3 },
          "createdAt": "2026-02-26T22:32:55.206Z",
          "status": "STORED",
          "content": {
            "verdict": { "status": "VERIFIED", "reason": null },
            "issues": [],
            "evidences": []
          }
        }
      ]
    }
  ]
}

Session with a rolled-back attempt followed by a completed attempt (newest-first)

{
  "timeline": [
    {
      "stepId": "doc_idv",
      "stepType": "DOC_ID:v4",
      "stepDescription": "Document verification",
      "stepAttempt": 2,
      "stepStatus": "COMPLETED",
      "stepStartedAt": "2026-02-26T22:31:00.000Z",
      "stepConcludedAt": "2026-02-26T22:33:10.000Z",
      "dataBlocks": []
    },
    {
      "stepId": "doc_idv",
      "stepType": "DOC_ID:v4",
      "stepDescription": "Document verification",
      "stepAttempt": 1,
      "stepStatus": "ROLLED_BACK",
      "stepStartedAt": "2026-02-26T22:30:00.000Z",
      "stepConcludedAt": "2026-02-26T22:30:55.000Z",
      "dataBlocks": []
    }
  ]
}

---

Notes

• The timeline array is sorted newest-first by the step's internal clock. For a strictly oldest-first view, reverse the array on the client.
• ROLLED_BACK attempts are included. When the flow sends the user back to an earlier step, the latest attempt of every step from that step up to the one that triggered the rollback is marked ROLLED_BACK, not only the triggering one. Use them to understand retry history.
• The timeline is the final record. A step can have ended as COMPLETED when its step event was sent and show as ROLLED_BACK here, because a later step sent the user back past it. See Track step progress.
• dataBlocks[].content is null when dataBlocks[].status is DELETED (the end-user exercised their right to erasure, or the data block was otherwise removed).
• An in-progress attempt (stepStatus: "STARTED") may appear at the head of the list if the session is still running.

---