云端浏览器 API

2026-10-20

云端浏览器 API

连接与使用指南

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

请求头: Authorization: Bearer $PRAXIS_API_KEY

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

操作方法与路径
创建浏览器会话POST /browser/v1/sessions
列出浏览器会话GET /browser/v1/sessions
读取浏览器会话GET /browser/v1/sessions/{sessionId}
关闭浏览器会话POST /browser/v1/sessions/{sessionId}
读取调试地址GET /browser/v1/sessions/{sessionId}/debug
列出会话事件GET /browser/v1/sessions/{sessionId}/events
请求人工接管POST /browser/v1/sessions/{sessionId}/handoff
完成人工接管POST /browser/v1/sessions/{sessionId}/handoff/complete
更新查看者心跳POST /browser/v1/sessions/{sessionId}/viewer
创建登录态POST /browser/v1/contexts
列出登录态GET /browser/v1/contexts
读取登录态GET /browser/v1/contexts/{contextId}
更新登录态PUT /browser/v1/contexts/{contextId}
删除登录态DELETE /browser/v1/contexts/{contextId}
连接云端浏览器GET /browser/v1/connect
打开实时浏览器画面GET /browser/v1/live/{sessionId}/{pageId}
订阅会话动态GET /browser/v1/sessions/{sessionId}/stream
读取 Selenium 不支持提示GET /browser/v1/selenium-unsupported

创建浏览器会话

POST /browser/v1/sessions● 支持

请求参数

  • projectIdstring可选

    可省略；账户使用 default 项目。

  • keepAliveboolean可选
    默认 false

    false 时最后一个客户端断开且无人观看后结束会话；true 时保留至关闭或超时。

  • timeoutnumber可选
    默认 3600

    从创建时刻起算的会话最长寿命，单位为秒；可含小数。

  • browserSettingsobject可选

    创建浏览器时的登录态、视口及兼容选项；省略时不加载已保存的登录态。

    ▸ 展开子字段（13）
    • contextobject可选

      新会话使用的已保存登录态；必须属于当前账户；persist 为 true 时同一登录态只能有一个写入会话。

      ▸ 展开子字段（2）
      • idstring必填

        登录态 ID；使用创建或列出登录态返回的 id，以 bsc_ 开头。

      • persistboolean可选
        默认 false

        关闭会话时合并保存 cookie 和 localStorage；false 只读取登录态；不保存 IndexedDB。

    • viewportobject可选

      浏览器视口尺寸；创建时省略整个对象则使用宽 1280、高 800 像素。

      ▸ 展开子字段（2）
      • widthinteger必填

        浏览器视口宽度，单位为像素，必须为正整数。

      • heightinteger必填

        浏览器视口高度，单位为像素，必须为正整数。

    • blockAdsboolean可选◐ 部分支持

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

    • solveCaptchasboolean可选◐ 部分支持

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

    • recordSessionboolean可选◐ 部分支持

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

    • logSessionboolean可选◐ 部分支持

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

    • extensionIdstring可选○ 未支持

      不支持此配置。

    • verifiedboolean可选○ 未支持

      不支持此配置。

    • advancedStealthboolean可选○ 未支持

      不支持此配置。

    • osstring可选○ 未支持

      不支持此配置。

    • fingerprintobject可选○ 未支持

      不支持此配置。

    • allowedDomainsarray可选○ 未支持

      不支持此配置。

    • ignoreCertificateErrorsboolean可选○ 未支持

      不支持此配置。

  • proxiesunion可选◐ 部分支持

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

  • regionstring可选◐ 部分支持

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

  • extensionIdstring可选○ 未支持

    不支持此配置。

  • userMetadataobject可选

    自定义 JSON 元数据；序列化后的长度最多为 512 个 UTF-16 代码单元。

  • namestring可选

    会话名称；1–128 个 ASCII 字母、数字或 . _ : -，可用于筛选会话。

  • labelsobject可选

    自定义字符串标签；最多 32 项，键最多 128 个 UTF-8 字节，值最多 1024 个 UTF-8 字节。

