Recordings

Every session keeps two records of what happened in it. Both can be read while the session runs and after it stops:

• a recording: a frame-by-frame replay of its screen;
• a log of events: console messages, network requests, page loads, errors, actions, every shell command and more.

They are kept while the session is stopped, for your plan’s retention days: 7 on Free, 30 on Hobby and Startup, 90 on Scale. Then the session is deleted, with its recording and log. You can delete it earlier. See How long they are kept.

Recordings

Sessions record by default (recordSession: true when you create one), on plans that include session recordings (see Plans and features). Create a session with recordSession: false to record nothing.

The platform keeps a JPEG frame:

• whenever the screen has changed, checked every two seconds;
• each time a page finishes loading, so a short visit between two checks still shows (at most one such frame every quarter of a second);
• after each step of an agent run that clicks, types, selects or presses a key, so every step has its own screen;
• once more when the session stops, so the last screen is there.

A session without a browser (browser: false, a shell only) has nothing to record: it has no frames, hasRecording stays false, and its log has no console, network or navigation events.

GET /v1/sessions/:id/recording lists the frames (index, at and the page’s url) and the recording’s length. GET /v1/sessions/:id/recording/frames/:index returns one frame as an image. The session’s hasRecording tells you whether there is anything to show.

curl https://api.boxline.dev/v1/sessions/$SESSION_ID/recording \  -H "x-api-key: $BOXLINE_API_KEY"curl https://api.boxline.dev/v1/sessions/$SESSION_ID/recording/frames/0 \  -H "x-api-key: $BOXLINE_API_KEY" \  -o frame-0.jpg

const { frames, durationMs } = await session.recording();console.log(frames.length, "frames over", durationMs, "ms");const jpeg = await session.recordingFrame(0);await writeFile("frame-0.jpg", jpeg); // writeFile from node:fs/promises

recording = session.recording()print(len(recording["frames"]), "frames over", recording["durationMs"], "ms")with open("frame-0.jpg", "wb") as f:    f.write(session.recording_frame(0))

Events

A session’s events are the one place for everything that happened in it, live and after it has stopped: what the page did, what your code called, what an agent run did, and every shell command, whoever ran it. GET /v1/sessions/:id/events returns them oldest first. Filter with types. To page forward, or to poll for new events, pass nextAfter back as after. To see only what one agent run did in the session, pass its id as runId.

Each event has seq (its number in the session), at, type, and the fields that fit its type: level, text, url, method, status, resourceType, durationMs, tabId and data.

curl "https://api.boxline.dev/v1/sessions/$SESSION_ID/events?types=console,error,captcha" \  -H "x-api-key: $BOXLINE_API_KEY"

const page = await session.events({ types: ["console", "error", "captcha"] });for (const e of page.data) console.log(e.seq, e.type, e.text);const after = page.nextAfter; // poll again later from here: session.events({ after })

page = session.events(types=["console", "error", "captcha"])for e in page.data:    print(e["seq"], e["type"], e.get("text"))after = page.next_after  # poll again later from here: session.events(after=after)

A page holds up to 500 events by default (at most 2,000 with limit). next has the same value as nextAfter while the page was full, and is null once you have caught up.

Shell commands, whoever ran them

Every command the session runs is an exec event, from every source. An agent run’s bash commands are in the session’s events too, not only in the run’s steps, so one stream shows what your own calls and the agent did, in order.

An event has the command in text (credential values hidden), durationMs, and the exit code in data.exitCode. The output is not in the event: it stays with whoever ran the command. You get it in the answer to your own call, and an agent’s output is in the run’s steps.

curl "https://api.boxline.dev/v1/sessions/$SESSION_ID/events?types=exec" \  -H "x-api-key: $BOXLINE_API_KEY"

for await (const e of session.events({ types: ["exec"] })) {  console.log(e.seq, e.data?.by, e.data?.runId ?? "", e.text, "exit", e.data?.exitCode);}

for e in session.events(types=["exec"]):    print(e["seq"], e["data"].get("by"), e["data"].get("runId", ""), e["text"], "exit", e["data"].get("exitCode"))

Browser actions, whoever ran them

Every browser action is an action event too: text is the result line, and data says what it was and who ran it. A failure has level: "error" and, when the error has a code, data.code (for example feature_not_in_plan).

An agent run and its events link by runId and step: the run’s steps say why and what (what the agent saw, thought and did, and what it cost), and the events say what happened in the machine. The step keeps the output; the event keeps only the fact. Pass runId to list or stream just one run’s events.

curl "https://api.boxline.dev/v1/sessions/$SESSION_ID/events?runId=$RUN_ID&types=action,exec" \  -H "x-api-key: $BOXLINE_API_KEY"

for await (const e of session.events({ runId: run.id, types: ["action", "exec"] })) {  console.log(e.data?.step, e.type, e.text);}

for e in session.events(types=["action", "exec"], run_id=run["id"]):    print(e["data"].get("step"), e["type"], e.get("text"))

Files

A write, upload or delete through the Files API is a files event: data: {op: "write" | "delete", path, bytes, by: "api"}, with the path relative to the workspace. Reading, listing and downloading folders are not logged. The files a shell command creates or changes are on that command’s exec event (data.files, for an agent’s command), never also as files events.

Live stream

GET /v1/sessions/:id/events/stream is a server-sent events stream: it sends what is already logged after after, then each new event as it happens, one per data: line. It carries the same events as the list, an agent run’s shell commands included, and takes runId too.

curl -N https://api.boxline.dev/v1/sessions/$SESSION_ID/events/stream \  -H "x-api-key: $BOXLINE_API_KEY"

for await (const e of session.streamEvents()) {  console.log(e.seq, e.type, e.text ?? e.url ?? "");  if (e.type === "error") break; // leave the loop to stop the stream}

for e in session.stream_events():    print(e["seq"], e["type"], e.get("text") or e.get("url", ""))

Pages visited

GET /v1/sessions/:id/pages lists each URL the session opened, per tab, with its title, the number of visits and the first and last time it was seen.

curl https://api.boxline.dev/v1/sessions/$SESSION_ID/pages \  -H "x-api-key: $BOXLINE_API_KEY"

const { data } = await session.pages();for (const p of data) console.log(p.visits, p.url, p.title);

for p in session.pages():    print(p["visits"], p["url"], p["title"])

How long they are kept

A stopped session keeps its recording and log until its deletesAt: your plan’s retentionDays after it stopped. The platform checks once an hour, and then deletes the session.

The day is fixed when the session stops (deletesAt = stoppedAt + retentionDays), so a later plan change does not move it. Resuming a session and stopping it again sets a new day. You can also delete a session yourself, at any time: DELETE /v1/sessions/:id. That deletes everything below at once and cannot be undone.

What is deleted:

• the recording (every frame);
• the event log and the list of pages visited;
• the steps of agent runs in the session: their tool output and screenshot notes;
• what the session saved when it stopped: the browser (tabs, cookies and site storage) and the files in /workspace (downloads and uploads too), and any copy left from its checkpoints.

The session record stays, with its usage and cost for billing. Its status becomes DELETED, with deletedAt and deleteReason (requested or retention), and a session.deleted webhook is sent. After that, the recording and log calls answer with empty lists, and hasRecording is false. Agent runs keep their task, result and token counts.

Not affected: browser profiles (until you delete them), usage and billing records, and webhook bodies, which have their own rule (7 days). Your plan’s value is limits.retentionDays in GET /v1/auth/me.