Get a session's timeline

The session's act steps in order, one row per step (skipped steps included): kind, start, duration, status, error, the target's box in the viewport, and a JPEG thumbnail when the session was created with `thumbnails: true`. Also the cursor path: every pointer event, from act steps and from `Input.dispatchMouseEvent` commands a CDP client sent over the session's socket, with its time since the session was created. Kept with the session (at most 1,000 steps, 20,000 points and 8 MiB of thumbnails; `dropped` counts what did not fit); a row's `url` and its error's `detail` are cut to 2,048 characters, and a CDP command whose `type` or `button` is not one of the documented values adds no point. Thumbnails are dropped 15 minutes after the session closes. The closed sessions of one organization keep at most 64 MiB of timelines together: the most recently closed keep theirs, older ones read empty, with what they held counted in `dropped`. The timeline is empty for a session closed by a node restart.

GET /v1/vision/sessions/{session_id}/timeline
The session's act steps in order, one row per step (skipped steps included): kind, start, duration, status, error, the target's box in the viewport, and a JPEG thumbnail when the session was created with `thumbnails: true`. Also the cursor path: every pointer event, from act steps and from `Input.dispatchMouseEvent` commands a CDP client sent over the session's socket, with its time since the session was created. Kept with the session (at most 1,000 steps, 20,000 points and 8 MiB of thumbnails; `dropped` counts what did not fit); a row's `url` and its error's `detail` are cut to 2,048 characters, and a CDP command whose `type` or `button` is not one of the documented values adds no point. Thumbnails are dropped 15 minutes after the session closes. The closed sessions of one organization keep at most 64 MiB of timelines together: the most recently closed keep theirs, older ones read empty, with what they held counted in `dropped`. The timeline is empty for a session closed by a node restart.

Authentication

Bearer Token (b3os_sk_ API key or b3os_pat_ token)

Path Parameters

session_id string required path
The session ID (`brs_…`).
Example: "brs_01m5t3y30wcksxf22t9gwk9fwb"

Responses

200 The timeline.
application/json
object string REQUIRED
Enum: session_timeline
session_id string REQUIRED
viewport object REQUIRED
Browser viewport in CSS pixels.
width integer REQUIRED
height integer REQUIRED
steps object[] REQUIRED
Array of:
act integer REQUIRED
Which act call on the session (1, 2, ...).
index integer REQUIRED
The step's position in that call's `actions`.
kind string REQUIRED
Enum: navigate, click, hover, type, key, scroll, select, wait, evaluate, screenshot, markdown
started_at string (date-time) REQUIRED
at_ms integer REQUIRED
Milliseconds from the session's creation to the step's start.
duration_ms number REQUIRED
status string REQUIRED
Enum: ok, failed, skipped
target object | null REQUIRED
The target's box in the viewport (CSS pixels, after it was scrolled into view), or `null` for a step without a target.
x number REQUIRED
y number REQUIRED
width number REQUIRED
height number REQUIRED
url string | null REQUIRED
The URL a `navigate` step reached.
error object
The step's problem; only on a step that failed.
type string (uri) REQUIRED
`https://docs.beta.b3os.org/errors#<code>`.
title string REQUIRED
Short summary of the problem type.
status integer REQUIRED
The HTTP status code, repeated for convenience.
code string REQUIRED
Stable machine-readable error code from the errors catalog.
detail string REQUIRED
Explanation of this occurrence. Never contains secrets.
instance string
The request ID (`req_…`) of the request that failed. Include it when you contact support.
errors object[]
Validation problems, one per field (`invalid_request` and the other codes that list `errors`).
Array of:
pointer string REQUIRED
Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.
detail string REQUIRED
What is wrong there.
reason string
Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).
required_scope string
The scope that was missing (`forbidden` with `reason: scope`).
retry_after_s integer
Same value as the `Retry-After` header, for clients that only read the body.
limit object
The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.
id string REQUIRED
Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.
limit number REQUIRED
The limit's value.
unit string REQUIRED
What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.
window_s integer
Window length in seconds for rate limits and quotas.
current number
Current usage against the limit, when known.
current_status string
The object's current status, for state conflicts such as `sandbox_not_running`.
upstream_status integer
The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).
step string
The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).
pack_error object
The error a pack's error mapping chose (`upstream_error` from pack actions).
code string REQUIRED
message string REQUIRED
retryable boolean REQUIRED
thumbnail object | null REQUIRED
A JPEG of the viewport after the step, or `null` (thumbnails off, skipped step, budget spent).
format string REQUIRED
Enum: jpeg
width integer REQUIRED
height integer REQUIRED
data_base64 string REQUIRED
cursor object[] REQUIRED
Array of:
at_ms integer REQUIRED
Milliseconds from the session's creation.
x number REQUIRED
y number REQUIRED
type string REQUIRED
`Input.dispatchMouseEvent` type: `mouseMoved`, `mousePressed`, `mouseReleased` or `mouseWheel`.
button string
The button of a press or release (`left`, `middle`, `right`, `back`, `forward`).
source string REQUIRED
`act`: an act step. `cdp`: a CDP client on the session socket.
Enum: act, cdp
dropped object REQUIRED
What did not fit in the session's timeline.
steps integer REQUIRED
points integer REQUIRED
thumbnails integer REQUIRED
400 The request failed validation (`invalid_request`, `invalid_url`).
401 Missing, malformed, expired or revoked credentials (`unauthorized`).
403 Authenticated but not allowed (`forbidden`, `egress_denied`).
404 No such browser session in this project (`session_not_found`).
429 A rate, concurrency or quota limit applies (`rate_limited`, `concurrency_limited`, `quota_exceeded`).
500 Something failed inside B3OS (`internal`). Retry with backoff.
503 The node or the product is not available right now (`node_unavailable`, `product_unavailable`, `capacity_unavailable`). 
curl -X GET 'https://beta-api.b3os.org/v1/vision/sessions/brs_01m5t3y30wcksxf22t9gwk9fwb/timeline' \  -H 'Authorization: Bearer YOUR_API_TOKEN'
const response = await fetch('https://beta-api.b3os.org/v1/vision/sessions/brs_01m5t3y30wcksxf22t9gwk9fwb/timeline', {  method: 'GET',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN"  }});const data = await response.json();console.log(data);
import requestsheaders = {    'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.get('https://beta-api.b3os.org/v1/vision/sessions/brs_01m5t3y30wcksxf22t9gwk9fwb/timeline', headers=headers)print(response.json())
200 Response 
{  "object": "session_timeline",  "session_id": "brs_01m5t3y30wcksxf22t9gwk9fwb",  "viewport": {    "width": 1280,    "height": 800  },  "steps": [    {      "act": 1,      "index": 0,      "kind": "click",      "started_at": "2026-10-30T18:02:11.204Z",      "at_ms": 5120,      "duration_ms": 3.1,      "status": "ok",      "target": {        "x": 540,        "y": 380,        "width": 200,        "height": 40      },      "url": null,      "thumbnail": null    }  ],  "cursor": [    {      "at_ms": 5122,      "x": 640,      "y": 400,      "type": "mouseMoved",      "source": "act"    },    {      "at_ms": 5122,      "x": 640,      "y": 400,      "type": "mousePressed",      "button": "left",      "source": "act"    },    {      "at_ms": 5122,      "x": 640,      "y": 400,      "type": "mouseReleased",      "button": "left",      "source": "act"    }  ],  "dropped": {    "steps": 0,    "points": 0,    "thumbnails": 0  }}
Previous Create a stream ticket
Next Save a session to a profile
Ask a question... ⌘I