跳转到主要内容
POST
网页研究
搜索和获取公开网页内容。所有操作返回规范化 output，以及最后一个 Run 的 id、provider 和生命周期 status。search 返回 output.results[]；news、places、scholar、shopping、images、videos、similar 返回每行字段固定的 output.items[]；answer 返回 output.answer 和 citations[]；scrape 返回固定内容字段。 对于 scrape，读取 output.text、output.markdown、output.html 和 output.raw_html，缺失格式为 null，不将 HTML 转换为文本。output 不重复数据提供商原生输出；请通过 GET /v1/runs/:id 从 Run 读取。search 读取 output.results[]。 分别检查 result_status 和 status：前者为 success、partial、no_result、error 或 pending。COMPLETED 表示最终 Run 收到数据提供商响应并已结算，不保证内容可用。交付失败或等待中时 output 为 null；partial 会列出 missing_formats。内容语义未经验证，不通过措辞和长度判断质量。 charge_usd 汇总本响应 runs 的费用，包括收费的失败和空结果，所有 Run 结算前为 null。runs[] 包含各自费用、状态和 charge_basis，不重复正文。多个 Run 的汇总 charge_basis 为 null。响应是 Solution 结果，不是存储的 Run；GET /v1/runs/:id 仍返回原生输出和单笔费用。 对于 QUEUED/RUNNING，即 HTTP 202，在 API 服务地址上使用认证轮询 result_url。该读取返回相同的规范化结构和费用总和，不创建 Run，也不恢复切换。终态结果返回 HTTP 200，包括业务错误；请检查 result_status 和 error。有意重试时复用相同 Idempotency-Key 和执行参数。 Scrape 自动模式在默认 30000 毫秒请求预算内先用 Serper，再用 Firecrawl。HTML 或显式缓存年龄请求直接使用 Firecrawl。X/Twitter 和 LinkedIn 信息补全排除 Firecrawl；Exa 和 DataForSEO 只能显式指定。指定数据提供商时不切换。当其他路径可能改善交付时，空或无效输出、数据提供商错误、超时和缺少受支持格式可触发切换。不跨数据提供商合并内容。未受理任何 Run 时，返回受理错误。 省略 formats 时，Serper/Exa 检查 text，Firecrawl/DataForSEO 检查 markdown；所有可用原生格式均映射到 output。max_charge_usd 覆盖本请求全部 Run，包括重放。预算仅保存在请求内存中；重试会开始新时间窗口，但不能改变已有 Run 的截止时间。 Search 的 time_range 支持 day、week、month、year。自动模式选择支持该过滤的数据提供商。空搜索结果不会触发付费切换。

​
各操作输出

各操作的规范化字段。数据提供商原生输出不在此重复，保留在 Run 中，可通过 GET /v1/runs/:id 读取。未报告的值为 null。
  • search: results[]: url, title, snippet ，Google 摘要；Exa 为提取片段, position, published_at, date_text, date ，已弃用
  • news: items[]: title, url, source, published_at, date_text, snippet
  • places: items[]: name, address ，数据提供商原生文本，可能仅含街道, category, rating ，1–5, reviews, phone, website, latitude, longitude, google_cid
  • scholar: items[]: title, url, snippet, publication, year, cited_by, pdf_url
  • shopping: items[]: title, url ，Google Shopping 页面, merchant_url, google_product_id, price_text, seller, rating ，1–5, reviews, image_url
  • images: items[]: title, image_url, thumbnail_url, source_url, source, width, height
  • videos: items[]: title, url, channel, source, date_text, duration_text, snippet, thumbnail_url
  • answer: answer, citations[]: url, title, published_at
  • scrape: url, final_url, title, text, markdown, html, raw_html, text_character_limit, cached, fetched_at, quality ，已弃用
  • similar: items[]: url, title, exa_similarity_score, published_at, author
published_at 为 ISO 8601 UTC，仅根据数据提供商机器时间戳填写。date_text 为 Google 原样日期文本，可能相对于 Run 的 completed_at，不解析。rating 为 Google 1–5 平均星级；reviews 为数量。source 为出版方或网站名称。exa_similarity_score 为 Exa 自身分数，只宜在同一响应内比较。

请求头

​
idempotency-key
string
必填

为每次预期执行生成唯一值，推荐使用 UUID。使用同一个键和执行参数重试，可读取原 Run，避免再次扣费。使用同一个键但修改执行参数会返回 409；修改 task_id 或 metadata 不会更新原 Run。

