本页内容
cloudBrowser.runtime
runtime.status 为 starting、running、stopping 或 stopped；starting/stopping 仍占额度。runtimeKind 为 neko 或 worker_cdp。活动会话带 sessionId、expiresAt；只有 running 才可能带 connectUrl，可直接打开对应实例的交互界面，需使用档案所有者账号登录。neko 链接指向 API 域 /cloud-browser-runtime/{sessionId}/，不返回 cdpBaseUrl；固定 usr/pwd 参数是公共查看器协议值，访问权限仍由会话 Cookie 校验，不使用只读 cast 模式。worker_cdp 使用 CDP Studio，可返回带临时令牌的 cdpBaseUrl。请使用返回地址，勿自行拼接或向 URL 添加 API Key、Cookie、代理凭据。地址缺失时先查询真实状态。
| 字段 | 类型 | 说明 |
|---|---|---|
runtimeKind | "neko" | "worker_cdp" | 运行时类型。 |
status必填 | "starting" | "running" | "stopping" | "stopped" | runtime.status 为 starting、running、stopping 或 stopped；starting/stopping 仍占额度。runtimeKind 为 neko 或 worker_cdp。活动会话带 sessionId、expiresAt；只有 running 才可能带 connectUrl，可直接打开对应实例的交互界面，需使用档案所有者账号登录。neko 链接指向 API 域 /cloud-browser-runtime/{sessionId}/，不返回 cdpBaseUrl；固定 usr/pwd 参数是公共查看器协议值，访问权限仍由会话 Cookie 校验，不使用只读 cast 模式。worker_cdp 使用 CDP Studio，可返回带临时令牌的 cdpBaseUrl。请使用返回地址，勿自行拼接或向 URL 添加 API Key、Cookie、代理凭据。地址缺失时先查询真实状态。 |
sessionId | string | 活动会话 ID。 |
expiresAt | string (RFC3339) | 活动会话最大到期时间。 |
connectUrl | string | 可选的交互式云浏览器直达链接；需要档案所有者的登录会话。 |
cdpBaseUrl | string | 仅 worker_cdp 可返回。 |
cloudBrowser.quotas
limit 是套餐允许保存的档案数量；runningLimit 是用户同时运行上限；runningCount 统计该用户所有档案的 starting、running、stopping，会跨分页、API Key 和页面共享，不包含临时 /cdp/sessions。users.cloud_browser_running_limit 为 NULL 或负数时默认 1，0 禁止新启动，正数为上限。列表和每次启动实时读取；下调不会主动关闭已有实例。全局容量仍单独限制，不叠加临时 CDP 的每 Key 并发限制。
| 字段 | 类型 | 说明 |
|---|---|---|
limit必填 | integer | 可保存档案数量。 |
runningLimit必填 | integer | 用户同时运行上限。 |
runningCount必填 | integer | starting/running/stopping 总数。 |
browserSettings
CDP 会话的浏览器设置。不传地区时随机使用可信代理；可显式使用 GLOBAL、指定地区或传入自定义代理。
| 字段 | 类型 | 说明 |
|---|---|---|
viewport | { width: number; height: number } | 浏览器窗口尺寸。CDP 会话会转换成默认 window-size。 |
locale | string | 浏览器 locale，例如 en-US。 |
timezoneId | string | IANA 时区，例如 Asia/Shanghai。 |
geolocation | { latitude: number; longitude: number } | 可选地理位置。 |
proxy | proxy | 自定义代理配置；与 countryCode 不能同时使用。 |
countryCode | "GLOBAL" | string | 托管代理地区。GLOBAL 随机选择热门地区；指定地区优先可信代理并由动态代理兜底。不传时优先随机可信代理。 |
userAgent | string | 覆盖默认 User-Agent。 |
userAgentMode | "custom" | "random" | 设为 random 时由服务端从 User-Agent 库随机选择；未传 User-Agent 时默认使用 random。 |
userAgentOs | "windows" | "macos" | 随机模式使用的操作系统，默认 windows。 |
fingerprint | fingerprint | CDP 指纹设置。未显式设置时 canvas 与 webGlImage 默认为 real，其余省略信号按随机一致性档案生成。 |
cookies | cookies[] | 启动会话前预置的 Cookie 列表。 |
fingerprint
所有字段都可省略。浏览器任务的省略字段默认 random；CDP browserSettings 会把省略的 canvas 与 webGlImage 设为 real，其余信号按随机一致性档案生成。WebGL 为 real 时，WebGPU 与 hardware 不能设为 random。
| 字段 | 类型 | 说明 |
|---|---|---|
webRtc | "forward" | "real" | "disabled" | 转发使用代理出口地址；旧值 random 仍兼容并按 forward 处理。 |
webGl | "random" | "real" | WebGL 厂商与渲染器。 |
webGpu | "random" | "real" | "disabled" | 随机时跟随 WebGL GPU。 |
webGlImage | "random" | "real" | WebGL 图像噪声。 |
canvas | "random" | "real" | Canvas 噪声。 |
audioContext | "random" | "real" | 音频指纹噪声。 |
clientRects | "random" | "real" | 布局测量噪声。 |
speechVoices | "random" | "real" | 与操作系统匹配的语音列表。 |
fonts | "random" | "real" | 与操作系统匹配的字体列表。 |
hardware | "random" | "real" | 成组生成 CPU 线程数和内存。 |
doNotTrack | "random" | "enabled" | "disabled" | Do Not Track 偏好。 |
proxy
可选代理配置。使用 server，或使用 protocol + host + port，两种写法二选一；账号和密码必须成对提供。
| 字段 | 类型 | 说明 |
|---|---|---|
server | string | 完整代理地址，例如 http://host:port 或 socks5://host:port；不能包含账号密码，也不能与 host 同时传入。 |
protocol | "http" | "socks5" | 拆分写法的代理协议。 |
host | string | 拆分写法的代理主机。 |
port | number | numeric string | 拆分写法的 1-65535 端口。 |
username | string | 代理用户名。 |
password | string | 代理密码。 |
waitFor
SPA 导航和 actions 完成后等待可见元素或文本；selector 与 text 可同时使用。
| 字段 | 类型 | 说明 |
|---|---|---|
selector | string | 等待首个匹配元素可见。 |
text | string | 等待首个包含该文本的元素可见。 |
timeoutMs | number | 默认 15,000，且不会超过任务剩余超时。 |
field
SPA extract 字段定义。DOM 字段读取元素内容；network 字段读取最近一个 URL 匹配的 JSON 响应。
| 字段 | 类型 | 说明 |
|---|---|---|
source必填 | "dom" | "network" | 字段数据来源。 |
selector | string | DOM 字段的 CSS selector。 |
value | "text" | "html" | "attribute" | DOM 读取方式，默认 text。 |
attribute | string | value=attribute 时读取的属性名。 |
urlIncludes | string | network 字段用于匹配响应 URL 的子串。 |
path | string | network JSON 路径，例如 $.data.metrics[0].value。 |
multiple | boolean | DOM 字段是否返回所有匹配元素。 |
parse | "string" | "number" | "integer" | "boolean" | "json" | 对提取值进行类型转换。 |
regex | string | 可选正则；存在捕获组时优先返回第 1 组。 |
required | boolean | 缺失时任务返回 422 SPA_REQUIRED_FIELDS_MISSING。 |
actions[]
按数组顺序执行页面交互；单步交互超时不超过 30 秒。
| 字段 | 类型 | 说明 |
|---|---|---|
wait | { type: "wait"; milliseconds: number } | 暂停 0-30,000ms。 |
waitForSelector | { type: "waitForSelector"; selector: string; timeoutMs?: number } | 等待首个匹配元素可见。 |
click | { type: "click"; selector: string } | 点击首个匹配元素。 |
fill | { type: "fill"; selector: string; value: string } | 清空并填写首个匹配输入框。 |
press | { type: "press"; selector: string; key: string } | 向首个匹配元素发送按键。 |
scroll | { type: "scroll"; selector?: string; x?: number; y?: number } | 滚动到元素，或按 x/y 滚动页面；默认 y=800。 |
Google Trends result metadata
google-trends-explore 成功响应在通用 SPA 结果之外返回的顶层采集来源与缓存元数据。
| 字段 | 类型 | 说明 |
|---|---|---|
source必填 | "sunbrowser" | "cache" | 结果来自 SunBrowser 实时采集或服务端缓存。 |
cached必填 | boolean | 本次响应是否命中缓存。 |
stale必填 | boolean | 返回的缓存结果是否已过新鲜期。 |
collectedAt必填 | string (RFC3339Nano) | 结果实际采集时间。 |
attempts必填 | non-negative integer | 结果携带的采集尝试次数；缓存 HIT 为 0，STALE 在 Worker 有报告时返回实际已发生的尝试数。 |
