Runs

A run is the durable record of a runtime’s lifecycle, from start to stop. Every start opens a run that records structured events, an activity timeline, a live view you can watch or take over, a replayable recording, and any files produced. Use it to see what an agent did while it ran and to replay it afterward.

Read a run

1
const run = await bctrl.runs.get(runId);
2
3
const { data } = await bctrl.runs.list({ spaceId: space.id, status: "completed" });
4
5
for await (const r of bctrl.runs.iter({ runtimeId: runtime.id })) {
6
  console.log(r.id, r.status);
7
}

Events and activity

Events are the structured timeline of what happened in the run. List them, or stream them live:

1
const events = await bctrl.runs.events.list(runId);
2
3
for await (const event of bctrl.runs.events.iter(runId)) {
4
  console.log(event.type, event.time);
5
}

activity is the higher-level view over the same run:

1
const activity = await bctrl.runs.activity.list(runId);

Both expose a streamUrl(runId) for server-sent events. See Streaming.

Live view

Mint a short-lived viewer URL to watch a run, optionally with human takeover:

1
const live = await bctrl.runs.live(runId, { control: "none" });
2
console.log(live.url, live.expiresAt);

Set control: "input" to let a human take over the browser through the iframe.

Recording

Once a run ends, mint a recording viewer to replay it:

1
const recording = await bctrl.runs.recording(runId);
2
console.log(recording.url, recording.durationMs);

Files

List the files a run produced, or export them as a downloadable archive:

1
const files = await bctrl.runs.files.list(runId);
2
const archive = await bctrl.runs.files.export(runId, {
3
  name: "session-files",
4
  type: ["download"],
5
});

Next

• Events & Activity - the structured timeline in depth
• Invocations - the hosted work recorded in a run
• Streaming - subscribe to run events over SSE