返回

201

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

连接与使用指南

响应

HTTP 201

请求成功。

application/json

名称类型说明
idstring浏览器会话 ID；使用创建或列出会话返回的 id，以 bss_ 开头。
projectIdstring兼容项目标识，当前账户的会话固定返回 default。
statusstring会话生命周期状态；释放中的会话仍显示 RUNNING，但已不能建立新连接。
keepAlivebooleanAPI 创建的会话是否在客户端断开后保留；true 不因空闲释放，仍受最长寿命限制。
regionstring兼容字段，不代表可选择部署区域。
proxyBytesinteger兼容的代理流量字节数；当前未使用代理，固定返回 0。
createdAtstring会话创建时刻，UTC ISO 8601 时间。
updatedAtstring会话状态最近一次更新的时刻，UTC ISO 8601 时间。
startedAtstring浏览器开始运行的时刻；尚未开始运行时返回创建时刻，UTC ISO 8601 时间。
expiresAtstring会话最长寿命的到期时刻，等于创建时刻加 timeout 秒，UTC ISO 8601 时间。
endedAtstring浏览器使用区间的结束时刻，UTC ISO 8601 时间；尚未记录结束时刻时省略。
contextIdstring登录态 ID；使用创建或列出登录态返回的 id，以 bsc_ 开头。
userMetadataobject创建会话时传入的自定义 JSON 元数据；未设置时为空对象。
namestring会话名称；1–128 个 ASCII 字母、数字或 . _ : -，可用于筛选会话。
labelsobject自定义字符串标签；最多 32 项，键最多 128 个 UTF-8 字节，值最多 1024 个 UTF-8 字节。
originstring会话创建入口；api 为 API 创建，connect 为一步连接创建，console 为 Console 创建。
closeReasonstring会话释放原因；未开始释放时省略。
viewportobject浏览器视口尺寸；创建时省略整个对象则使用宽 1280、高 800 像素。
viewport.widthinteger浏览器视口宽度，单位为像素，必须为正整数。
viewport.heightinteger浏览器视口高度，单位为像素，必须为正整数。
billedSecondsnumber会话计费时长，单位为秒；运行时随时长增长，结束后为最终计费时长，可含小数。
currentUrlstring最近观察到的页面导航地址；尚未观察到导航时省略。
clientsinteger当前连接的 CDP 客户端数量；不包含仅观看页面的用户。
handoffobject | null待完成的人工接管请求；没有请求、已完成或已过期时为 null。
handoff.messagestring请求人工接管时提供给操作者的说明文字。
handoff.requestedAtstring人工接管请求的发起时刻，UTC ISO 8601 时间。
handoff.expiresAtstring人工接管请求的失效时刻，UTC ISO 8601 时间。
connectUrlstring自带凭证的 CDP WebSocket 地址，有效期覆盖会话寿命；连接无需额外 API Key。
signingKeystringconnectUrl 内的连接凭证，请勿公开。
seleniumRemoteUrlstring该地址返回 501；不支持 Selenium。

列出浏览器会话

GET /browser/v1/sessions● 支持

请求参数

  • statusstring可选

    按会话生命周期状态筛选；省略时返回所有状态。

    取值 PENDINGRUNNINGERRORTIMED_OUTCOMPLETED
  • qstring可选

    按单个用户元数据键的字符串值精确筛选，例如 user_metadata['purpose']:'docs'。

  • namestring可选

    按会话名称精确匹配；省略时不按名称筛选。

  • labelsstring可选

    JSON 编码的标签对象；仅返回同时匹配所有标签键值的会话。

  • cursorstring可选

    上一页返回的 nextCursor，原样传入以继续读取；省略时读取第一页。

  • limitinteger可选

    每页最多返回的记录数量；默认 50，范围 1–200。

返回

200

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

连接与使用指南

响应

HTTP 200

请求成功。

application/json