Minimum string length: 1

请求体

application/json
​
action
enum<string> | null

默认为 search。

  • search、news、places、scholar、shopping、images、videos、answer 提供 query。
  • scrape 或 similar 提供 url。
可用选项:
search,
news,
places,
scholar,
shopping,
images,
videos,
answer,
scrape,
similar
​
provider
enum<string> | null

默认为 auto，按 Glasser 偏好顺序选择第一家符合条件的数据提供商。指定的数据提供商必须支持请求且获得当前 API Key 的允许，不会切换到其他家。可用值见下方。

可用选项:
auto,
serper,
serpapi,
exa,
dataforseo,
firecrawl
​
query
string | null
Required string length: 1 - 500
​
url
string | null
Required string length: 1 - 2048
​
formats
enum<string>[]

仅用于 scrape。省略时使用所选数据提供商的原生默认格式：Serper/Exa 为 text，Firecrawl/DataForSEO 为 markdown。请求格式用于路由和切换；输出提供固定的 text/markdown/html/raw_html 字段。html 为清理后的 HTML，raw_html 为原始 HTML。自动模式先用 Serper，再用 Firecrawl；HTML 请求直接使用 Firecrawl。通过 result_status 和 missing_formats 判断交付情况；未请求字段为 null 不代表 partial。Firecrawl 不提供 text，Glasser 不将 HTML 转成文本。X/Twitter 和信息补全路径排除 Firecrawl。

Required array length: 1 - 4 elements
可用选项:
text,
markdown,
html,
raw_html
​
timeout_ms
integer

仅用于 scrape，默认为 90000。本次 API 请求的执行预算，包括串行切换。每次数据提供商调用都以所属 Endpoint 的自身窗口开启，而不是分享剩余时间；当该窗口连同结算时间装进剩余预算时，这一跳保留完整窗口。完整窗口会超出请求预算时，Serper、Firecrawl 与 Exa 仍按实际剩余时间运行至所属 Endpoint 窗口，并预留结算与响应时间；只有剩余调用时间少于一秒时才跳过这一跳。重试会开始新的请求窗口，并通过 Run 幂等机制复用已有 Run。

必填范围: 1000 <= x <= 120000
​
max_charge_usd
string

精确的美元十进制字符串，小数位数为 2–6，采用唯一规范格式。求和时使用十进制运算或乘以 10^6 转为整数，不使用浮点数。

Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
​
cache_max_age_seconds
integer

仅用于 scrape。数据提供商缓存的最大年龄；0 表示必须实时抓取。不支持此控制的路径将被排除。自动模式选择 Firecrawl，单位转换为毫秒；显式选择 Exa 时向下取整为小时。未知缓存和抓取元数据保留为 null。

必填范围: 0 <= x <= 2592000
​
time_range
enum<string>

仅用于 search：通过 Google 时间过滤，将结果限制为最近一天、一周、一个月或一年；省略则不限时间。自动模式只使用支持该过滤的数据提供商，即 Serper 和 SerpApi。提供此字段时拒绝 Exa。这是搜索引擎过滤，不是已验证的发布日期。

可用选项:
day,
week,
month,
year
​
country
string | null

搜索类操作的国家，使用两位 ISO 代码或国家名称，默认为 us。不用于 scrape 或 similar。指定的数据提供商无法应用时，返回 400。

Required string length: 2 - 60
​
language
string | null

搜索类操作的语言，使用 en、de 等两位代码。不用于 scrape 或 similar。

Pattern: ^[A-Za-z]{2}$
​
limit
integer | null

返回条数。请从较少条数开始：路由到的接口可能据此计费。各能力还会进一步限制上限。

必填范围: 1 <= x <= 100
​
task_id
string | null

将相关 Run，包括自动切换产生的 Run，归入同一个 Task。复用稳定字符串，并通过 Task 筛选 Run 列表。

​
metadata

可选追踪字段，随 Run 返回，也可用于筛选。不会发送给数据提供商，也不影响路由、价格或幂等。

  • 最多 20 个键：小写字母、数字和下划线，以字母开头，最长 40 个字符。
  • 值：长度为 1–500 的字符串。
  • user_id：终端用户的不透明 ID，不得使用邮箱或姓名。

无效条目整体丢弃，不截断。请求继续执行，Run 返回实际保存的字段。

响应

成功

​
id
string
必填
​
run_url
string
必填

在控制台打开 Run，需要工作空间成员权限。

