> ## Documentation Index
> Fetch the complete documentation index at: https://docs.browserbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pausing and resuming runs

> Let an Agent pause for input it can't get on its own, then resume the run with a reply.

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](/reference/api/run-an-agent). It describes when the Agent may pause, in your own words. Runs without it never pause.

```bash theme={null}
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](/platform/agents/overview#run-lifecycle)):

```typescript Node.js theme={null}
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](/reference/api/list-run-messages):

```json theme={null}
{
  "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](/reference/api/resume-a-run) with your reply in `task`:

```bash theme={null}
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`](/platform/agents/integrate-api-sdk#passing-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](/reference/api/stop-a-run) returns `409` for it. Resume it and stop it, or let it expire.