名称类型说明
dataarray<object>本页查询匹配的记录；没有匹配项时为空数组。
data[].idstring浏览器会话 ID；使用创建或列出会话返回的 id，以 bss_ 开头。
data[].projectIdstring兼容项目标识，当前账户的会话固定返回 default。
data[].statusstring会话生命周期状态；释放中的会话仍显示 RUNNING，但已不能建立新连接。
data[].keepAlivebooleanAPI 创建的会话是否在客户端断开后保留；true 不因空闲释放，仍受最长寿命限制。
data[].regionstring兼容字段，不代表可选择部署区域。
data[].proxyBytesinteger兼容的代理流量字节数；当前未使用代理，固定返回 0。
data[].createdAtstring会话创建时刻，UTC ISO 8601 时间。
data[].updatedAtstring会话状态最近一次更新的时刻，UTC ISO 8601 时间。
data[].startedAtstring浏览器开始运行的时刻；尚未开始运行时返回创建时刻，UTC ISO 8601 时间。
data[].expiresAtstring会话最长寿命的到期时刻，等于创建时刻加 timeout 秒，UTC ISO 8601 时间。
data[].endedAtstring浏览器使用区间的结束时刻，UTC ISO 8601 时间；尚未记录结束时刻时省略。
data[].contextIdstring登录态 ID；使用创建或列出登录态返回的 id，以 bsc_ 开头。
data[].userMetadataobject创建会话时传入的自定义 JSON 元数据；未设置时为空对象。
data[].namestring会话名称；1–128 个 ASCII 字母、数字或 . _ : -，可用于筛选会话。
data[].labelsobject自定义字符串标签；最多 32 项，键最多 128 个 UTF-8 字节，值最多 1024 个 UTF-8 字节。
data[].originstring会话创建入口；api 为 API 创建，connect 为一步连接创建，console 为 Console 创建。
data[].closeReasonstring会话释放原因；未开始释放时省略。
data[].viewportobject浏览器视口尺寸；创建时省略整个对象则使用宽 1280、高 800 像素。
data[].billedSecondsnumber会话计费时长，单位为秒；运行时随时长增长，结束后为最终计费时长，可含小数。
data[].currentUrlstring最近观察到的页面导航地址；尚未观察到导航时省略。
data[].clientsinteger当前连接的 CDP 客户端数量；不包含仅观看页面的用户。
data[].handoffobject | null待完成的人工接管请求；没有请求、已完成或已过期时为 null。
nextCursorstring | null下一页游标；原样传入 cursor，null 表示没有更多结果。

读取浏览器会话

GET /browser/v1/sessions/{sessionId}● 支持

请求参数

  • sessionIdstring必填

    浏览器会话 ID；使用创建或列出会话返回的 id，以 bss_ 开头。

  • expandstring可选

    逗号分隔的 debug、events；在同一响应中返回调试地址和事件。

返回

200

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

连接与使用指南

响应

HTTP 200

请求成功。

application/json