​
provider
string
必填
Pattern: ^[a-z0-9][a-z0-9-]*$
​
endpoint
string
必填
Pattern: ^\/.+$
​
endpoint_version
integer
必填
​
status
enum<string>
必填

QUEUED 或 RUNNING 表示仍在执行。COMPLETED 表示已有数据提供商响应，包括非 2xx 响应。FAILED 请读取 failure。STOPPED 表示分派前停止。charge_usd 与状态分别检查。

可用选项:
QUEUED,
RUNNING,
COMPLETED,
FAILED,
STOPPED
​
failure
object | null
必填

Run 失败原因，仅在 status 为 FAILED 时非 null。

​
input
object
必填
​
output
object
必填

各操作的规范化字段。数据提供商原生输出不在此重复，保留在 Run 中，可通过 GET /v1/runs/:id 读取。未报告的值为 null。

  • search: results[]: url, title, snippet ，Google 摘要；Exa 为提取片段, position, published_at, date_text, date ，已弃用
  • news: items[]: title, url, source, published_at, date_text, snippet
  • places: items[]: name, address ，数据提供商原生文本，可能仅含街道, category, rating ，1–5, reviews, phone, website, latitude, longitude, google_cid
  • scholar: items[]: title, url, snippet, publication, year, cited_by, pdf_url
  • shopping: items[]: title, url ，Google Shopping 页面, merchant_url, google_product_id, price_text, seller, rating ，1–5, reviews, image_url
  • images: items[]: title, image_url, thumbnail_url, source_url, source, width, height
  • videos: items[]: title, url, channel, source, date_text, duration_text, snippet, thumbnail_url
  • answer: answer, citations[]: url, title, published_at
  • scrape: url, final_url, title, text, markdown, html, raw_html, text_character_limit, cached, fetched_at, quality ，已弃用
  • similar: items[]: url, title, exa_similarity_score, published_at, author

published_at 为 ISO 8601 UTC，仅根据数据提供商机器时间戳填写。date_text 为 Google 原样日期文本，可能相对于 Run 的 completed_at，不解析。rating 为 Google 1–5 平均星级；reviews 为数量。source 为出版方或网站名称。exa_similarity_score 为 Exa 自身分数，只宜在同一响应内比较。

​
provider_response
object | null
必填

仅在 status 为 COMPLETED 时非 null。

  • 2xx 响应：output 为任意结构的数据提供商原生 JSON；正文为空时为 null。
  • 非 2xx 响应：error 包含数据提供商错误正文，output 为 null。

两种正文均会移除敏感字段。

​
charge_usd
string | null
必填

此 Solution 响应所含 runs 的总费用，全部 Run 结算前为 null。每个 Run 保留各自费用；失败也可能收费。

Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
​
charge_basis
object | null
必填

单个 Run 的计费依据；多个 Run 汇总时为 null。各项费用请查看 runs[].charge_basis。

​
stoppable
boolean
必填

当前是否可接受停止请求。不保证能在分派前停止 Run。

​
stop_requested_at
string<date-time> | null
必填

请求停止的时间。如果已开始分派，Run 仍可能继续。

​
created_at
string<date-time>
必填

ISO 8601 UTC 时间戳。

​
started_at
string<date-time> | null
必填

ISO 8601 UTC 时间戳。

​
completed_at
string<date-time> | null
必填

ISO 8601 UTC 时间戳。

​
task_id
string | null
必填
​
metadata
object
必填

已保存的追踪字段，可用于筛选 Run，不发送给数据提供商，不影响路由、价格或幂等。

  • 最多 20 个键：小写字母、数字和下划线，以字母开头，最长 40 个字符。
  • 值：长度为 1–500 的字符串。
  • user_id：终端用户的不透明 ID，不得使用邮箱或姓名。
​
action
enum<string>
必填
可用选项:
search,
news,
places,
scholar,
shopping,
images,
videos,
answer,
scrape,
similar
​
result_status
enum<string>
必填

业务交付状态，与 status 中的最终 Run 生命周期独立。success 不代表内容语义质量已验证。

可用选项:
success,
partial,
no_result,
error,
pending
​
missing_formats
enum<string>[]
必填
可用选项:
text,
markdown,
html,
raw_html
​
error
object | null
必填
​
runs
object[]
必填
​
result_url
string
必填

通过认证读取规范化结果和总费用的只读 URL 路径，配合 API 服务地址使用。不创建 Run，也不恢复切换。GET /v1/runs/:id 仍返回原生单个 Run。