React to Run Events | BCTRL Docs

Every Run emits a structured event stream - navigations, network failures, console errors. Subscribe over server-sent events and turn the ones you care about into alerts or interventions, while the Run is still going.

1 import { Bctrl } from "@bctrl/sdk";
2 
3 const bctrl = new Bctrl({ apiKey: process.env.BCTRL_API_KEY! });
4 
5 // streamUrl mints a ready-to-use SSE endpoint for the run.
6 const url = bctrl.runs.events.streamUrl(runId);
7 
8 let networkFailures = 0;
9 
10 const source = new EventSource(url);
11 source.addEventListener("run.event", (message) => {
12   const event = JSON.parse(message.data);
13 
14   switch (event.type) {
15     case "network.failed":
16       if (++networkFailures >= 5) {
17         notify(`run ${runId}: ${networkFailures} failed requests`); // your alerting
18       }
19       break;
20     case "console.message":
21       // surface page-side errors in your own logs
22       break;
23     case "navigation":
24       console.log("now at", event.time);
25       break;
26   }
27 });

Filter at the source instead of in your handler when you only want one kind of event:

1 const url = bctrl.runs.events.streamUrl(runId, { type: "console.message" });

Reacting, not just watching

The stream pairs with the rest of the API. A burst of network.failed events might mean the proxy exit went bad - stop the Runtime and restart on a fresh sticky key. A page that’s clearly stuck is a good moment to mint a View and page a human, with the URL right in the alert.

For a after-the-fact version of the same data - paged, filterable, no connection to hold - use bctrl.runs.events.list(runId) instead. The same Run page explains how trace data and raw events relate.

Trace and events - types, filters, and the activity view
Views - escalate to human eyes
CLI - inspect Runs from the terminal