Skip to main content
GET
/
v1
/
agents
/
runs
List Runs
curl --request GET \
  --url https://api.browserbase.com/v1/agents/runs \
  --header 'X-BB-API-Key: <api-key>'
{
  "data": [
    {
      "runId": "<string>",
      "task": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "agentId": "<string>",
      "sessionId": "<string>",
      "sandboxId": "<string>",
      "resultSchema": {},
      "result": {},
      "cause": {
        "code": "<string>",
        "message": "<string>"
      },
      "startedAt": "2023-11-07T05:31:56Z",
      "endedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "limit": 123,
  "nextCursor": "<string>"
}

Authorizations

​
X-BB-API-Key
string
header
required

Your Browserbase API Key.

Query Parameters

​
status
enum<string>

Current status of the run.

  • PENDING - agent will run soon
  • RUNNING - agent is currently running
  • COMPLETED - agent has finished running
  • FAILED - agent has failed the run
  • STOPPED - run was stopped by the user
  • TIMED_OUT - run exceeded maximum time
Available options:
PENDING,
RUNNING,
COMPLETED,
FAILED,
STOPPED,
TIMED_OUT
​
agentId
string

Only return runs that reference this agent ID.

​
startAt
string<date-time>

Only return runs created on or after this timestamp (inclusive). ISO 8601 / RFC 3339, e.g. 2026-01-19T00:00:00Z.

​
endAt
string<date-time>

Only return runs created on or before this timestamp (inclusive). ISO 8601 / RFC 3339, e.g. 2026-01-20T00:00:00Z.

​
limit
integer
default:20

Maximum number of results to return.

Required range: 1 <= x <= 1000
​
cursor
string

Pagination cursor. Pass the nextCursor from the previous response to fetch the next page. Omit to start from the first page.

Response

200 - application/json

The page of matching agent runs.

A page of agent runs.

​
data
object[]
required

The page of matching agent runs.

​
limit
integer
required

The maximum number of results returned in this page.

​
nextCursor
string
required

Cursor for the next page. Pass it back as cursor on the next request to continue paging. null when there are no more results.