名称类型说明
idstring浏览器会话 ID；使用创建或列出会话返回的 id，以 bss_ 开头。
projectIdstring兼容项目标识，当前账户的会话固定返回 default。
statusstring会话生命周期状态；释放中的会话仍显示 RUNNING，但已不能建立新连接。
keepAlivebooleanAPI 创建的会话是否在客户端断开后保留；true 不因空闲释放，仍受最长寿命限制。
regionstring兼容字段，不代表可选择部署区域。
proxyBytesinteger兼容的代理流量字节数；当前未使用代理，固定返回 0。
createdAtstring会话创建时刻，UTC ISO 8601 时间。
updatedAtstring会话状态最近一次更新的时刻，UTC ISO 8601 时间。
startedAtstring浏览器开始运行的时刻；尚未开始运行时返回创建时刻，UTC ISO 8601 时间。
expiresAtstring会话最长寿命的到期时刻，等于创建时刻加 timeout 秒，UTC ISO 8601 时间。
endedAtstring浏览器使用区间的结束时刻，UTC ISO 8601 时间；尚未记录结束时刻时省略。
contextIdstring登录态 ID；使用创建或列出登录态返回的 id，以 bsc_ 开头。
userMetadataobject创建会话时传入的自定义 JSON 元数据；未设置时为空对象。
namestring会话名称；1–128 个 ASCII 字母、数字或 . _ : -，可用于筛选会话。
labelsobject自定义字符串标签；最多 32 项，键最多 128 个 UTF-8 字节，值最多 1024 个 UTF-8 字节。
originstring会话创建入口；api 为 API 创建，connect 为一步连接创建，console 为 Console 创建。
closeReasonstring会话释放原因；未开始释放时省略。
viewportobject浏览器视口尺寸；创建时省略整个对象则使用宽 1280、高 800 像素。
viewport.widthinteger浏览器视口宽度，单位为像素，必须为正整数。
viewport.heightinteger浏览器视口高度，单位为像素，必须为正整数。
billedSecondsnumber会话计费时长，单位为秒；运行时随时长增长，结束后为最终计费时长，可含小数。
currentUrlstring最近观察到的页面导航地址；尚未观察到导航时省略。
clientsinteger当前连接的 CDP 客户端数量；不包含仅观看页面的用户。
handoffobject | null待完成的人工接管请求；没有请求、已完成或已过期时为 null。
handoff.messagestring请求人工接管时提供给操作者的说明文字。
handoff.requestedAtstring人工接管请求的发起时刻，UTC ISO 8601 时间。
handoff.expiresAtstring人工接管请求的失效时刻，UTC ISO 8601 时间。
debugobject会话和标签页的实时观看地址，以及当前会话的 CDP 连接地址。
debug.debuggerFullscreenUrlstring会话实时画面的完整跳转地址，携带观看凭证；与 debuggerUrl 相同。
debug.debuggerUrlstring会话实时画面的完整跳转地址；直接打开，勿移除查询凭证。
debug.wsUrlstring连接当前会话的 CDP WebSocket 地址，自带 signingKey，无需额外 API Key。
debug.pagesarray<object>当前浏览器标签页及各页的实时观看地址；会话不在运行状态时为空数组。
eventsobjectexpand 包含 events 时返回的会话事件首页；后续页通过事件列表读取。
events.dataarray<object>本页查询匹配的记录；没有匹配项时为空数组。
events.nextCursorstring | null下一页游标；原样传入 cursor，null 表示没有更多结果。

关闭浏览器会话

POST /browser/v1/sessions/{sessionId}● 支持

请求参数

  • sessionIdstring必填

    浏览器会话 ID；使用创建或列出会话返回的 id，以 bss_ 开头。

  • statusstring必填

    会话操作指令；REQUEST_RELEASE 表示请求关闭浏览器并结束会话。

    取值 REQUEST_RELEASE

返回

200

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

连接与使用指南

响应

HTTP 200

请求成功。

application/json

