Observability

If you only need the result, use runs.wait_for_completion() in Python or runs.waitForCompletion() in TypeScript. It polls the lightweight status endpoint instead of downloading every event. For a custom UI, poll runs.events() with the previous cursor. Read status before fetching events so that the final fetch happens after you observe a terminal state, and drain all hasMore pages before stopping:

import time

after = None
while True:
    status = client.runs.status(run.id).status.value
    page = client.runs.events(run.id, after=after)
    for event in page.events:
        print(event.type, event.data)
    after = page.next_after if page.next_after is not None else after

    if status in {"completed", "failed", "cancelled"} and not page.has_more:
        break
    time.sleep(2)

let after: number | undefined;
while (true) {
  const { status } = await client.runs.status(run.id);
  const page = await client.runs.events(run.id, { after });
  for (const event of page.events) {
    console.log(event.type, event.data);
  }
  after = page.nextAfter ?? after;

  if (["completed", "failed", "cancelled"].includes(status) && !page.hasMore) break;
  await new Promise((resolve) => setTimeout(resolve, 2000));
}

Events cover run lifecycle, model calls, browser readiness, tool activity, artifacts, and completion. See Get run events for the complete response shape. This two-second interval is an example for one stream, not a safe default for an unbounded batch. Event reads share the project’s general request bucket. Use a shared rate limiter and stagger polling across runs. Keep the cursor when backing off after a 429, and resume from it rather than rereading history. See Concurrency and rate limits for capacity, request budgets, retries, and the separate per-session message queue.

Get Started

Pillars

More