openapi: 3.0.0 info: title: Browserbase API description: Browserbase API for 3rd party developers version: v1 servers: - url: "https://api.browserbase.com" description: Public endpoint variables: {} paths: /v1/agents: post: operationId: Agents_create summary: Create an Agent description: Create a reusable agent. An agent defines a `systemPrompt` and `resultSchema` that guide its behavior for every run. Only `name` is required; an agent created with no `systemPrompt` behaves like an unconfigured run. requestBody: required: true content: application/json: schema: type: object properties: name: description: Human-readable name for the agent. Used to identify the agent in the dashboard and API responses. type: string maxLength: 255 minLength: 1 systemPrompt: description: System prompt that steers the agent's behavior on every run that uses this agent. type: string minLength: 1 resultSchema: description: "An optional [JSON Schema](https://json-schema.org/specification) object. If provided, runs that reference this agent will aim to return a `result` that conforms to this schema when they complete. Can be overridden per run by passing `resultSchema` on the run request." type: object additionalProperties: true properties: {} additionalProperties: false required: - name responses: "201": description: The agent has been created. content: application/json: schema: $ref: "#/components/schemas/Agent" x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const agent = await bb.agents.create({ name: "Job Finder", systemPrompt: "Use official company career pages.", }); console.log(agent); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) agent = bb.agents.create( name="Job Finder", system_prompt="Use official company career pages.", ) print(agent) - lang: bash label: cURL source: |- curl --request POST \ --url https://api.browserbase.com/v1/agents \ --header 'Content-Type: application/json' \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" \ --data '{ "name": "Job Finder", "systemPrompt": "Use official company career pages." }' get: operationId: Agents_list summary: List Agents description: List agents across your account. Supports filtering by creation time. parameters: - name: startAt in: query description: "Only return agents created on or after this timestamp (inclusive). ISO 8601 / RFC 3339, e.g. 2026-01-19T00:00:00Z." required: false schema: type: string format: date-time - name: endAt in: query description: "Only return agents created on or before this timestamp (inclusive). ISO 8601 / RFC 3339, e.g. 2026-01-20T00:00:00Z." required: false schema: type: string format: date-time - name: limit in: query description: Maximum number of results to return. required: false schema: type: integer default: 20 maximum: 1000 minimum: 1 - name: cursor in: query description: Pagination cursor. Pass the nextCursor from the previous response to fetch the next page. Omit to start from the first page. required: false schema: type: string responses: "200": description: The page of matching agents. content: application/json: schema: description: A page of agents. type: object properties: data: description: The page of matching agents. type: array items: $ref: "#/components/schemas/Agent" limit: description: The maximum number of results returned in this page. type: integer nextCursor: description: Cursor for the next page. Pass it back as `cursor` on the next request to continue paging. null when there are no more results. anyOf: - type: string nullable: true required: - data - limit - nextCursor x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const agents = await bb.agents.list({ limit: 20 }); console.log(agents); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) agents = bb.agents.list(limit=20) print(agents) - lang: bash label: cURL source: |- curl --request GET \ --url 'https://api.browserbase.com/v1/agents?limit=20' \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" /v1/agents/runs: post: operationId: AgentRuns_create summary: Run an Agent description: "Run a browser agent to complete the `task` by using web search and browser tooling. Optionally pass `agentId` to run a [custom agent](/reference/api/create-an-agent) you've created." requestBody: required: true content: application/json: schema: type: object properties: agentId: description: "Optionally run a specific [custom agent](/reference/api/create-an-agent) you've created by ID. The run will use the agent's `systemPrompt` and `resultSchema` unless overridden." type: string task: description: A natural language description of the task the agent should accomplish. type: string minLength: 1 resultSchema: description: "An optional [JSON Schema](https://json-schema.org/specification) object. If provided, the agent will aim to return a `result` that conforms to this schema when the run completes. Overrides the referenced agent's default `resultSchema` for this run only." type: object additionalProperties: true properties: {} browserSettings: description: "Browser configuration for the agent's session. When omitted, runner defaults apply." type: object additionalProperties: false properties: context: type: object additionalProperties: false properties: id: description: The Context ID. type: string persist: description: Whether to persist the context after browsing. Defaults to false. type: boolean required: - id proxies: description: "Proxy configuration. Can be true for default proxy, or an array of proxy configurations." anyOf: - type: array items: anyOf: - $ref: "#/components/schemas/BrowserbaseProxyConfig" - $ref: "#/components/schemas/ExternalProxyConfig" - $ref: "#/components/schemas/NoneProxyConfig" - type: boolean verified: description: Set true to enable Browserbase Verified for the session. type: boolean variables: description: "Optional named variables the agent can reference as placeholders, i.e. `%variable%`. Each entry pairs a `value` the placeholder resolves to with an optional `description` that hints to the agent when it should be used. Values are not persisted." type: object additionalProperties: additionalProperties: false type: object properties: value: description: The value the placeholder resolves to when the agent uses it. type: string description: description: Optional hint to the agent describing what this variable represents and when to use it. type: string required: - value additionalProperties: false required: - task responses: "201": description: The agent run has been created in `pending` state. content: application/json: schema: $ref: "#/components/schemas/AgentRun" x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const run = await bb.agents.runs.create({ agentId: "agent-id", task: "Find the pricing page on example.com.", }); console.log(run); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) run = bb.agents.runs.create( agent_id="agent-id", task="Find the pricing page on example.com.", ) print(run) - lang: bash label: cURL source: |- curl --request POST \ --url https://api.browserbase.com/v1/agents/runs \ --header 'Content-Type: application/json' \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" \ --data '{ "agentId": "agent-id", "task": "Find the pricing page on example.com." }' get: operationId: AgentRuns_list summary: List Runs description: "List runs across your account. Supports filtering by status, by the agent they reference, and by creation time." parameters: - name: status in: query description: |- 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 required: false schema: type: string enum: - PENDING - RUNNING - COMPLETED - FAILED - STOPPED - TIMED_OUT - name: agentId in: query description: Only return runs that reference this agent ID. required: false schema: type: string - name: startAt in: query description: "Only return runs created on or after this timestamp (inclusive). ISO 8601 / RFC 3339, e.g. 2026-01-19T00:00:00Z." required: false schema: type: string format: date-time - name: endAt in: query description: "Only return runs created on or before this timestamp (inclusive). ISO 8601 / RFC 3339, e.g. 2026-01-20T00:00:00Z." required: false schema: type: string format: date-time - name: limit in: query description: Maximum number of results to return. required: false schema: type: integer default: 20 maximum: 1000 minimum: 1 - name: cursor in: query description: Pagination cursor. Pass the nextCursor from the previous response to fetch the next page. Omit to start from the first page. required: false schema: type: string responses: "200": description: The page of matching agent runs. content: application/json: schema: description: A page of agent runs. type: object properties: data: description: The page of matching agent runs. type: array items: $ref: "#/components/schemas/AgentRun" limit: description: The maximum number of results returned in this page. type: integer nextCursor: description: Cursor for the next page. Pass it back as `cursor` on the next request to continue paging. null when there are no more results. anyOf: - type: string nullable: true required: - data - limit - nextCursor x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const runs = await bb.agents.runs.list({ status: "COMPLETED", limit: 20, }); console.log(runs); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) runs = bb.agents.runs.list(status="COMPLETED", limit=20) print(runs) - lang: bash label: cURL source: |- curl --request GET \ --url https://api.browserbase.com/v1/agents/runs \ --get \ --data-urlencode 'status=COMPLETED' \ --data-urlencode 'limit=20' \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" "/v1/agents/runs/{runId}": get: operationId: AgentRuns_get summary: Get a Run description: "Retrieve the current status and details of a run, including its result and associated session information. To fetch the run's messages, use [List Run Messages](/reference/api/list-run-messages)." parameters: - name: runId in: path description: The run ID. required: true schema: type: string responses: "200": description: The agent run. content: application/json: schema: $ref: "#/components/schemas/AgentRun" x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const run = await bb.agents.runs.retrieve("run-id"); console.log(run); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) run = bb.agents.runs.retrieve("run-id") print(run) - lang: bash label: cURL source: |- curl --request GET \ --url https://api.browserbase.com/v1/agents/runs/run-id \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" "/v1/agents/runs/{runId}/messages": get: operationId: AgentRuns_messages summary: List Run Messages description: |- Returns a paginated list of messages produced by a run, in chronological order, with the oldest messages first. Messages conform to the [AI SDK UIMessage format](https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message). parameters: - name: since in: query description: "The `id` of the last message you've already received. The response will contain messages produced after that one, in chronological order. Omit on the first call. Pass the previous response's `nextSince` value to continue paging or to poll for new messages." required: false schema: type: string - name: limit in: query description: Maximum number of messages to return. required: false schema: type: integer default: 20 maximum: 100 minimum: 1 - name: all in: query description: "Return every message after `since` in one response, ignoring `limit`." required: false schema: type: boolean default: false - name: runId in: path description: The run ID. required: true schema: type: string format: uuid responses: "200": description: "The page of messages, in chronological order, with the oldest messages first." content: application/json: schema: type: object properties: data: description: "The page of messages, in chronological order, with the oldest messages first." type: array items: type: object required: - id - createdAt - message properties: id: type: string createdAt: type: string format: date-time message: description: An AI SDK response message (assistant or tool). type: object additionalProperties: true properties: role: type: string enum: - assistant - tool content: description: Plain string (assistant text) or an array of typed parts. oneOf: - type: string - type: array items: type: object required: - type additionalProperties: true properties: type: description: text | reasoning | file | tool-call | tool-result type: string text: type: string toolCallId: type: string toolName: type: string input: {} output: {} mediaType: type: string data: type: string required: - role - content nextSince: description: "The `id` of the last message in `data`. Pass it back as `since` on the next request to continue paging, or to poll for new messages. `null` only when the run has no messages yet; in that case, omit `since` and retry." type: string nullable: true required: - data - nextSince x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const messages = await bb.agents.runs.listMessages("run-id", { limit: 20, }); console.log(messages); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) messages = bb.agents.runs.list_messages("run-id", limit=20) print(messages) - lang: bash label: cURL source: |- curl --request GET \ --url https://api.browserbase.com/v1/agents/runs/run-id/messages \ --get \ --data-urlencode 'limit=20' \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" "/v1/agents/runs/{runId}/stop": post: operationId: AgentRuns_stop summary: Stop a Run description: Request that an in-progress run stop. The run winds down and transitions to `STOPPED`. Stopping a run that has already finished returns a conflict. parameters: - name: runId in: path description: The run ID. required: true schema: type: string responses: "202": description: The stop has been requested. Poll the run until its status is `STOPPED` to confirm it wound down. content: application/json: schema: $ref: "#/components/schemas/AgentRun" x-codeSamples: - lang: bash label: cURL source: |- curl --request POST \ --url https://api.browserbase.com/v1/agents/runs/run-id/stop \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" "/v1/agents/{agentId}": get: operationId: Agents_get summary: Get an Agent description: Retrieve an agent by ID. parameters: - name: agentId in: path description: The agent ID. required: true schema: type: string responses: "200": description: The agent. content: application/json: schema: $ref: "#/components/schemas/Agent" x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const agent = await bb.agents.retrieve("agent-id"); console.log(agent); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) agent = bb.agents.retrieve("agent-id") print(agent) - lang: bash label: cURL source: |- curl --request GET \ --url https://api.browserbase.com/v1/agents/agent-id \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" patch: operationId: Agents_update summary: Update an Agent description: Update an existing agent. Only the fields provided in the body are modified; omitted fields are left unchanged. parameters: - name: agentId in: path description: The agent ID. required: true schema: type: string requestBody: content: application/json: schema: type: object properties: name: description: Human-readable name for the agent. Used to identify the agent in the dashboard and API responses. type: string maxLength: 255 minLength: 1 systemPrompt: description: New system prompt that steers the agent's behavior on every run that uses this agent. type: string minLength: 1 resultSchema: description: "An optional [JSON Schema](https://json-schema.org/specification) object. If provided, runs that reference this agent will aim to return a `result` that conforms to this schema when they complete. Can be overridden per run by passing `resultSchema` on the run request." type: object additionalProperties: true properties: {} additionalProperties: false responses: "200": description: The updated agent. content: application/json: schema: $ref: "#/components/schemas/Agent" x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const agent = await bb.agents.update("agent-id", { name: "Official Job Finder", }); console.log(agent); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) agent = bb.agents.update("agent-id", name="Official Job Finder") print(agent) - lang: bash label: cURL source: |- curl --request PATCH \ --url https://api.browserbase.com/v1/agents/agent-id \ --header 'Content-Type: application/json' \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" \ --data '{"name":"Official Job Finder"}' delete: operationId: Agents_delete summary: Delete an Agent description: Delete an agent. Runs that already referenced this agent are unaffected. parameters: - name: agentId in: path description: The agent ID. required: true schema: type: string responses: "204": description: "The agent has been deleted. Idempotent: deleting an already-deleted or non-existent agent returns 204." x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); await bb.agents.delete("agent-id"); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) bb.agents.delete("agent-id") - lang: bash label: cURL source: |- curl --request DELETE \ --url https://api.browserbase.com/v1/agents/agent-id \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" /v1/certificates: post: operationId: Certificates_upload summary: Upload a Certificate requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary required: - file responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/Certificate" get: operationId: Certificates_list summary: List Certificates responses: "200": description: The request has succeeded. content: application/json: schema: type: array items: $ref: "#/components/schemas/Certificate" "/v1/certificates/{id}": get: operationId: Certificates_get summary: Get a Certificate parameters: - name: id in: path required: true schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/Certificate" delete: operationId: Certificates_delete summary: Delete a Certificate parameters: - name: id in: path required: true schema: type: string responses: "204": description: "There is no content to send for this request, but the headers may be useful." /v1/contexts: post: operationId: Contexts_create summary: Create a Context requestBody: content: application/json: schema: type: object properties: projectId: description: "The Project ID. Can be found in [Settings](https://www.browserbase.com/settings). Optional - if not provided, the project will be inferred from the API key." type: string name: description: "Optional user-defined name for the Context. Leading and trailing whitespace is trimmed before storage. Names are unique within the project among active Contexts, compared case-insensitively." type: string maxLength: 128 minLength: 1 responses: "201": description: The request has succeeded and a new resource has been created as a result. content: application/json: schema: type: object properties: id: type: string publicKey: description: The public key to encrypt the user-data-directory. type: string cipherAlgorithm: description: The cipher algorithm used to encrypt the user-data-directory. AES-256-CBC is currently the only supported algorithm. type: string initializationVectorSize: description: "The initialization vector size used to encrypt the user-data-directory. [Read more about how to use it](/features/contexts)." type: integer format: uint8 required: - id - publicKey - cipherAlgorithm - initializationVectorSize "/v1/contexts/{id}": get: operationId: Contexts_get summary: Get a Context parameters: - name: id in: path required: true schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/Context" delete: operationId: Contexts_delete summary: Delete a Context parameters: - name: id in: path required: true schema: type: string responses: "204": description: "There is no content to send for this request, but the headers may be useful." /v1/downloads: get: operationId: Downloads_list summary: List Downloads description: List all downloads for a session with optional filtering and pagination. parameters: - name: sessionId in: query description: Filter downloads by session ID (required). required: true schema: type: string - name: filename in: query description: Filter by exact filename match. required: false schema: type: string maxLength: 255 - name: mimeType in: query description: Filter by MIME type. required: false schema: type: string maxLength: 255 - name: minSize in: query description: Minimum file size in bytes. required: false schema: type: number minimum: 0 - name: maxSize in: query description: Maximum file size in bytes. required: false schema: type: number minimum: 0 - name: createdAfter in: query description: Filter downloads created on or after this timestamp. required: false schema: type: string format: date-time - name: createdBefore in: query description: Filter downloads created on or before this timestamp. required: false schema: type: string format: date-time - name: limit in: query description: Maximum number of results to return. required: false schema: type: number default: 20 maximum: 100 minimum: 1 - name: offset in: query description: Number of results to skip for pagination. required: false schema: type: number default: 0 minimum: 0 responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: downloads: type: array items: type: object properties: id: description: Unique identifier for the download. type: string sessionId: description: The Session ID this download belongs to. type: string filename: description: The filename of the downloaded file. type: string mimeType: description: The MIME type of the file. type: string size: description: File size in bytes. type: number checksum: description: SHA256 checksum of the file. type: string createdAt: description: Timestamp when the file was downloaded. type: string format: date-time required: - id - sessionId - filename - mimeType - size - checksum - createdAt total: description: Total count of matching downloads. type: number limit: type: number offset: type: number required: - downloads - total - limit - offset "/v1/downloads/{id}": get: operationId: Downloads_get summary: Get a Download description: "Get download metadata (Accept: application/json) or file content (Accept: application/octet-stream)." parameters: - name: id in: path description: The download ID. required: true schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: id: description: Unique identifier for the download. type: string sessionId: description: The Session ID this download belongs to. type: string filename: description: The filename of the downloaded file. type: string mimeType: description: The MIME type of the file. type: string size: description: File size in bytes. type: number checksum: description: SHA256 checksum of the file. type: string createdAt: description: Timestamp when the file was downloaded. type: string format: date-time required: - id - sessionId - filename - mimeType - size - checksum - createdAt application/octet-stream: schema: type: string format: binary delete: operationId: Downloads_delete summary: Delete a Download description: Delete a download file from storage and mark as deleted. parameters: - name: id in: path description: The download ID to delete. required: true schema: type: string responses: "204": description: There is no content to send for this request. /v1/extensions: post: operationId: Extensions_upload summary: Upload an Extension requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary required: - file responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/Extension" "/v1/extensions/{id}": get: operationId: Extensions_get summary: Get an Extension parameters: - name: id in: path required: true schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/Extension" delete: operationId: Extensions_delete summary: Delete an Extension parameters: - name: id in: path required: true schema: type: string responses: "204": description: "There is no content to send for this request, but the headers may be useful." /v1/fetch: post: operationId: Fetch_create summary: Fetch a Page description: "Fetch a page and return its content, headers, and metadata." requestBody: required: true content: application/json: schema: type: object properties: url: description: The URL to fetch type: string format: uri allowRedirects: description: Whether to follow HTTP redirects type: boolean default: false allowInsecureSsl: description: Whether to bypass TLS certificate verification type: boolean default: false proxies: description: Whether to enable proxy support for the request type: boolean default: false format: description: Output format for the response content. `raw` (default) returns the response body unchanged; `json` returns structured data (requires `schema`); `markdown` returns the page as markdown. default: raw anyOf: - type: string enum: - raw - type: string enum: - json - type: string enum: - markdown schema: description: JSON Schema describing the desired structure of the response. Only used when `format` is `json`. type: object additionalProperties: {} required: - url responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: id: description: Unique identifier for the fetch request type: string statusCode: description: HTTP status code of the fetched response type: integer headers: description: Response headers as key-value pairs type: object additionalProperties: type: string content: anyOf: - type: string - type: object additionalProperties: {} description: The response body content. A string for `raw` and `markdown` formats; a structured object for `json` format (the schema-extracted result). contentType: description: The MIME type of the response type: string encoding: description: The character encoding of the response type: string required: - id - statusCode - headers - content - contentType - encoding "400": description: "Invalid request body, or the requested `format` is not supported for the fetched response's content type." content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string id: description: Unique identifier for the fetch request type: string required: - statusCode - error - message "402": description: Free plan quota exceeded for the requested format. content: application/json: schema: description: Free plan quota exceeded for the requested format. "403": description: Project is not enabled for the requested format. Only `raw` is available without enablement. content: application/json: schema: description: Project is not enabled for the requested format. Only `raw` is available without enablement. "429": description: Concurrent fetch request limit exceeded. content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string id: description: Unique identifier for the fetch request type: string required: - statusCode - error - message "502": description: The fetched response was too large or TLS certificate verification failed. content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string id: description: Unique identifier for the fetch request type: string required: - statusCode - error - message - id "503": description: The fetch service is temporarily unavailable. content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string id: description: Unique identifier for the fetch request type: string required: - statusCode - error - message - id "504": description: The fetch request timed out. content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string id: description: Unique identifier for the fetch request type: string required: - statusCode - error - message - id /v1/functions: get: operationId: Functions_list summary: List Functions parameters: - name: offset in: query required: false schema: type: integer default: 0 minimum: 0 - name: limit in: query required: false schema: type: integer default: 20 maximum: 100 minimum: 1 responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Function" total: type: integer minimum: 0 required: - data - total /v1/functions/builds: get: operationId: FunctionBuilds_list summary: List Function Builds parameters: - name: offset in: query required: false schema: type: integer default: 0 minimum: 0 - name: limit in: query required: false schema: type: integer default: 20 maximum: 100 minimum: 1 - name: status in: query required: false schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/FunctionBuild" total: type: integer minimum: 0 required: - data - total "/v1/functions/builds/{id}": get: operationId: FunctionBuilds_get summary: Get a Function Build parameters: - name: id in: path required: true schema: type: string format: uuid responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/FunctionBuild" "/v1/functions/builds/{id}/logs": get: operationId: FunctionBuilds_getLogs summary: Get Function Build Logs parameters: - name: id in: path required: true schema: type: string format: uuid responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: logs: type: array items: $ref: "#/components/schemas/FunctionBuildLog" total: type: integer minimum: 0 required: - logs - total "/v1/functions/invocations/{id}": get: operationId: Invocations_get summary: Get an Invocation parameters: - name: id in: path required: true schema: type: string format: uuid responses: "200": description: The request has succeeded. content: application/json: schema: allOf: - $ref: "#/components/schemas/Invocation" - type: object properties: cause: type: object properties: code: type: string enum: - TIMED_OUT - INTERNAL_ERROR - WORKLOAD_ERROR message: type: string minLength: 1 required: - code "/v1/functions/invocations/{id}/logs": get: operationId: Invocations_getLogs summary: Get Invocation Logs parameters: - name: id in: path required: true schema: type: string format: uuid responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: logs: type: array items: $ref: "#/components/schemas/InvocationLog" total: type: integer minimum: 0 required: - logs - total "/v1/functions/versions/{id}": get: operationId: FunctionVersions_get summary: Get a Function Version parameters: - name: id in: path required: true schema: type: string format: uuid responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/FunctionVersion" "/v1/functions/versions/{id}/invocations": get: operationId: FunctionVersions_listInvocations summary: List Invocations for a Function Version parameters: - name: offset in: query required: false schema: type: integer default: 0 minimum: 0 - name: limit in: query required: false schema: type: integer default: 20 maximum: 100 minimum: 1 - name: status in: query required: false schema: type: string - name: id in: path required: true schema: type: string format: uuid responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: results: type: array items: $ref: "#/components/schemas/Invocation" total: type: integer minimum: 0 required: - results - total "/v1/functions/{id}": get: operationId: Functions_get summary: Get a Function parameters: - name: id in: path required: true schema: type: string format: uuid responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/Function" "/v1/functions/{id}/invoke": post: operationId: Functions_invoke summary: Invoke a Function parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: content: application/json: schema: type: object properties: params: description: JSON object that can be stored in a JSONB column type: object additionalProperties: true properties: {} sessionCreateParams: type: object properties: extensionId: description: "The uploaded Extension ID. See [Upload Extension](/reference/api/upload-an-extension)." type: string browserSettings: type: object properties: context: type: object properties: id: description: The Context ID. type: string persist: description: Whether or not to persist the context after browsing. Defaults to `false`. type: boolean required: - id extensionId: description: "The uploaded Extension ID. See [Upload Extension](/reference/api/upload-an-extension)." type: string viewport: type: object properties: width: description: The width of the browser. type: integer height: description: The height of the browser. type: integer blockAds: description: Enable or disable ad blocking in the browser. Defaults to `false`. type: boolean solveCaptchas: description: Enable or disable captcha solving in the browser. Defaults to `true`. type: boolean recordSession: description: Enable or disable session recording. Defaults to `true`. type: boolean logSession: description: Enable or disable session logging. Defaults to `true`. type: boolean advancedStealth: description: Advanced Browser Stealth Mode type: boolean verified: description: Verified Browser Mode type: boolean captchaImageSelector: description: "Custom selector for captcha image. See [Custom Captcha Solving](/features/stealth-mode#custom-captcha-solving)" type: string captchaInputSelector: description: "Custom selector for captcha input. See [Custom Captcha Solving](/features/stealth-mode#custom-captcha-solving)" type: string os: description: "Operating system for stealth mode. Valid values: windows, mac, linux, mobile, tablet" type: string enum: - windows - mac - linux - mobile - tablet size: description: "[NOT IN DOCS] Resource size of the browser." type: string default: small enum: - small - medium - large enableNativeSelectPolyfill: description: "[NOT IN DOCS] Enable native select polyfill. This gives support a break-glass option to disable the polyfill." type: boolean enablePdfViewer: description: "[NOT IN DOCS] Enable PDF viewer. This gives support a break-glass option to enable the viewer when users want to view PDFs in-browser." type: boolean extensions: description: "[NOT IN DOCS] List of pre-installed extension names and custom extension ids to enable on the browser" type: array items: type: string enum: - onepassword - browser-events default: [] allowedDomains: description: "An optional list of allowed domains for the session. If you pass one or more domains, Browserbase restricts top-level (main-frame) page navigations to the listed domains and their subdomains. For example, `example.com` also permits `www.example.com` and `a.b.example.com`, but not `notexample.com`. Matching is domain-based, not full-URL. An empty list (the default) disables the restriction entirely. Browserbase enforces only main-frame navigations; it does not block iframe/subframe loads or other in-page resource requests (images, scripts, XHR, etc.)." type: array items: type: string default: [] ignoreCertificateErrors: description: Enable or disable ignoring of certificate errors in the browser. Defaults to `true`. type: boolean proxies: description: "Proxy configuration. Can be true for default proxy, or an array of proxy configurations." anyOf: - type: array items: anyOf: - $ref: "#/components/schemas/BrowserbaseProxyConfig" - $ref: "#/components/schemas/ExternalProxyConfig" - $ref: "#/components/schemas/NoneProxyConfig" - type: boolean proxySettings: description: Supplementary proxy settings. Optional. type: object properties: caCertificates: description: The TLS certificate IDs to trust. Optional. type: array items: format: uuid description: The TLS certificate ID to trust. type: string default: [] userMetadata: description: "Arbitrary user metadata to attach to the session. To learn more about user metadata, see [User Metadata](/features/sessions#user-metadata)." type: object additionalProperties: true properties: {} timeout: description: Duration in seconds after which the function invocation will automatically end. Defaults to 900 (15 minutes). type: integer default: 900 maximum: 900 minimum: 60 responses: "202": description: "The request has been accepted for processing, but processing has not yet completed." content: application/json: schema: $ref: "#/components/schemas/Invocation" "/v1/functions/{id}/versions": get: operationId: Functions_listVersions summary: List Function Versions parameters: - name: offset in: query required: false schema: type: integer default: 0 minimum: 0 - name: limit in: query required: false schema: type: integer default: 20 maximum: 100 minimum: 1 - name: id in: path required: true schema: type: string format: uuid responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: results: type: array items: $ref: "#/components/schemas/FunctionVersion" total: type: integer minimum: 0 required: - results - total /v1/projects: get: operationId: Projects_list summary: List Projects responses: "200": description: The request has succeeded. content: application/json: schema: type: array items: $ref: "#/components/schemas/Project" "/v1/projects/{id}": get: operationId: Projects_get summary: Get a Project parameters: - name: id in: path required: true schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/Project" "/v1/projects/{id}/usage": get: operationId: Projects_usage summary: Get Project Usage parameters: - name: id in: path required: true schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/ProjectUsage" /v1/search: post: operationId: Search_web summary: Web Search description: Perform a web search and return structured results. requestBody: required: true content: application/json: schema: type: object properties: query: description: The search query string type: string maxLength: 200 minLength: 1 numResults: description: Number of results to return (1-25) type: integer default: 10 maximum: 25 minimum: 1 required: - query responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: requestId: description: Unique identifier for the request type: string query: description: The search query that was executed type: string results: description: List of search results type: array items: type: object properties: id: description: Unique identifier for the result type: string url: description: The URL of the search result type: string title: description: The title of the search result type: string author: description: Author of the content if available type: string publishedDate: description: Publication date in ISO 8601 format type: string format: date-time image: description: Image URL if available type: string favicon: description: Favicon URL type: string required: - id - url - title required: - requestId - query - results /v1/sessions: get: operationId: Sessions_list summary: List Sessions parameters: - name: status in: query required: false schema: type: string enum: - PENDING - RUNNING - ERROR - TIMED_OUT - COMPLETED - name: q in: query description: "Query sessions by user metadata. See [Querying Sessions by User Metadata](/features/sessions#querying-sessions-by-user-metadata) for the schema of this query." required: false schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: type: array items: $ref: "#/components/schemas/Session" post: operationId: Sessions_create summary: Create a Session requestBody: content: application/json: schema: type: object properties: projectId: description: "The Project ID. Can be found in [Settings](https://www.browserbase.com/settings). Optional - if not provided, the project will be inferred from the API key." type: string extensionId: description: "The uploaded Extension ID. See [Upload Extension](/reference/api/upload-an-extension)." type: string browserSettings: type: object properties: context: type: object properties: id: description: The Context ID. type: string persist: description: Whether or not to persist the context after browsing. Defaults to `false`. type: boolean required: - id extensionId: description: "The uploaded Extension ID. See [Upload Extension](/reference/api/upload-an-extension)." type: string viewport: type: object properties: width: description: The width of the browser. type: integer height: description: The height of the browser. type: integer blockAds: description: Enable or disable ad blocking in the browser. Defaults to `false`. type: boolean solveCaptchas: description: Enable or disable captcha solving in the browser. Defaults to `true`. type: boolean recordSession: description: Enable or disable session recording. Defaults to `true`. type: boolean logSession: description: Enable or disable session logging. Defaults to `true`. type: boolean advancedStealth: description: Advanced Browser Stealth Mode type: boolean verified: description: Verified Browser Mode type: boolean captchaImageSelector: description: "Custom selector for captcha image. See [Custom Captcha Solving](/features/stealth-mode#custom-captcha-solving)" type: string captchaInputSelector: description: "Custom selector for captcha input. See [Custom Captcha Solving](/features/stealth-mode#custom-captcha-solving)" type: string os: description: "Operating system for stealth mode. Valid values: windows, mac, linux, mobile, tablet" type: string enum: - windows - mac - linux - mobile - tablet allowedDomains: description: "An optional list of allowed domains for the session. If you pass one or more domains, Browserbase restricts top-level (main-frame) page navigations to the listed domains and their subdomains. For example, `example.com` also permits `www.example.com` and `a.b.example.com`, but not `notexample.com`. Matching is domain-based, not full-URL. An empty list (the default) disables the restriction entirely. Browserbase enforces only main-frame navigations; it does not block iframe/subframe loads or other in-page resource requests (images, scripts, XHR, etc.)." type: array items: type: string default: [] ignoreCertificateErrors: description: Enable or disable ignoring of certificate errors in the browser. Defaults to `true`. type: boolean timeout: description: "Duration in seconds after which the session will automatically end. Defaults to the Project's `defaultTimeout`. Minimum 60 seconds, maximum 21600 seconds (6 hours)." type: integer maximum: 21600 minimum: 60 x-stainless-param: api_timeout keepAlive: description: Set to true to keep the session alive even after disconnections. Available on the Hobby Plan and above. type: boolean proxies: description: "Proxy configuration. Can be true for default proxy, or an array of proxy configurations." anyOf: - type: array items: anyOf: - $ref: "#/components/schemas/BrowserbaseProxyConfig" - $ref: "#/components/schemas/ExternalProxyConfig" - $ref: "#/components/schemas/NoneProxyConfig" - type: boolean proxySettings: description: Supplementary proxy settings. Optional. type: object properties: caCertificates: description: The TLS certificate IDs to trust. Optional. type: array items: format: uuid description: The TLS certificate ID to trust. type: string default: [] region: description: The region where the Session should run. type: string default: us-west-2 enum: - us-west-2 - us-east-1 - eu-central-1 - ap-southeast-1 userMetadata: description: "Arbitrary user metadata to attach to the session. To learn more about user metadata, see [User Metadata](/features/sessions#user-metadata)." type: object additionalProperties: true properties: {} responses: "201": description: The request has succeeded and a new resource has been created as a result. content: application/json: schema: allOf: - $ref: "#/components/schemas/Session" - type: object properties: connectUrl: description: WebSocket URL to connect to the Session. type: string format: uri seleniumRemoteUrl: description: HTTP URL to connect to the Session. type: string format: uri signingKey: description: Signing key to use when connecting to the Session via HTTP. type: string required: - connectUrl - seleniumRemoteUrl - signingKey x-codeSamples: - lang: cURL source: |- curl --request POST \ --url https://api.browserbase.com/v1/sessions \ --header 'Content-Type: application/json' \ --header 'X-BB-API-Key: ' \ --data '{}' - lang: JavaScript source: |- fetch('https://api.browserbase.com/v1/sessions', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-BB-API-Key': '' }, body: JSON.stringify({}) }) - lang: Python source: |- import requests url = "https://api.browserbase.com/v1/sessions" payload = {} headers = { "X-BB-API-Key": "", "Content-Type": "application/json" } response = requests.request("POST", url, json=payload, headers=headers) print(response.text) - lang: PHP source: |- "https://api.browserbase.com/v1/sessions", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => "{}", CURLOPT_HTTPHEADER => [ "Content-Type: application/json", "X-BB-API-Key: " ], ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; } - lang: Go source: "package main\n\nimport (\n\t\"fmt\"\n\t\"strings\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.browserbase.com/v1/sessions\"\n\n\tpayload := strings.NewReader(\"{}\")\n\n\treq, _ := http.NewRequest(\"POST\", url, payload)\n\n\treq.Header.Add(\"X-BB-API-Key\", \"\")\n\treq.Header.Add(\"Content-Type\", \"application/json\")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}" - lang: Java source: |- HttpResponse response = Unirest.post("https://api.browserbase.com/v1/sessions") .header("X-BB-API-Key", "") .header("Content-Type", "application/json") .body("{}") .asString(); "/v1/sessions/{id}": get: operationId: Sessions_get summary: Get a Session parameters: - name: id in: path required: true schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: allOf: - $ref: "#/components/schemas/Session" - type: object properties: connectUrl: description: WebSocket URL to connect to the Session. type: string format: uri seleniumRemoteUrl: description: HTTP URL to connect to the Session. type: string format: uri signingKey: description: Signing key to use when connecting to the Session via HTTP. type: string post: operationId: Sessions_update summary: Update a Session parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: status: description: Set to `REQUEST_RELEASE` to request that the session complete. Use before session's timeout to avoid additional charges. type: string enum: - REQUEST_RELEASE required: - status responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/Session" "/v1/sessions/{id}/debug": get: operationId: Sessions_getDebug summary: Session Live URLs parameters: - name: id in: path required: true schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/SessionLiveUrls" "/v1/sessions/{id}/logs": get: operationId: Sessions_getLogs summary: Session Logs parameters: - name: id in: path required: true schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: type: array items: $ref: "#/components/schemas/SessionLog" "/v1/sessions/{id}/recording": get: operationId: Sessions_getRecording summary: Session Recording parameters: - name: id in: path required: true schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: type: array items: $ref: "#/components/schemas/SessionRecording" "/v1/sessions/{id}/recording/downloads": post: operationId: Sessions_createRecordingDownloads summary: Create Session Recording Downloads description: "Requests one downloadable MP4 per recorded page of a session. Assembly runs asynchronously and every page returns as `PENDING`. Re-posting re-enqueues all pages and retries any that failed. Poll the GET endpoint for per-page status and, on standard (non-BYOS) projects, download URLs." parameters: - name: id in: path description: Session ID required: true schema: type: string format: uuid responses: "202": description: Downloads enqueued. Poll the GET endpoint for status. content: application/json: schema: type: object properties: downloads: type: array items: $ref: "#/components/schemas/RecordingDownload" required: - downloads "404": description: "The session was not found, or it has no recording." content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string required: - statusCode - error - message "409": description: The session has not ended. Recording downloads are available only after a session completes. content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string required: - statusCode - error - message "410": description: The session's recording has aged out of its retention window and can no longer be assembled. content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string required: - statusCode - error - message "422": description: "Recording was disabled for this session (`recordSession: false`), so there is nothing to assemble." content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string required: - statusCode - error - message "502": description: Failed to reach the recording service. Retry the request. content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string required: - statusCode - error - message get: operationId: Sessions_listRecordingDownloads summary: List Session Recording Downloads description: "Returns the per-page download status for a session, with a short-lived signed URL for each completed page on standard (non-BYOS) projects." parameters: - name: id in: path description: Session ID required: true schema: type: string format: uuid responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: downloads: type: array items: $ref: "#/components/schemas/RecordingDownload" required: - downloads "404": description: "The session was not found, or it has no recording." content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string required: - statusCode - error - message "409": description: The session has not ended. Recording downloads are available only after a session completes. content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string required: - statusCode - error - message "410": description: The session's recording has aged out of its retention window and can no longer be assembled. content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string required: - statusCode - error - message "422": description: "Recording was disabled for this session (`recordSession: false`), so there is nothing to download." content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string required: - statusCode - error - message "502": description: Failed to reach the recording service. Retry the request. content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string required: - statusCode - error - message "/v1/sessions/{id}/replays": get: operationId: Sessions_getReplay summary: Get Session Replay description: "Returns page metadata for a session replay, including timing information and the URL of each page's HLS playlist." parameters: - name: id in: path description: Session ID required: true schema: type: string format: uuid responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: pages: type: array items: $ref: "#/components/schemas/ReplayPage" pageCount: type: integer required: - pages - pageCount "/v1/sessions/{id}/replays/{pageId}": get: operationId: Sessions_getReplayPage summary: Get Replay Page description: Returns an HLS VOD media playlist (.m3u8) for a specific page of a session replay. parameters: - name: id in: path description: Session ID required: true schema: type: string format: uuid - name: pageId in: path required: true schema: type: string maxLength: 3 pattern: ^\d+$ responses: "200": description: The request has succeeded. content: application/vnd.apple.mpegurl: schema: type: string "/v1/sessions/{id}/uploads": post: operationId: Sessions_uploadFile summary: Create Session Uploads parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary required: - file responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: message: type: string required: - message components: schemas: Agent: description: A reusable agent. Referenced by `agentId` to apply a system prompt to every run that uses the agent. type: object properties: agentId: description: Unique identifier for the agent. Use this value as `agentId` when creating an agent run. type: string name: description: Human-readable name for the agent. Used to identify the agent in the dashboard and API responses. type: string systemPrompt: description: System prompt applied to every run that uses this agent. type: string resultSchema: description: "[JSON Schema](https://json-schema.org/specification) that runs referencing this agent will aim to conform their `result` to. Can be overridden per run by passing `resultSchema` on the run request." type: object additionalProperties: true properties: {} createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - agentId - name - createdAt - updatedAt AgentRun: description: One execution of an agent against a task. Created in `pending` and transitioned through `running` → `completed`/`failed` by the runner. type: object properties: runId: description: Unique identifier for the run. type: string agentId: description: "The ID of the agent applied to this run, if any. Omitted for ad-hoc runs." type: string task: description: The original task description. type: string status: description: |- 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 type: string enum: - PENDING - RUNNING - COMPLETED - FAILED - STOPPED - TIMED_OUT sessionId: description: The Browserbase session ID powering this run. type: string sandboxId: description: External sandbox identifier assigned by the runner. Optional. type: string resultSchema: description: "Per-run [JSON Schema](https://json-schema.org/specification) override for the result shape. When unset, the agent's default `resultSchema` applies." type: object additionalProperties: true properties: {} result: description: "The agent's structured result for the run. Only present when the run has finished and output is available. The result conforms to the provided [JSON Schema](https://json-schema.org/specification) when one is set." type: object additionalProperties: true properties: {} cause: type: object properties: code: description: "Structured failure code (e.g., RUNNER_HEARTBEAT_LOST)." type: string maxLength: 64 message: description: Human-readable failure detail. type: string maxLength: 500 required: - code startedAt: type: string format: date-time endedAt: type: string format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - runId - task - status - createdAt - updatedAt BrowserbaseProxyConfig: type: object properties: type: description: Type of proxy. Always use 'browserbase' for the Browserbase managed proxy network. type: string enum: - browserbase geolocation: description: Geographic location for the proxy. Optional. type: object properties: city: description: Name of the city. Use spaces for multi-word city names. Optional. type: string state: description: US state code (2 characters). Must also specify US as the country. Optional. type: string maxLength: 2 minLength: 2 country: description: Country code in ISO 3166-1 alpha-2 format type: string maxLength: 2 minLength: 2 required: - country domainPattern: description: "Domain pattern for which this proxy should be used. If omitted, defaults to all domains. Optional." type: string required: - type Certificate: type: object properties: id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time projectId: description: The Project ID linked to the uploaded Certificate. type: string required: - id - createdAt - updatedAt - projectId Context: type: object properties: id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time projectId: description: The Project ID linked to the uploaded Context. type: string name: description: "Optional user-defined name for the Context. Leading and trailing whitespace is trimmed before storage. Names are unique within the project among active Contexts, compared case-insensitively." type: string maxLength: 128 minLength: 1 required: - id - createdAt - updatedAt - projectId Extension: type: object properties: id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time fileName: type: string minLength: 1 projectId: description: The Project ID linked to the uploaded Extension. type: string required: - id - createdAt - updatedAt - fileName - projectId ExternalProxyConfig: type: object properties: type: description: Type of proxy. Always 'external' for this config. type: string enum: - external server: description: Server URL for external proxy. Required. type: string domainPattern: description: "Domain pattern for which this proxy should be used. If omitted, defaults to all domains. Optional." type: string username: description: Username for external proxy authentication. Optional. type: string password: description: Password for external proxy authentication. Optional. type: string required: - type - server Function: type: object properties: id: type: string format: uuid projectId: type: string format: uuid name: type: string minLength: 1 createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - projectId - name - createdAt - updatedAt FunctionBuild: type: object properties: id: type: string format: uuid projectId: type: string format: uuid request: type: object properties: entrypoint: type: string minLength: 1 functionNames: type: array items: minLength: 1 type: string required: - entrypoint status: type: string enum: - PENDING - RUNNING - COMPLETED - FAILED createdAt: type: string format: date-time updatedAt: type: string format: date-time startedAt: type: string format: date-time endedAt: type: string format: date-time expiresAt: type: string format: date-time builtFunctions: type: array items: allOf: - $ref: "#/components/schemas/Function" - type: object properties: createdVersion: $ref: "#/components/schemas/FunctionVersion" required: - createdVersion cause: type: object properties: code: type: string enum: - NO_MANIFESTS_FOUND - TOO_MANY_MANIFESTS - MANIFEST_TOO_LARGE - INVALID_SESSION_CREATE_PARAMS - TIMED_OUT message: type: string minLength: 1 required: - code required: - id - projectId - request - status - createdAt - updatedAt - startedAt - expiresAt FunctionBuildLog: type: object properties: message: type: string timestamp: type: number required: - message - timestamp FunctionVersion: type: object properties: id: type: string format: uuid projectId: type: string format: uuid functionId: type: string format: uuid functionBuildId: type: string format: uuid sessionCreateParams: description: JSON object that can be stored in a JSONB column type: object additionalProperties: true properties: {} userParamsSchema: description: JSON object that can be stored in a JSONB column type: object additionalProperties: true properties: {} createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - projectId - functionId - functionBuildId - createdAt - updatedAt Invocation: type: object properties: id: type: string format: uuid projectId: type: string format: uuid functionId: type: string format: uuid versionId: type: string format: uuid sessionId: type: string format: uuid region: type: string minLength: 1 params: description: JSON object that can be stored in a JSONB column type: object additionalProperties: true properties: {} status: type: string enum: - PENDING - RUNNING - COMPLETED - FAILED results: description: Any JSON-serializable value that can be stored in a JSONB column anyOf: - type: string - type: number - type: boolean - type: array items: {} - additionalProperties: true type: object properties: {} nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time startedAt: type: string format: date-time endedAt: type: string format: date-time expiresAt: type: string format: date-time required: - id - projectId - functionId - versionId - sessionId - status - createdAt - updatedAt - startedAt - expiresAt InvocationLog: type: object properties: message: type: string timestamp: type: number required: - message - timestamp NoneProxyConfig: type: object properties: type: description: Type of proxy. Always 'none' for this config. type: string enum: - none domainPattern: description: "Domain pattern for which this proxy should be used. If omitted, defaults to all domains. Optional." type: string required: - type Project: type: object properties: id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time name: type: string minLength: 1 ownerId: type: string defaultTimeout: type: integer maximum: 21600 minimum: 60 concurrency: description: The maximum number of sessions that this project can run concurrently. type: integer minimum: 1 required: - id - createdAt - updatedAt - name - ownerId - defaultTimeout - concurrency ProjectUsage: type: object properties: browserMinutes: type: integer minimum: 0 proxyBytes: type: integer minimum: 0 required: - browserMinutes - proxyBytes RecordingDownload: type: object properties: pageId: description: 'Recorded page (tab) within the session, e.g. "0", "1".' type: string status: $ref: "#/components/schemas/RecordingDownloadStatus" downloadUrl: description: "Short-lived signed CDN URL, re-minted each GET. Present only when COMPLETED on a standard (non-BYOS) project." type: string completedAt: description: When the MP4 was created. Present only when COMPLETED on a standard (non-BYOS) project. type: string format: date-time required: - pageId - status RecordingDownloadStatus: description: "Per-page MP4 assembly state. `NOT_REQUESTED`: no download has been requested for the session yet. `PENDING`: assembly is enqueued or in progress. `COMPLETED`: the MP4 is ready. `FAILED`: assembly failed; POST again to retry." type: string enum: - NOT_REQUESTED - PENDING - COMPLETED - FAILED ReplayPage: type: object properties: pageId: type: string url: type: string startTimeMs: type: integer endTimeMs: type: integer required: - pageId - url - startTimeMs - endTimeMs Session: type: object properties: id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time projectId: description: The Project ID linked to the Session. type: string startedAt: type: string format: date-time endedAt: type: string format: date-time expiresAt: type: string format: date-time status: type: string enum: - PENDING - RUNNING - ERROR - TIMED_OUT - COMPLETED proxyBytes: description: "Bytes used via the [Proxy](/features/stealth-mode#proxies-and-residential-ips)" type: integer keepAlive: description: Indicates if the Session was created to be kept alive upon disconnections type: boolean contextId: description: Optional. The Context linked to the Session. type: string region: description: The region where the Session is running. type: string enum: - us-west-2 - us-east-1 - eu-central-1 - ap-southeast-1 userMetadata: description: "Arbitrary user metadata to attach to the session. To learn more about user metadata, see [User Metadata](/features/sessions#user-metadata)." type: object additionalProperties: true properties: {} required: - id - createdAt - updatedAt - projectId - status - proxyBytes - keepAlive - region - startedAt - expiresAt SessionLiveUrls: type: object properties: debuggerFullscreenUrl: type: string format: uri debuggerUrl: type: string format: uri pages: type: array items: type: object properties: id: type: string url: type: string format: uri faviconUrl: type: string format: uri title: type: string debuggerUrl: type: string format: uri debuggerFullscreenUrl: type: string format: uri required: - id - url - faviconUrl - title - debuggerUrl - debuggerFullscreenUrl wsUrl: type: string format: uri required: - debuggerFullscreenUrl - debuggerUrl - pages - wsUrl SessionLog: type: object properties: method: type: string pageId: type: integer sessionId: type: string request: type: object properties: timestamp: description: milliseconds that have elapsed since the UNIX epoch type: integer params: type: object additionalProperties: true properties: {} rawBody: type: string required: - params - rawBody response: type: object properties: timestamp: description: milliseconds that have elapsed since the UNIX epoch type: integer result: type: object additionalProperties: true properties: {} rawBody: type: string required: - result - rawBody timestamp: description: milliseconds that have elapsed since the UNIX epoch type: integer frameId: type: string loaderId: type: string required: - method - pageId - sessionId SessionRecording: type: object properties: data: description: "See [rrweb documentation](https://github.com/rrweb-io/rrweb/blob/master/docs/recipes/dive-into-event.md)." type: object additionalProperties: true properties: {} sessionId: type: string timestamp: description: milliseconds that have elapsed since the UNIX epoch type: integer type: type: integer required: - data - sessionId - timestamp - type securitySchemes: BrowserbaseAuth: type: apiKey in: header name: X-BB-API-Key description: "Your [Browserbase API Key](https://www.browserbase.com/settings)." tags: [] security: - BrowserbaseAuth: []