名称类型说明
idstring浏览器会话 ID；使用创建或列出会话返回的 id，以 bss_ 开头。
projectIdstring兼容项目标识，当前账户的会话固定返回 default。
statusstring会话生命周期状态；释放中的会话仍显示 RUNNING，但已不能建立新连接。
keepAlivebooleanAPI 创建的会话是否在客户端断开后保留；true 不因空闲释放，仍受最长寿命限制。
regionstring兼容字段，不代表可选择部署区域。
proxyBytesinteger兼容的代理流量字节数；当前未使用代理，固定返回 0。
createdAtstring会话创建时刻，UTC ISO 8601 时间。
updatedAtstring会话状态最近一次更新的时刻，UTC ISO 8601 时间。
startedAtstring浏览器开始运行的时刻；尚未开始运行时返回创建时刻，UTC ISO 8601 时间。
expiresAtstring会话最长寿命的到期时刻，等于创建时刻加 timeout 秒，UTC ISO 8601 时间。
endedAtstring浏览器使用区间的结束时刻，UTC ISO 8601 时间；尚未记录结束时刻时省略。
contextIdstring登录态 ID；使用创建或列出登录态返回的 id，以 bsc_ 开头。
userMetadataobject创建会话时传入的自定义 JSON 元数据；未设置时为空对象。
namestring会话名称；1–128 个 ASCII 字母、数字或 . _ : -，可用于筛选会话。
labelsobject自定义字符串标签；最多 32 项，键最多 128 个 UTF-8 字节，值最多 1024 个 UTF-8 字节。
originstring会话创建入口；api 为 API 创建，connect 为一步连接创建，console 为 Console 创建。
closeReasonstring会话释放原因；未开始释放时省略。
viewportobject浏览器视口尺寸；创建时省略整个对象则使用宽 1280、高 800 像素。
viewport.widthinteger浏览器视口宽度，单位为像素，必须为正整数。
viewport.heightinteger浏览器视口高度，单位为像素，必须为正整数。
billedSecondsnumber会话计费时长，单位为秒；运行时随时长增长，结束后为最终计费时长，可含小数。
currentUrlstring最近观察到的页面导航地址；尚未观察到导航时省略。
clientsinteger当前连接的 CDP 客户端数量；不包含仅观看页面的用户。
handoffobject | null待完成的人工接管请求；没有请求、已完成或已过期时为 null。
handoff.messagestring请求人工接管时提供给操作者的说明文字。
handoff.requestedAtstring人工接管请求的发起时刻，UTC ISO 8601 时间。
handoff.expiresAtstring人工接管请求的失效时刻，UTC ISO 8601 时间。

读取调试地址

GET /browser/v1/sessions/{sessionId}/debug● 支持

请求参数

  • sessionIdstring必填

    浏览器会话 ID；使用创建或列出会话返回的 id，以 bss_ 开头。

返回

200

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

连接与使用指南

响应

HTTP 200

请求成功。

application/json

名称类型说明
debuggerFullscreenUrlstring会话实时画面的完整跳转地址，携带观看凭证；与 debuggerUrl 相同。
debuggerUrlstring会话实时画面的完整跳转地址；直接打开，勿移除查询凭证。
wsUrlstring连接当前会话的 CDP WebSocket 地址，自带 signingKey，无需额外 API Key。
pagesarray<object>当前浏览器标签页及各页的实时观看地址；会话不在运行状态时为空数组。
pages[].idstring浏览器标签页的目标 ID，可用于实时画面地址中的 pageId。
pages[].urlstring该浏览器标签页当前报告的页面地址。
pages[].titlestring该浏览器标签页当前报告的页面标题。
pages[].faviconUrlstring兼容的页面图标地址字段，当前固定返回空字符串。
pages[].debuggerUrlstring此标签页实时画面的完整跳转地址，包含观看凭证。
pages[].debuggerFullscreenUrlstring此标签页实时画面的完整跳转地址，与该页 debuggerUrl 相同。

列出会话事件

GET /browser/v1/sessions/{sessionId}/events● 支持

请求参数

  • sessionIdstring必填

    浏览器会话 ID；使用创建或列出会话返回的 id，以 bss_ 开头。

  • cursorstring可选

    上一页返回的 nextCursor，表示已读到的事件序号；省略时从最早事件开始。

  • limitinteger可选

    每页最多返回的记录数量；默认 50，范围 1–200。

  • typesstring可选

    逗号分隔的账本事件类型，仅返回匹配项；省略时不按类型筛选。

返回

200

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

连接与使用指南

响应

HTTP 200

请求成功。

application/json

名称类型说明
dataarray<object>本页查询匹配的记录；没有匹配项时为空数组。
data[].seqinteger当前会话内递增的事件序号，用于事件排序及分页。
data[].idstring服务生成的事件唯一标识，使用 UUID 格式。
data[].typestring会话账本中的事件类型，用于区分状态变化和会话操作。
data[].processed_atstring事件记录时刻，UTC ISO 8601 时间。
data[].session_idstring浏览器会话 ID；使用创建或列出会话返回的 id，以 bss_ 开头。
data[].reasonstring事件发生原因；关闭相关事件记录对应的会话释放原因。
data[].payloadobject事件附加数据，内容取决于事件类型；没有附加数据时省略。
nextCursorstring | null下一页游标；原样传入 cursor，null 表示没有更多结果。

