> ## 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.

# Integrating agents

> Trigger agent runs, pass variables, and track runs to completion from your application over the REST API.

Once you've built an agent in the [dashboard](/welcome/quickstarts/agents), you integrate it into your application over the REST API: trigger runs, pass per-run values, track each run to completion, and read the result.

Runs are asynchronous. You create a run, then track it to a terminal state by polling.

<Tip>
  To scaffold the integration quickly, open an agent's run view in the dashboard and use **Build API in** to open the agent's API prompt in a coding tool like Cursor.
</Tip>

## Endpoints at a glance

**Agents** define reusable configuration.

| Endpoint                                          | Use                                                             |
| ------------------------------------------------- | --------------------------------------------------------------- |
| [Create an agent](/reference/api/create-an-agent) | Define a reusable agent with a system prompt and result schema. |
| [List agents](/reference/api/list-agents)         | Page through your agents.                                       |
| [Get an agent](/reference/api/get-an-agent)       | Fetch a single agent.                                           |
| [Update an agent](/reference/api/update-an-agent) | Change an agent's configuration.                                |
| [Delete an agent](/reference/api/delete-an-agent) | Remove an agent.                                                |

**Runs** are single executions of a task.

| Endpoint                                              | Use                                                |
| ----------------------------------------------------- | -------------------------------------------------- |
| [Run an agent](/reference/api/run-an-agent)           | Start a run, optionally against an existing agent. |
| [List runs](/reference/api/list-runs)                 | Page through runs, filtered by agent or status.    |
| [Get a run](/reference/api/get-a-run)                 | Fetch a run's status and result.                   |
| [List run messages](/reference/api/list-run-messages) | Stream the run's step-by-step transcript.          |

## Trigger a run

Start a run with [Run an agent](/reference/api/run-an-agent). Pass an `agentId` to run an existing agent, along with per-run options like `variables`, `resultSchema`, and `browserSettings`.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.browserbase.com/v1/agents/runs \
      --header "x-bb-api-key: $BROWSERBASE_API_KEY" \
      --header "Content-Type: application/json" \
      --data '{
        "agentId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
        "task": "Find the best matching open role at Browserbase",
        "browserSettings": { "proxies": true }
      }'
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    const response = await fetch("https://api.browserbase.com/v1/agents/runs", {
      method: "POST",
      headers: {
        "x-bb-api-key": process.env.BROWSERBASE_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        agentId: "a1b2c3d4-5678-90ab-cdef-1234567890ab",
        task: "Find the best matching open role at Browserbase",
        browserSettings: { proxies: true },
      }),
    });

    const { runId } = await response.json();
    console.log("Run started:", runId);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    import requests

    response = requests.post(
        "https://api.browserbase.com/v1/agents/runs",
        headers={
            "x-bb-api-key": os.environ["BROWSERBASE_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "agentId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
            "task": "Find the best matching open role at Browserbase",
            "browserSettings": {"proxies": True},
        },
    )

    print("Run started:", response.json()["runId"])
    ```
  </Tab>
</Tabs>

A call with no `agentId` creates an ad-hoc run and returns a `runId`. See [Run an agent](/reference/api/run-an-agent) for every field.

## Passing variables

Use `variables` to pass per-run dynamic values without writing them into the prompt. Each variable pairs a `value` the placeholder resolves to with an optional `description` that tells the agent when to use it. Reference a variable in the task or system prompt as `%variableName%`.

```json theme={null}
{
  "agentId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "task": "Check in to my flight using confirmation %confirmation%",
  "variables": {
    "confirmation": {
      "value": "XYZ123",
      "description": "The flight confirmation code to enter at check-in"
    }
  }
}
```

Variables suit values like account numbers, dates of birth, and confirmation codes. The agent fills the placeholder without the value appearing inline in the task.

## Tracking a run to completion

A run moves through these states:

```
PENDING → RUNNING → COMPLETED
                  → FAILED
                  → TIMED_OUT
                  → STOPPED
```

`PENDING` and `RUNNING` are active. The rest are terminal.

### Poll for the result

Poll [Get a run](/reference/api/get-a-run) until the run reaches a terminal state, then read `result`:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.browserbase.com/v1/agents/runs/$RUN_ID \
      --header "x-bb-api-key: $BROWSERBASE_API_KEY"
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    async function pollRun(runId: string) {
      const terminal = ["COMPLETED", "FAILED", "STOPPED", "TIMED_OUT"];
      while (true) {
        const response = await fetch(
          `https://api.browserbase.com/v1/agents/runs/${runId}`,
          { headers: { "x-bb-api-key": process.env.BROWSERBASE_API_KEY! } },
        );
        const run = await response.json();
        if (terminal.includes(run.status)) return run;
        await new Promise((resolve) => setTimeout(resolve, 2000));
      }
    }

    const run = await pollRun(runId);
    console.log("Result:", run.result);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    import time
    import requests

    def poll_run(run_id):
        terminal = {"COMPLETED", "FAILED", "STOPPED", "TIMED_OUT"}
        while True:
            response = requests.get(
                f"https://api.browserbase.com/v1/agents/runs/{run_id}",
                headers={"x-bb-api-key": os.environ["BROWSERBASE_API_KEY"]},
            )
            run = response.json()
            if run["status"] in terminal:
                return run
            time.sleep(2)

    run = poll_run(run_id)
    print("Result:", run.get("result"))
    ```
  </Tab>
</Tabs>

### Stream progress

To follow what the agent is doing while it runs, poll [List run messages](/reference/api/list-run-messages). Save the response's `nextSince` and pass it back as `since` to fetch only newer messages:

```bash theme={null}
curl "https://api.browserbase.com/v1/agents/runs/$RUN_ID/messages?since=$LAST_MESSAGE_ID" \
  --header "x-bb-api-key: $BROWSERBASE_API_KEY"
```

Messages conform to the [AI SDK UIMessage format](https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message). Each has a `role` and a `parts` array of typed blocks: text, tool calls, reasoning, and files.

<Note>
  Integration is poll-based today: track runs with [Get a run](/reference/api/get-a-run) and [List run messages](/reference/api/list-run-messages). Webhook notifications are planned as a future enhancement.
</Note>

## Listing and filtering

Both list endpoints use cursor pagination. Pass the `nextCursor` from a response back as `cursor` to fetch the next page.

[List runs](/reference/api/list-runs) filters by `agentId`, `status`, and a `startAt`/`endAt` time range:

```bash theme={null}
curl "https://api.browserbase.com/v1/agents/runs?agentId=$AGENT_ID&status=COMPLETED&limit=20" \
  --header "x-bb-api-key: $BROWSERBASE_API_KEY"
```

[List agents](/reference/api/list-agents) pages through your agents with the same `cursor` pagination pattern.

## Next steps

<CardGroup cols={2}>
  <Card title="Run an agent" icon="terminal" iconType="sharp-solid" href="/reference/api/run-an-agent">
    Full request and response reference for a run
  </Card>

  <Card title="List run messages" icon="list" iconType="sharp-solid" href="/reference/api/list-run-messages">
    Stream a run's step-by-step transcript
  </Card>

  <Card title="Managing files" icon="file" iconType="sharp-solid" href="/platform/agents/managing-files">
    Retrieve files an agent downloads during a run
  </Card>

  <Card title="How it works" icon="gear" iconType="sharp-solid" href="/platform/agents/how-it-works">
    The execution loop, run lifecycle, and observability
  </Card>
</CardGroup>