> ## Documentation Index > Fetch the complete documentation index at: https://glasser.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # 网页研究 > 搜索网页和新闻，获取地点、购物结果和页面内容，并以统一结构返回。 搜索和获取公开网页内容。所有操作返回规范化 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 自身分数，只宜在同一响应内比较。 ```json { "action": "news", "provider": "serper", "status": "COMPLETED", "result_status": "success", "output": { "items": [ { "title": "Ripple, Stripe-owned Privy partner to bring embedded wallets to XRP Ledger", "url": "https://www.theblock.co/news/business/2026-10-13-stripe-privy-ripple-xrp-ledger-wallets-418463", "source": "The Block", "published_at": null, "date_text": "18 hours ago", "snippet": "The integration will allow developers to add XRP Ledger wallets to their apps using Privy's infrastructure." } ] }, "charge_usd": "0.0011", "runs": [{ "provider": "serper", "status": "COMPLETED", "charge_usd": "0.0011" }], "result_url": "/v1/solutions/gtm/web_research/result?token=…" } ``` ## OpenAPI ````yaml /openapi.zh.json post /v1/solutions/gtm/web_research openapi: 3.1.0 info: title: Glasser version: 0.0.1 description: 一个 API Key，无需合同，按次付费，即可调用批量采购的付费 API。每个响应包含 x-request-id；所有错误正文采用统一结构。 servers: - url: https://api.glasser.ai security: [] tags: - name: Solutions - name: Endpoints - name: Runs - name: Balance paths: /v1/solutions/gtm/web_research: post: tags: - Solutions summary: 网页研究 description: >- 搜索和获取公开网页内容。所有操作返回规范化 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 自动模式在默认 90000 毫秒请求预算内先用 Serper，再用 Firecrawl。每次数据提供商调用都以所属 Endpoint 的自身窗口开启；当该窗口会超出请求预算时，Serper、Firecrawl 与 Exa 仍按实际剩余时间运行，并预留结算及响应时间。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。自动模式选择支持该过滤的数据提供商。空搜索结果不会触发付费切换。 operationId: gtm-web-research parameters: - name: idempotency-key in: header schema: type: string minLength: 1 description: >- 为每次预期执行生成唯一值，推荐使用 UUID。使用同一个键和执行参数重试，可读取原 Run，避免再次扣费。使用同一个键但修改执行参数会返回 409；修改 task_id 或 metadata 不会更新原 Run。 required: true requestBody: content: application/json: schema: type: object properties: action: anyOf: - type: string enum: - search - news - places - scholar - shopping - images - videos - answer - scrape - similar description: >- 默认为 search。 - search、news、places、scholar、shopping、images、videos、answer 提供 query。 - scrape 或 similar 提供 url。 - type: 'null' provider: anyOf: - type: string enum: - auto - serper - serpapi - exa - dataforseo - firecrawl description: >- 默认为 auto，按 Glasser 偏好顺序选择第一家符合条件的数据提供商。指定的数据提供商必须支持请求且获得当前 API Key 的允许，不会切换到其他家。可用值见下方。 - type: 'null' query: anyOf: - type: string minLength: 1 maxLength: 500 - type: 'null' url: anyOf: - type: string minLength: 1 maxLength: 2048 - type: 'null' formats: type: array items: type: string enum: - text - markdown - html - raw_html minItems: 1 maxItems: 4 description: >- 仅用于 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。 timeout_ms: type: integer minimum: 1000 maximum: 120000 description: >- 仅用于 scrape，默认为 90000。本次 API 请求的执行预算，包括串行切换。每次数据提供商调用都以所属 Endpoint 的自身窗口开启，而不是分享剩余时间；当该窗口连同结算时间装进剩余预算时，这一跳保留完整窗口。完整窗口会超出请求预算时，Serper、Firecrawl 与 Exa 仍按实际剩余时间运行至所属 Endpoint 窗口，并预留结算与响应时间；只有剩余调用时间少于一秒时才跳过这一跳。重试会开始新的请求窗口，并通过 Run 幂等机制复用已有 Run。 max_charge_usd: type: string pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$ description: >- 精确的美元十进制字符串，小数位数为 2–6，采用唯一规范格式。求和时使用十进制运算或乘以 10^6 转为整数，不使用浮点数。 allOf: - pattern: ^\d{1,12}\. description: >- 仅用于 scrape。本请求全部 Run 的最高总费用，包括重放 Run。受理新 Run 前，已结算费用加上其最高费用不得超过此值。存在未结算 Run 时停止切换。省略表示调用方不设上限；0.00 不允许新建付费 Run。 cache_max_age_seconds: type: integer minimum: 0 maximum: 2592000 description: >- 仅用于 scrape。数据提供商缓存的最大年龄；0 表示必须实时抓取。不支持此控制的路径将被排除。自动模式选择 Firecrawl，单位转换为毫秒；显式选择 Exa 时向下取整为小时。未知缓存和抓取元数据保留为 null。 time_range: type: string enum: - day - week - month - year description: >- 仅用于 search：通过 Google 时间过滤，将结果限制为最近一天、一周、一个月或一年；省略则不限时间。自动模式只使用支持该过滤的数据提供商，即 Serper 和 SerpApi。提供此字段时拒绝 Exa。这是搜索引擎过滤，不是已验证的发布日期。 country: anyOf: - type: string minLength: 2 maxLength: 60 description: >- 搜索类操作的国家，使用两位 ISO 代码或国家名称，默认为 us。不用于 scrape 或 similar。指定的数据提供商无法应用时，返回 400。 - type: 'null' language: anyOf: - type: string pattern: ^[A-Za-z]{2}$ description: 搜索类操作的语言，使用 en、de 等两位代码。不用于 scrape 或 similar。 - type: 'null' limit: anyOf: - type: integer minimum: 1 maximum: 100 description: 返回条数。请从较少条数开始：路由到的接口可能据此计费。各能力还会进一步限制上限。 - type: 'null' task_id: anyOf: - type: string description: >- 将相关 Run，包括自动切换产生的 Run，归入同一个 Task。复用稳定字符串，并通过 Task 筛选 Run 列表。 - type: 'null' metadata: anyOf: - anyOf: - type: object additionalProperties: type: string minLength: 1 maxLength: 500 maxProperties: 20 propertyNames: type: string pattern: ^[a-z][a-z0-9_]{0,39}$ - {} description: |- 可选追踪字段，随 Run 返回，也可用于筛选。不会发送给数据提供商，也不影响路由、价格或幂等。 - 最多 20 个键：小写字母、数字和下划线，以字母开头，最长 40 个字符。 - 值：长度为 1–500 的字符串。 - user_id：终端用户的不透明 ID，不得使用邮箱或姓名。 无效条目整体丢弃，不截断。请求继续执行，Run 返回实际保存的字段。 - type: 'null' additionalProperties: false required: true responses: '200': description: 成功 content: application/json: schema: anyOf: - $ref: '#/components/schemas/WebResearchResult' '202': description: 成功 content: application/json: schema: anyOf: - $ref: '#/components/schemas/WebResearchResult' '400': description: ValidationFailed | IdempotencyKeyRequired content: application/json: schema: anyOf: - $ref: '#/components/schemas/ValidationFailedEncoded' - $ref: '#/components/schemas/IdempotencyKeyRequiredEncoded' - $ref: '#/components/schemas/ValidationFailedEncoded' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthorizedEncoded' '402': description: InsufficientBalance content: application/json: schema: $ref: '#/components/schemas/InsufficientBalanceEncoded' '403': description: EndpointNotPermitted | Forbidden content: application/json: schema: anyOf: - $ref: '#/components/schemas/EndpointNotPermittedEncoded' - $ref: '#/components/schemas/ForbiddenEncoded' '409': description: IdempotencyConflict content: application/json: schema: $ref: '#/components/schemas/IdempotencyConflictEncoded' '429': description: RateLimited content: application/json: schema: $ref: '#/components/schemas/RateLimitedEncoded' '503': description: ServiceUnavailable content: application/json: schema: $ref: '#/components/schemas/ServiceUnavailableEncoded' security: - bearer: [] components: schemas: WebResearchResult: type: object properties: id: type: string run_url: type: string description: 在控制台打开 Run，需要工作空间成员权限。 provider: type: string pattern: ^[a-z0-9][a-z0-9-]*$ endpoint: type: string pattern: ^\/.+$ endpoint_version: type: integer exclusiveMinimum: 0 status: type: string enum: - QUEUED - RUNNING - COMPLETED - FAILED - STOPPED description: >- QUEUED 或 RUNNING 表示仍在执行。COMPLETED 表示已有数据提供商响应，包括非 2xx 响应。FAILED 请读取 failure。STOPPED 表示分派前停止。charge_usd 与状态分别检查。 failure: anyOf: - type: object properties: kind: type: string enum: - TIMED_OUT - INTERNAL message: type: string required: - kind - message additionalProperties: false - type: 'null' description: Run 失败原因，仅在 status 为 FAILED 时非 null。 input: type: object output: anyOf: - anyOf: - type: object properties: url: type: string description: 请求的 URL；数据提供商报告最终 URL 时，使用最终 URL。 final_url: anyOf: - type: string - type: 'null' description: 数据提供商报告的重定向后 URL，适用于 Firecrawl、Exa。未报告时为 null。 title: anyOf: - type: string - type: 'null' text: anyOf: - type: string - type: 'null' markdown: anyOf: - type: string - type: 'null' html: anyOf: - type: string - type: 'null' raw_html: anyOf: - type: string - type: 'null' text_character_limit: anyOf: - type: integer - type: 'null' description: >- Glasser 要求数据提供商应用的文本字符上限，Exa 为 10000。文本长度恰好达到此值时可能已截断；未设上限时为 null。 cached: anyOf: - type: boolean - type: 'null' description: >- 数据提供商是否从缓存返回页面，取自 Firecrawl cacheState 或 Exa status source。未说明时为 null。 fetched_at: anyOf: - type: string - type: 'null' description: >- 数据提供商抓取页面的时间，ISO 8601 UTC，取自 DataForSEO fetch_time。未报告时为 null。 quality: type: string enum: - unverified description: 已弃用：始终为 unverified，不执行内容检查。为兼容保留，将在下一次不兼容修订中移除。 required: - url - final_url - title - text - markdown - html - raw_html - text_character_limit - cached - fetched_at - quality additionalProperties: false - type: object properties: results: type: array items: type: object properties: url: type: string title: anyOf: - type: string - type: 'null' snippet: anyOf: - type: string - type: 'null' description: >- Google 的简短摘要，适用于 Serper/SerpApi；Exa 则为提取的高亮片段。不是完整页面文本。 position: type: integer date: anyOf: - type: string - type: 'null' description: >- 已弃用，请使用 published_at 或 date_text。Serper/SerpApi 为 Google 展示文本，Exa 为原始 publishedDate。 published_at: anyOf: - type: string - type: 'null' description: >- ISO 8601 UTC 时间戳，仅在数据提供商报告机器时间戳时填写，例如 Exa publishedDate、SerpApi news iso_date，否则为 null。 date_text: anyOf: - type: string - type: 'null' description: >- 数据提供商原样返回的 Google 日期展示文本，即 Serper/SerpApi date。可能相对于 Run 的 completed_at，例如 '3 hours ago'，不解析。 required: - url - title - snippet - position - date - published_at - date_text additionalProperties: false required: - results additionalProperties: false - type: object properties: items: type: array items: type: object properties: title: anyOf: - type: string - type: 'null' url: anyOf: - type: string - type: 'null' source: anyOf: - type: string - type: 'null' description: 数据提供商展示的出版方或网站名称。 published_at: anyOf: - type: string - type: 'null' description: >- ISO 8601 UTC 时间戳，仅在数据提供商报告机器时间戳时填写，例如 Exa publishedDate、SerpApi news iso_date，否则为 null。 date_text: anyOf: - type: string - type: 'null' description: >- 数据提供商原样返回的 Google 日期展示文本，即 Serper/SerpApi date。可能相对于 Run 的 completed_at，例如 '3 hours ago'，不解析。 snippet: anyOf: - type: string - type: 'null' required: - title - url - source - published_at - date_text - snippet additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: name: anyOf: - type: string - type: 'null' address: anyOf: - type: string - type: 'null' description: 数据提供商原生地址文本，不解析或补全。Serper 可能只返回街道。 category: anyOf: - type: string - type: 'null' rating: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: Google 平均星级评分，1–5。 reviews: anyOf: - type: integer - type: 'null' description: 评分对应的 Google 评论数。 phone: anyOf: - type: string - type: 'null' website: anyOf: - type: string - type: 'null' latitude: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' longitude: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' google_cid: anyOf: - type: string - type: 'null' description: >- 地点的 Google Maps CID，取自 Serper cid 或 SerpApi data_cid。 required: - name - address - category - rating - reviews - phone - website - latitude - longitude - google_cid additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: title: anyOf: - type: string - type: 'null' url: anyOf: - type: string - type: 'null' snippet: anyOf: - type: string - type: 'null' publication: anyOf: - type: string - type: 'null' year: anyOf: - type: integer - type: 'null' cited_by: anyOf: - type: integer - type: 'null' pdf_url: anyOf: - type: string - type: 'null' required: - title - url - snippet - publication - year - cited_by - pdf_url additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: title: anyOf: - type: string - type: 'null' url: anyOf: - type: string - type: 'null' description: Google Shopping 商品页面。 merchant_url: anyOf: - type: string - type: 'null' description: 数据提供商报告的商家报价 URL，取自 SerpApi link；Serper 为 null。 google_product_id: anyOf: - type: string - type: 'null' description: >- Google Shopping 商品 ID，取自 Serper productId 或 SerpApi product_id。 price_text: anyOf: - type: string - type: 'null' description: 数据提供商的价格展示文本，例如 '$69.00'，不解析，币种取决于 country。 seller: anyOf: - type: string - type: 'null' rating: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: Google 平均星级评分，1–5。 reviews: anyOf: - type: integer - type: 'null' description: 评分对应的 Google 评论数。 image_url: anyOf: - type: string - type: 'null' required: - title - url - merchant_url - google_product_id - price_text - seller - rating - reviews - image_url additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: title: anyOf: - type: string - type: 'null' image_url: anyOf: - type: string - type: 'null' thumbnail_url: anyOf: - type: string - type: 'null' source_url: anyOf: - type: string - type: 'null' source: anyOf: - type: string - type: 'null' description: 数据提供商展示的出版方或网站名称。 width: anyOf: - type: integer - type: 'null' height: anyOf: - type: integer - type: 'null' required: - title - image_url - thumbnail_url - source_url - source - width - height additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: title: anyOf: - type: string - type: 'null' url: anyOf: - type: string - type: 'null' channel: anyOf: - type: string - type: 'null' source: anyOf: - type: string - type: 'null' description: 数据提供商展示的视频平台，例如 YouTube。 date_text: anyOf: - type: string - type: 'null' description: >- 数据提供商原样返回的 Google 日期展示文本，即 Serper/SerpApi date。可能相对于 Run 的 completed_at，例如 '3 hours ago'，不解析。 duration_text: anyOf: - type: string - type: 'null' description: 原样返回的时长文本，例如 '4:39'。 snippet: anyOf: - type: string - type: 'null' thumbnail_url: anyOf: - type: string - type: 'null' required: - title - url - channel - source - date_text - duration_text - snippet - thumbnail_url additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: url: anyOf: - type: string - type: 'null' title: anyOf: - type: string - type: 'null' exa_similarity_score: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: Exa 对此页面的自身相似度分数，只宜在同一响应内比较，不能与其他数据提供商分数直接比较。 published_at: anyOf: - type: string - type: 'null' description: >- ISO 8601 UTC 时间戳，仅在数据提供商报告机器时间戳时填写，例如 Exa publishedDate、SerpApi news iso_date，否则为 null。 author: anyOf: - type: string - type: 'null' required: - url - title - exa_similarity_score - published_at - author additionalProperties: false required: - items additionalProperties: false - type: object properties: answer: anyOf: - type: string - type: 'null' citations: type: array items: type: object properties: url: anyOf: - type: string - type: 'null' title: anyOf: - type: string - type: 'null' published_at: anyOf: - type: string - type: 'null' description: >- ISO 8601 UTC 时间戳，仅在数据提供商报告机器时间戳时填写，例如 Exa publishedDate、SerpApi news iso_date，否则为 null。 required: - url - title - published_at additionalProperties: false required: - answer - citations additionalProperties: false - type: 'null' description: >- 各操作的规范化字段。数据提供商原生输出不在此重复，保留在 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: anyOf: - type: object properties: http_status: type: integer minimum: 100 maximum: 599 description: 数据提供商返回的 HTTP 状态，即使 Run 为 COMPLETED 也应检查。 error: anyOf: - {} - type: 'null' required: - http_status additionalProperties: false - type: 'null' description: |- 仅在 status 为 COMPLETED 时非 null。 - 2xx 响应：output 为任意结构的数据提供商原生 JSON；正文为空时为 null。 - 非 2xx 响应：error 包含数据提供商错误正文，output 为 null。 两种正文均会移除敏感字段。 charge_usd: anyOf: - type: string pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$ description: 精确的美元十进制字符串，小数位数为 2–6，采用唯一规范格式。求和时使用十进制运算或乘以 10^6 转为整数，不使用浮点数。 - type: 'null' description: 此 Solution 响应所含 runs 的总费用，全部 Run 结算前为 null。每个 Run 保留各自费用；失败也可能收费。 charge_basis: anyOf: - type: object properties: clause: type: string enum: - rule - NO_RESULT - PROVIDER_ERROR - TIMED_OUT - INTERNAL quantity: anyOf: - type: integer minimum: 0 - type: 'null' required: - clause - quantity additionalProperties: false - type: 'null' description: 单个 Run 的计费依据；多个 Run 汇总时为 null。各项费用请查看 runs[].charge_basis。 stoppable: type: boolean description: 当前是否可接受停止请求。不保证能在分派前停止 Run。 stop_requested_at: anyOf: - type: string description: ISO 8601 UTC 时间戳。 format: date-time - type: 'null' description: 请求停止的时间。如果已开始分派，Run 仍可能继续。 created_at: type: string description: ISO 8601 UTC 时间戳。 format: date-time started_at: anyOf: - type: string description: ISO 8601 UTC 时间戳。 format: date-time - type: 'null' completed_at: anyOf: - type: string description: ISO 8601 UTC 时间戳。 format: date-time - type: 'null' task_id: anyOf: - type: string - type: 'null' metadata: type: object additionalProperties: type: string minLength: 1 maxLength: 500 maxProperties: 20 propertyNames: type: string pattern: ^[a-z][a-z0-9_]{0,39}$ description: |- 已保存的追踪字段，可用于筛选 Run，不发送给数据提供商，不影响路由、价格或幂等。 - 最多 20 个键：小写字母、数字和下划线，以字母开头，最长 40 个字符。 - 值：长度为 1–500 的字符串。 - user_id：终端用户的不透明 ID，不得使用邮箱或姓名。 action: type: string enum: - search - news - places - scholar - shopping - images - videos - answer - scrape - similar result_status: type: string enum: - success - partial - no_result - error - pending description: 业务交付状态，与 status 中的最终 Run 生命周期独立。success 不代表内容语义质量已验证。 missing_formats: type: array items: type: string enum: - text - markdown - html - raw_html error: anyOf: - type: object properties: code: type: string message: type: string required: - code - message additionalProperties: false - type: 'null' runs: type: array items: type: object properties: id: type: string run_url: type: string description: 在控制台打开 Run，需要工作空间成员权限。 provider: type: string pattern: ^[a-z0-9][a-z0-9-]*$ endpoint: type: string pattern: ^\/.+$ endpoint_version: type: integer exclusiveMinimum: 0 status: type: string enum: - QUEUED - RUNNING - COMPLETED - FAILED - STOPPED description: >- QUEUED 或 RUNNING 表示仍在执行。COMPLETED 表示已有数据提供商响应，包括非 2xx 响应。FAILED 请读取 failure。STOPPED 表示分派前停止。charge_usd 与状态分别检查。 failure: anyOf: - type: object properties: kind: type: string enum: - TIMED_OUT - INTERNAL message: type: string required: - kind - message additionalProperties: false - type: 'null' description: Run 失败原因，仅在 status 为 FAILED 时非 null。 input: type: object properties: omitted: type: boolean enum: - true required: - omitted additionalProperties: false output: type: object properties: omitted: type: boolean enum: - true required: - omitted additionalProperties: false provider_response: anyOf: - type: object properties: http_status: type: integer minimum: 100 maximum: 599 description: 数据提供商返回的 HTTP 状态，即使 Run 为 COMPLETED 也应检查。 required: - http_status additionalProperties: false - type: 'null' charge_usd: anyOf: - type: string pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$ description: >- 精确的美元十进制字符串，小数位数为 2–6，采用唯一规范格式。求和时使用十进制运算或乘以 10^6 转为整数，不使用浮点数。 - type: 'null' description: >- 最终费用，精确的美元十进制字符串。QUEUED 或 RUNNING 时为 null。FAILED 状态的 Run 仍可能按接口定价产生非零费用。 charge_basis: anyOf: - type: object properties: clause: type: string enum: - rule - NO_RESULT - PROVIDER_ERROR - TIMED_OUT - INTERNAL quantity: anyOf: - type: integer minimum: 0 - type: 'null' required: - clause - quantity additionalProperties: false - type: 'null' description: 计算费用所用的价格条款。结算前或未尝试调用数据提供商时为 null。 stoppable: type: boolean description: 当前是否可接受停止请求。不保证能在分派前停止 Run。 stop_requested_at: anyOf: - type: string description: ISO 8601 UTC 时间戳。 format: date-time - type: 'null' description: 请求停止的时间。如果已开始分派，Run 仍可能继续。 created_at: type: string description: ISO 8601 UTC 时间戳。 format: date-time started_at: anyOf: - type: string description: ISO 8601 UTC 时间戳。 format: date-time - type: 'null' completed_at: anyOf: - type: string description: ISO 8601 UTC 时间戳。 format: date-time - type: 'null' task_id: anyOf: - type: string - type: 'null' metadata: type: object additionalProperties: type: string minLength: 1 maxLength: 500 maxProperties: 20 propertyNames: type: string pattern: ^[a-z][a-z0-9_]{0,39}$ description: |- 已保存的追踪字段，可用于筛选 Run，不发送给数据提供商，不影响路由、价格或幂等。 - 最多 20 个键：小写字母、数字和下划线，以字母开头，最长 40 个字符。 - 值：长度为 1–500 的字符串。 - user_id：终端用户的不透明 ID，不得使用邮箱或姓名。 required: - id - run_url - provider - endpoint - endpoint_version - status - failure - input - output - provider_response - charge_usd - charge_basis - stoppable - stop_requested_at - created_at - started_at - completed_at - task_id - metadata additionalProperties: false result_url: type: string description: >- 通过认证读取规范化结果和总费用的只读 URL 路径，配合 API 服务地址使用。不创建 Run，也不恢复切换。GET /v1/runs/:id 仍返回原生单个 Run。 required: - id - run_url - provider - endpoint - endpoint_version - status - failure - input - output - provider_response - charge_usd - charge_basis - stoppable - stop_requested_at - created_at - started_at - completed_at - task_id - metadata - action - result_status - missing_formats - error - runs - result_url additionalProperties: false ValidationFailedEncoded: type: object properties: error: type: object properties: code: type: string enum: - validation_failed message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false IdempotencyKeyRequiredEncoded: type: object properties: error: type: object properties: code: type: string enum: - idempotency_key_required message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false UnauthorizedEncoded: type: object properties: error: type: object properties: code: type: string enum: - unauthorized message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false InsufficientBalanceEncoded: type: object properties: error: type: object properties: code: type: string enum: - insufficient_balance message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false EndpointNotPermittedEncoded: type: object properties: error: type: object properties: code: type: string enum: - endpoint_not_permitted message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false ForbiddenEncoded: type: object properties: error: type: object properties: code: type: string enum: - forbidden message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false IdempotencyConflictEncoded: type: object properties: error: type: object properties: code: type: string enum: - idempotency_conflict message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false RateLimitedEncoded: type: object properties: error: type: object properties: code: type: string enum: - rate_limited message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false ServiceUnavailableEncoded: type: object properties: error: type: object properties: code: type: string enum: - service_unavailable message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false securitySchemes: bearer: type: http scheme: Bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.