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 finished successfully
ROLLED_BACK	Superseded by a later attempt on the same step
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. These represent earlier attempts on the same step that were superseded — useful for understanding retry history.
• 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.

---