Browserbase

2026-10-20

Browserbase

连接与使用指南

基础地址: https://api-develop.deepraxis.ai/browserbase

请求头: X-BB-API-Key: $PRAXIS_API_KEY

请求 ID 响应头: X-Request-Id

官方 SDK 设置 baseURL 后使用以下接口。代理、反检测、扩展和 Selenium 不可用；region 与 solveCaptchas 接受但忽略。删除登录态返回 200 和 deleted=true；会话响应还可能包含 currentUrl、clients、handoff。

操作方法与路径
创建浏览器会话POST /browserbase/v1/sessions
列出浏览器会话GET /browserbase/v1/sessions
读取浏览器会话GET /browserbase/v1/sessions/{id}
关闭浏览器会话POST /browserbase/v1/sessions/{id}
读取调试地址GET /browserbase/v1/sessions/{id}/debug
读取会话日志GET /browserbase/v1/sessions/{id}/logs
读取会话录像GET /browserbase/v1/sessions/{id}/recording
创建登录态POST /browserbase/v1/contexts
读取登录态GET /browserbase/v1/contexts/{id}
删除登录态DELETE /browserbase/v1/contexts/{id}

创建浏览器会话

POST /browserbase/v1/sessions● 支持

Browserbase

请求参数

  • projectIdstring可选

    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.

  • extensionIdstring可选○ 未支持

    不支持此配置。

  • browserSettingsobject可选
    ▸ 展开子字段（14）
    • contextobject可选
      ▸ 展开子字段（2）
      • idstring必填

        The Context ID.

      • persistboolean可选

        Whether or not to persist the context after browsing. Defaults to `false`.

    • extensionIdstring可选○ 未支持

      不支持此配置。

    • viewportobject可选
      ▸ 展开子字段（2）
      • widthinteger可选

        The width of the browser.

      • heightinteger可选

        The height of the browser.

    • blockAdsboolean可选◐ 部分支持

      接受但忽略；不会启用此能力。

    • solveCaptchasboolean可选◐ 部分支持

      接受但忽略；不会启用此能力。

    • recordSessionboolean可选◐ 部分支持

      接受但忽略；不会启用此能力。

    • logSessionboolean可选◐ 部分支持

      接受但忽略；不会启用此能力。

    • advancedStealthboolean可选○ 未支持

      不支持此配置。

    • verifiedboolean可选○ 未支持

      不支持此配置。

    • captchaImageSelectorstring可选

      Custom selector for captcha image. See [Custom Captcha Solving](/features/stealth-mode#custom-captcha-solving)

    • captchaInputSelectorstring可选

      Custom selector for captcha input. See [Custom Captcha Solving](/features/stealth-mode#custom-captcha-solving)

    • osstring可选○ 未支持

      不支持此配置。

      取值 windowsmaclinuxmobiletablet
    • allowedDomainsarray可选○ 未支持
      默认 []

      不支持此配置。

    • ignoreCertificateErrorsboolean可选○ 未支持

      不支持此配置。

  • timeoutinteger可选

    Duration in seconds after which the session will automatically end. Defaults to the Project's `defaultTimeout`. Minimum 60 seconds, maximum 21600 seconds (6 hours).

  • keepAliveboolean可选

    Set to true to keep the session alive even after disconnections. Available on the Hobby Plan and above.

  • proxiesunion可选◐ 部分支持

    仅省略、false 或 [{type: 'none'}] 可用，其它代理配置返回 501。

  • proxySettingsobject可选

    Supplementary proxy settings. Optional.

    ▸ 展开子字段（1）
    • caCertificatesarray可选
      默认 []

      The TLS certificate IDs to trust. Optional.

  • regionstring可选◐ 部分支持
    默认 "us-west-2"

    接受但忽略；不会启用此能力。

    取值 us-west-2us-east-1eu-central-1ap-southeast-1
  • userMetadataobject可选

    Arbitrary user metadata to attach to the session. To learn more about user metadata, see [User Metadata](/features/sessions#user-metadata).

返回

201

仅支持服务指南列出的能力；部分官方请求参数不可用。

错误含 statusCode、error、message；自有面另含 code。请求 ID 见 X-Request-Id。 错误

连接与使用指南

代理、反检测、扩展和 Selenium 不可用。region 和 solveCaptchas 接受但忽略；不提供区域选择或验证码代解。

响应

HTTP 201

The request has succeeded and a new resource has been created as a result.

application/json

名称类型说明
idstring
createdAtstring
updatedAtstring
projectIdstringThe Project ID linked to the Session.
startedAtstring
endedAtstring
expiresAtstring
statusstring
proxyBytesintegerBytes used via the Proxy
keepAlivebooleanIndicates if the Session was created to be kept alive upon disconnections
contextIdstringOptional. The Context linked to the Session.
regionstringThe region where the Session is running.
userMetadataobjectArbitrary user metadata to attach to the session. To learn more about user metadata, see User Metadata.
connectUrlstringWebSocket URL to connect to the Session.
seleniumRemoteUrlstringHTTP URL to connect to the Session.
signingKeystringSigning key to use when connecting to the Session via HTTP.

列出浏览器会话

GET /browserbase/v1/sessions● 支持

Browserbase

请求参数

  • statusstring可选
    取值 PENDINGRUNNINGERRORTIMED_OUTCOMPLETED
  • qstring可选

    Query sessions by user metadata. See [Querying Sessions by User Metadata](/features/sessions#querying-sessions-by-user-metadata) for the schema of this query.

返回

200

仅支持服务指南列出的能力；部分官方请求参数不可用。

错误含 statusCode、error、message；自有面另含 code。请求 ID 见 X-Request-Id。 错误

连接与使用指南

代理、反检测、扩展和 Selenium 不可用。region 和 solveCaptchas 接受但忽略；不提供区域选择或验证码代解。

响应

HTTP 200

The request has succeeded.

application/json

名称类型说明
[].idstring
[].createdAtstring
[].updatedAtstring
[].projectIdstringThe Project ID linked to the Session.
[].startedAtstring
[].endedAtstring
[].expiresAtstring
[].statusstring
[].proxyBytesintegerBytes used via the Proxy
[].keepAlivebooleanIndicates if the Session was created to be kept alive upon disconnections
[].contextIdstringOptional. The Context linked to the Session.
[].regionstringThe region where the Session is running.
[].userMetadataobjectArbitrary user metadata to attach to the session. To learn more about user metadata, see User Metadata.

读取浏览器会话

GET /browserbase/v1/sessions/{id}● 支持

Browserbase

请求参数

  • idstring必填

返回

200

仅支持服务指南列出的能力；部分官方请求参数不可用。

错误含 statusCode、error、message；自有面另含 code。请求 ID 见 X-Request-Id。 错误

连接与使用指南

代理、反检测、扩展和 Selenium 不可用。region 和 solveCaptchas 接受但忽略；不提供区域选择或验证码代解。

响应

HTTP 200

The request has succeeded.

application/json

名称类型说明
idstring
createdAtstring
updatedAtstring
projectIdstringThe Project ID linked to the Session.
startedAtstring
endedAtstring
expiresAtstring
statusstring
proxyBytesintegerBytes used via the Proxy
keepAlivebooleanIndicates if the Session was created to be kept alive upon disconnections
contextIdstringOptional. The Context linked to the Session.
regionstringThe region where the Session is running.
userMetadataobjectArbitrary user metadata to attach to the session. To learn more about user metadata, see User Metadata.
connectUrlstringWebSocket URL to connect to the Session.
seleniumRemoteUrlstringHTTP URL to connect to the Session.
signingKeystringSigning key to use when connecting to the Session via HTTP.

关闭浏览器会话

POST /browserbase/v1/sessions/{id}● 支持

Browserbase

请求参数

  • idstring必填
  • statusstring必填

    Set to `REQUEST_RELEASE` to request that the session complete. Use before session's timeout to avoid additional charges.

    取值 REQUEST_RELEASE

返回

200

仅支持服务指南列出的能力；部分官方请求参数不可用。

错误含 statusCode、error、message；自有面另含 code。请求 ID 见 X-Request-Id。 错误

连接与使用指南

代理、反检测、扩展和 Selenium 不可用。region 和 solveCaptchas 接受但忽略；不提供区域选择或验证码代解。

响应

HTTP 200

The request has succeeded.

application/json

名称类型说明
idstring
createdAtstring
updatedAtstring
projectIdstringThe Project ID linked to the Session.
startedAtstring
endedAtstring
expiresAtstring
statusstring
proxyBytesintegerBytes used via the Proxy
keepAlivebooleanIndicates if the Session was created to be kept alive upon disconnections
contextIdstringOptional. The Context linked to the Session.
regionstringThe region where the Session is running.
userMetadataobjectArbitrary user metadata to attach to the session. To learn more about user metadata, see User Metadata.

读取调试地址

GET /browserbase/v1/sessions/{id}/debug● 支持

Browserbase

请求参数

  • expiresIninteger可选

    Time-to-live of the generated live view URLs, in seconds. If omitted, the URLs expire with the session, up to a maximum of 21600 seconds (6 hours).

  • idstring必填

返回

200

仅支持服务指南列出的能力；部分官方请求参数不可用。

错误含 statusCode、error、message；自有面另含 code。请求 ID 见 X-Request-Id。 错误

连接与使用指南

代理、反检测、扩展和 Selenium 不可用。region 和 solveCaptchas 接受但忽略；不提供区域选择或验证码代解。

响应

HTTP 200

The request has succeeded.

application/json

名称类型说明
debuggerFullscreenUrlstring
debuggerUrlstring
pagesarray<object>
pages[].idstring
pages[].urlstring
pages[].faviconUrlstring
pages[].titlestring
pages[].debuggerUrlstring
pages[].debuggerFullscreenUrlstring
wsUrlstring

读取会话日志

GET /browserbase/v1/sessions/{id}/logs● 支持

Browserbase

请求参数

  • idstring必填

返回

200

仅支持服务指南列出的能力；部分官方请求参数不可用。

错误含 statusCode、error、message；自有面另含 code。请求 ID 见 X-Request-Id。 错误

连接与使用指南

代理、反检测、扩展和 Selenium 不可用。region 和 solveCaptchas 接受但忽略；不提供区域选择或验证码代解。

响应

HTTP 200

The request has succeeded.

application/json

名称类型说明
[].methodstring
[].pageIdinteger
[].sessionIdstring
[].requestobject
[].request.timestampintegermilliseconds that have elapsed since the UNIX epoch
[].request.paramsobject
[].request.rawBodystring
[].responseobject
[].response.timestampintegermilliseconds that have elapsed since the UNIX epoch
[].response.resultobject
[].response.rawBodystring
[].timestampintegermilliseconds that have elapsed since the UNIX epoch
[].frameIdstring
[].loaderIdstring

读取会话录像

GET /browserbase/v1/sessions/{id}/recording● 支持

Browserbase

请求参数

  • idstring必填

返回

200

仅支持服务指南列出的能力；部分官方请求参数不可用。

错误含 statusCode、error、message；自有面另含 code。请求 ID 见 X-Request-Id。 错误

连接与使用指南

代理、反检测、扩展和 Selenium 不可用。region 和 solveCaptchas 接受但忽略；不提供区域选择或验证码代解。

响应

HTTP 200

The request has succeeded.

application/json

名称类型说明
[].idstring
[].dataobjectSee rrweb documentation.
[].sessionIdstring
[].timestampintegermilliseconds that have elapsed since the UNIX epoch
[].typeinteger

创建登录态

POST /browserbase/v1/contexts● 支持

Browserbase

请求参数

  • projectIdstring可选

    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.

  • namestring可选

    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.

返回

201

仅支持服务指南列出的能力；部分官方请求参数不可用。

错误含 statusCode、error、message；自有面另含 code。请求 ID 见 X-Request-Id。 错误

连接与使用指南

代理、反检测、扩展和 Selenium 不可用。region 和 solveCaptchas 接受但忽略；不提供区域选择或验证码代解。

响应

HTTP 201

The request has succeeded and a new resource has been created as a result.

application/json

名称类型说明
idstring
publicKeystringThe public key to encrypt the user-data-directory.
cipherAlgorithmstringThe cipher algorithm used to encrypt the user-data-directory. AES-256-CBC is currently the only supported algorithm.
initializationVectorSizeintegerThe initialization vector size used to encrypt the user-data-directory. Read more about how to use it.

读取登录态

GET /browserbase/v1/contexts/{id}● 支持

Browserbase

请求参数

  • idstring必填

返回

200

仅支持服务指南列出的能力；部分官方请求参数不可用。

错误含 statusCode、error、message；自有面另含 code。请求 ID 见 X-Request-Id。 错误

连接与使用指南

代理、反检测、扩展和 Selenium 不可用。region 和 solveCaptchas 接受但忽略；不提供区域选择或验证码代解。

响应

HTTP 200

The request has succeeded.

application/json

名称类型说明
idstring
createdAtstring
updatedAtstring
projectIdstringThe Project ID linked to the uploaded Context.
namestringOptional 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.

删除登录态

DELETE /browserbase/v1/contexts/{id}● 支持

Browserbase

请求参数

  • idstring必填

返回

200

仅支持服务指南列出的能力；部分官方请求参数不可用。

错误含 statusCode、error、message；自有面另含 code。请求 ID 见 X-Request-Id。 错误

连接与使用指南

代理、反检测、扩展和 Selenium 不可用。region 和 solveCaptchas 接受但忽略；不提供区域选择或验证码代解。

此接口返回 200 和 JSON 确认；Browserbase 官方为 204。

响应

HTTP 200

Context deleted. Praxis returns JSON instead of Browserbase's 204.

application/json

名称类型说明
deletedboolean