请求人工接管

POST /browser/v1/sessions/{sessionId}/handoff● 支持

请求参数

  • sessionIdstring必填

    浏览器会话 ID；使用创建或列出会话返回的 id，以 bss_ 开头。

  • messagestring必填

    交给人工操作者的接管说明，可为空字符串。

  • timeoutMsnumber可选
    默认 1800000

    接管请求有效时长，单位为毫秒；必须大于 0，可含小数。

返回

200

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

连接与使用指南

响应

HTTP 200

请求成功。

application/json

名称类型说明
seqinteger当前会话内递增的事件序号，用于事件排序及分页。
idstring服务生成的事件唯一标识，使用 UUID 格式。
typestring会话账本中的事件类型，用于区分状态变化和会话操作。
processed_atstring事件记录时刻，UTC ISO 8601 时间。
session_idstring浏览器会话 ID；使用创建或列出会话返回的 id，以 bss_ 开头。
reasonstring事件发生原因；关闭相关事件记录对应的会话释放原因。
payloadobject事件附加数据，内容取决于事件类型；没有附加数据时省略。

完成人工接管

POST /browser/v1/sessions/{sessionId}/handoff/complete● 支持

请求参数

  • sessionIdstring必填

    浏览器会话 ID；使用创建或列出会话返回的 id，以 bss_ 开头。

返回

200

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

连接与使用指南

响应

HTTP 200

请求成功。

application/json

名称类型说明
seqinteger当前会话内递增的事件序号，用于事件排序及分页。
idstring服务生成的事件唯一标识，使用 UUID 格式。
typestring会话账本中的事件类型，用于区分状态变化和会话操作。
processed_atstring事件记录时刻，UTC ISO 8601 时间。
session_idstring浏览器会话 ID；使用创建或列出会话返回的 id，以 bss_ 开头。
reasonstring事件发生原因；关闭相关事件记录对应的会话释放原因。
payloadobject事件附加数据，内容取决于事件类型；没有附加数据时省略。

更新查看者心跳

POST /browser/v1/sessions/{sessionId}/viewer● 支持

请求参数

  • sessionIdstring必填

    浏览器会话 ID；使用创建或列出会话返回的 id，以 bss_ 开头。

  • viewerIdstring必填

    当前观看者的稳定标识；同一观看者重复心跳应使用相同值，长度为 1–128 个 UTF-16 代码单元。

返回

200

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

连接与使用指南

响应

HTTP 200

请求成功。

application/json

名称类型说明
okboolean心跳已被接受，成功时固定返回 true。

创建登录态

POST /browser/v1/contexts● 支持

请求参数

  • projectIdstring可选

    兼容项目字段；传入值被忽略，创建结果的 projectId 固定为 default。

  • namestring可选

    登录态名称；非空时为 1–128 个 ASCII 字母、数字或 . _ : -，在当前账户内唯一；空字符串表示不设名称或清除名称。

  • labelsobject可选

    自定义字符串标签；最多 32 项，键最多 128 个 UTF-8 字节，值最多 1024 个 UTF-8 字节。

返回

201

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

连接与使用指南

响应

HTTP 201

请求成功。

application/json

