Pausing and resuming runs

Some tasks need input the Agent can’t produce: a verification code, an approval, or an answer from another system. With pauseWhen, the Agent can pause the run, tell you what it needs, and continue exactly where it left off once you reply. The reply can come from a person, your application, or another agent.

Enable pausing on a run

Pass pauseWhen when you run an Agent. It describes when the Agent may pause, in your own words. Runs without it never pause.

curl https://api.browserbase.com/v1/agents/runs \
  --header "x-bb-api-key: $BROWSERBASE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "task": "Log in to the billing portal and download the latest invoice",
    "pauseWhen": "when the site asks for a verification code"
  }'

The Agent pauses only under those conditions. A vague task is not a reason to pause: the Agent still makes reasonable assumptions and keeps going.

Detect a paused run

When the Agent pauses, the run’s status becomes PAUSED. PAUSED is not terminal, so stop polling on it as well as on terminal statuses (see Run lifecycle):

Node.js

const stopAt = ["PAUSED", "COMPLETED", "FAILED", "STOPPED", "TIMED_OUT"];

The Agent’s request is the last message in the run’s transcript: a pause tool call whose input.message says what it needs and in what form. Read it with List run messages:

{
  "role": "assistant",
  "content": [
    {
      "type": "tool-call",
      "toolName": "pause",
      "toolCallId": "toolu_01HR58Eb6RbLfnjU7igxvQAz",
      "input": { "message": "Reply with the 6-digit code sent to the phone ending in 1234" }
    }
  ]
}

While a run is paused, its browser session stays open, so the page is exactly as the Agent left it. The run doesn’t keep its file workspace: files from before the pause are gone when it resumes.

Resume the run

Call Resume a run with your reply in task:

curl https://api.browserbase.com/v1/agents/runs/$RUN_ID/resume \
  --header "x-bb-api-key: $BROWSERBASE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "task": "The code is %code%", "variables": { "code": { "value": "481516" } } }'

The response is 202 with the run back in RUNNING. Poll it as before. It may pause again if the same conditions come up. Pass secrets such as verification codes as variables rather than in task. The Agent types the %name% placeholder and Browserbase swaps in the real value as it types, so the value never enters the transcript. The resumed run doesn’t keep the original run’s variables, so re-supply any it needs. A resumed run continues within the original run’s limits: its step budget and maximum duration count from when the run first started.

Responses and errors

Status	Meaning	What to do
`202`	The run resumed.	Poll until it pauses again or finishes.
`404`	No such run in this project.	Check the run ID.
`409`	The run isn’t paused, another resume or stop got there first, or the run couldn’t continue from its pause.	Get the run: if it’s still `PAUSED`, retry after a short delay; otherwise act on its new status.
`500` with “Resume outcome is unknown”	The resume may or may not have started.	Poll the run before retrying.
`503`	Run control is temporarily unavailable.	Retry after a short delay.

Limits

A paused run holds its browser session until the session times out: up to 15 minutes on free plans or 60 minutes on paid plans. Browserbase starts this timer when it creates the session. Pausing doesn’t reset the timer, so any browser use before the pause counts toward the limit. If you resume after the session expires, the run ends as TIMED_OUT.
You can’t stop a paused run yet: Stop a run returns 409 for it. Resume it and stop it, or let it expire.

Welcome

Platform

Use cases

Optimization

Account

Enable pausing on a run

Detect a paused run

Resume the run

Responses and errors

Limits

​Enable pausing on a run

​Detect a paused run

​Resume the run

​Responses and errors

​Limits

Enable pausing on a run

Detect a paused run

Resume the run

Responses and errors

Limits