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.

import { Bctrl } from "@bctrl/sdk";
const bctrl = new Bctrl({ apiKey: process.env.BCTRL_API_KEY! });
// streamUrl mints a ready-to-use SSE endpoint for the run.
const url = bctrl.runs.events.streamUrl(runId);
let networkFailures = 0;
const source = new EventSource(url);
source.addEventListener("run.event", (message) => {
  const event = JSON.parse(message.data);
  switch (event.type) {
    case "network.failed":
      if (++networkFailures >= 5) {
        notify(`run ${runId}: ${networkFailures} failed requests`); // your alerting
      }
      break;
    case "console.message":
      // surface page-side errors in your own logs
      break;
    case "navigation":
      console.log("now at", event.time);
      break;
  }
});

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

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