名称类型说明
idstring登录态 ID；使用创建或列出登录态返回的 id，以 bsc_ 开头。
projectIdstring兼容项目标识，当前账户的登录态固定返回 default。
createdAtstring登录态创建时刻，UTC ISO 8601 时间。
updatedAtstring登录态名称、标签或保存内容最近一次更新的时刻，UTC ISO 8601 时间。
namestring登录态名称；非空时为 1–128 个 ASCII 字母、数字或 . _ : -，在当前账户内唯一；空字符串表示不设名称或清除名称。
labelsobject自定义字符串标签；最多 32 项，键最多 128 个 UTF-8 字节，值最多 1024 个 UTF-8 字节。
sitesarray<string>已保存的 localStorage 主机名和 cookie 域名，去掉 cookie 域名前导点后去重排序。
cookieCountinteger登录态中已保存的 cookie 条目数量；新登录态为 0。
bytesinteger登录态加密后保存内容的大小，单位为 UTF-8 字节。
lockedBystring当前登录态写入租约的持有者标识；无有效租约时省略。
lastUsedAtstring
publicKeystring
cipherAlgorithmstring
initializationVectorSizeinteger

列出登录态

GET /browser/v1/contexts● 支持

请求参数

  • cursorstring可选

    上一页返回的 nextCursor，原样传入以继续读取；省略时读取第一页。

  • limitinteger可选

    每页最多返回的登录态数量；默认 25，范围 1–100。

返回

200

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

连接与使用指南

响应

HTTP 200

请求成功。

application/json

名称类型说明
dataarray<object>本页查询匹配的记录；没有匹配项时为空数组。
data[].idstring登录态 ID；使用创建或列出登录态返回的 id，以 bsc_ 开头。
data[].projectIdstring兼容项目标识，当前账户的登录态固定返回 default。
data[].createdAtstring登录态创建时刻，UTC ISO 8601 时间。
data[].updatedAtstring登录态名称、标签或保存内容最近一次更新的时刻，UTC ISO 8601 时间。
data[].namestring登录态名称；非空时为 1–128 个 ASCII 字母、数字或 . _ : -，在当前账户内唯一；空字符串表示不设名称或清除名称。
data[].labelsobject自定义字符串标签；最多 32 项，键最多 128 个 UTF-8 字节，值最多 1024 个 UTF-8 字节。
data[].sitesarray<string>已保存的 localStorage 主机名和 cookie 域名，去掉 cookie 域名前导点后去重排序。
data[].cookieCountinteger登录态中已保存的 cookie 条目数量；新登录态为 0。
data[].bytesinteger登录态加密后保存内容的大小，单位为 UTF-8 字节。
data[].lockedBystring当前登录态写入租约的持有者标识；无有效租约时省略。
data[].lastUsedAtstring
nextCursorstring | null下一页游标；原样传入 cursor，null 表示没有更多结果。

读取登录态

GET /browser/v1/contexts/{contextId}● 支持

请求参数

  • contextIdstring必填

    登录态 ID；使用创建或列出登录态返回的 id，以 bsc_ 开头。

返回

200

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

连接与使用指南

响应

HTTP 200

请求成功。

application/json

名称类型说明
idstring登录态 ID；使用创建或列出登录态返回的 id，以 bsc_ 开头。
projectIdstring兼容项目标识，当前账户的登录态固定返回 default。
createdAtstring登录态创建时刻，UTC ISO 8601 时间。
updatedAtstring登录态名称、标签或保存内容最近一次更新的时刻，UTC ISO 8601 时间。
namestring登录态名称；非空时为 1–128 个 ASCII 字母、数字或 . _ : -，在当前账户内唯一；空字符串表示不设名称或清除名称。
labelsobject自定义字符串标签；最多 32 项，键最多 128 个 UTF-8 字节，值最多 1024 个 UTF-8 字节。
sitesarray<string>已保存的 localStorage 主机名和 cookie 域名，去掉 cookie 域名前导点后去重排序。
cookieCountinteger登录态中已保存的 cookie 条目数量；新登录态为 0。
bytesinteger登录态加密后保存内容的大小，单位为 UTF-8 字节。
lockedBystring当前登录态写入租约的持有者标识；无有效租约时省略。
lastUsedAtstring

更新登录态

PUT /browser/v1/contexts/{contextId}● 支持

请求参数

  • contextIdstring必填

    登录态 ID；使用创建或列出登录态返回的 id，以 bsc_ 开头。

  • namestring可选

    登录态名称；非空时为 1–128 个 ASCII 字母、数字或 . _ : -，在当前账户内唯一；空字符串表示不设名称或清除名称。

  • labelsobject可选

    自定义字符串标签；最多 32 项，键最多 128 个 UTF-8 字节，值最多 1024 个 UTF-8 字节。 更新时整体替换；空对象清除标签，省略则保留。

返回

200

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

连接与使用指南

响应

HTTP 200

请求成功。

application/json

名称类型说明
idstring登录态 ID；使用创建或列出登录态返回的 id，以 bsc_ 开头。
projectIdstring兼容项目标识，当前账户的登录态固定返回 default。
createdAtstring登录态创建时刻，UTC ISO 8601 时间。
updatedAtstring登录态名称、标签或保存内容最近一次更新的时刻，UTC ISO 8601 时间。
namestring登录态名称；非空时为 1–128 个 ASCII 字母、数字或 . _ : -，在当前账户内唯一；空字符串表示不设名称或清除名称。
labelsobject自定义字符串标签；最多 32 项，键最多 128 个 UTF-8 字节，值最多 1024 个 UTF-8 字节。
sitesarray<string>已保存的 localStorage 主机名和 cookie 域名，去掉 cookie 域名前导点后去重排序。
cookieCountinteger登录态中已保存的 cookie 条目数量；新登录态为 0。
bytesinteger登录态加密后保存内容的大小，单位为 UTF-8 字节。
lockedBystring当前登录态写入租约的持有者标识；无有效租约时省略。
lastUsedAtstring

删除登录态

DELETE /browser/v1/contexts/{contextId}● 支持

请求参数

  • contextIdstring必填

    登录态 ID；使用创建或列出登录态返回的 id，以 bsc_ 开头。

返回

200

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

连接与使用指南

响应

HTTP 200

请求成功。

application/json

名称类型说明
deletedboolean登录态及保存内容已删除，成功时固定返回 true。

连接云端浏览器

GET /browser/v1/connect● 支持

请求参数

  • sessionstring可选

    要连接的已有会话 ID，来自创建或列表响应；不能同时提供 name。

  • namestring可选

    按名称连接或创建。

  • signingKeystring可选

    connectUrl 自带凭证；必须同时带 session。

  • contextstring可选

    新会话使用的登录态 ID，来自创建或列表响应；连接已有会话时忽略。

  • persistboolean可选

    关闭时保存登录态。

  • timeoutnumber可选

    新会话最长寿命，单位为秒，可含小数；连接已有会话时忽略。

  • idlenumber可选

    新会话无人连接或观看后的释放等待时长，单位为毫秒；允许 0 或小数，连接已有会话时忽略。

  • labelsstring可选

    JSON 编码的字符串标签对象。

  • viewportstring可选

    JSON 编码的视口，例如 {"width":1280,"height":800}。

返回

101

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

连接与使用指南

响应

此端点没有声明成功响应。

打开实时浏览器画面

GET /browser/v1/live/{sessionId}/{pageId}● 支持

请求参数

  • sessionIdstring必填

    浏览器会话 ID；使用创建或列出会话返回的 id，以 bss_ 开头。

  • pageIdstring必填

    实时观看地址中的标签页 ID；使用 debug 返回链接中的原值，_ 表示会话级画面。

  • tstring可选

    实时观看地址自带的凭证。

返回

302

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

连接与使用指南

响应

此端点没有声明成功响应。

订阅会话动态

GET /browser/v1/sessions/{sessionId}/stream● 支持

请求参数

  • sessionIdstring必填

    浏览器会话 ID；使用创建或列出会话返回的 id，以 bss_ 开头。

返回

200

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

连接与使用指南

响应

HTTP 200

持续推送会话状态。

text/event-stream — chunk / 事件对象

名称类型说明
$stringevent: <事件名>\ndata: <JSON>\n\n

GET /browser/v1/selenium-unsupported○ 未支持

返回

501

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

连接与使用指南

响应

此端点没有声明成功响应。