> ## 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. # SEO 研究 > 研究关键词、排名、外链、竞争差距、网站问题，以及 AI 回答中的引用。 研究关键词搜索量和难度、搜索排名、外链、与竞争对手的关键词和外链差距、排名历史、网站抓取、单页检查及 AI 回答引用。选择操作，并提供关键词、域名或页面 URL。 所有操作返回规范化 output，以及最后一个 Run 的 id、provider 和生命周期 status。列表类操作 keyword\_ideas、serp、ranked\_keywords、organic\_competitors、backlinks、referring\_domains、keyword\_gap、backlink\_gap、visibility\_history、ai\_citations，以及每个关键词一行的 keyword\_overview，均提供字段固定的 output.items\[]；概览类操作 domain\_overview、backlinks\_overview、domain\_rating、ai\_visibility、page\_audit、site\_audit 提供固定顶层字段。原生输出不在 output 中重复，保留在 Run 中，可通过 GET /v1/runs/:id 读取。所选数据提供商未报告的值为 null。数值为响应方自身数据；搜索量、流量和 CPC 为估算，只宜在同一家内比较。数据提供商自身模型分数带有名称，例如 ahrefs\_domain\_rating、semrush\_keyword\_difficulty，不在不同家之间换算。金额统一为美元。 分别检查 result\_status 和 status：前者为 success、no\_result、error 或 pending。COMPLETED 表示最终 Run 收到数据提供商响应并已结算；有效空结果为 no\_result，保留操作结构，items 为 \[] 或各字段为 null。错误或等待中时 output 为 null。 charge\_usd 汇总本响应 runs 的费用，包括收费空结果和失败，所有 Run 结算前为 null。runs\[] 包含各自费用和 charge\_basis，不重复正文；多个 Run 的汇总 charge\_basis 为 null。GET /v1/runs/:id 仍返回原生输出和单笔费用。 provider=auto 选择第一家符合条件的数据提供商，仅在 PROVIDER\_ERROR、TIMED\_OUT 或受理时 503 后尝试下一家。无结果和执行中的 Run 不触发切换。对于 QUEUED/RUNNING，即 HTTP 202，在 API 服务地址上使用认证轮询 result\_url。有意重试时复用相同 Idempotency-Key 和执行参数。 ## 各操作输出 各操作的规范化字段。原生输出保留在 Run 中，可通过 GET /v1/runs/:id 读取。未报告的值为 null，金额为美元。权威度保留响应方口径和名称，不换算：ahrefs\_domain\_rating 为 0–100，semrush\_authority\_score 为 0–100，dataforseo\_rank 为 0–1000，serpstat\_domain\_rank 为 0–100。关键词难度同样分为 semrush\_keyword\_difficulty、serpstat\_keyword\_difficulty、dataforseo\_keyword\_difficulty、ahrefs\_keyword\_difficulty，各自模型范围为 0–100。只填写实际响应方字段，其他家为 null。volume、traffic、cpc 为响应方估算，只宜在同一家内比较，见 runs\[].provider。有效空结果的 result\_status 为 no\_result，保留操作结构，items 为 \[] 或各字段为 null。 * keyword\_overview: items\[]: keyword, volume, cpc\_usd, semrush\_keyword\_difficulty, serpstat\_keyword\_difficulty, dataforseo\_keyword\_difficulty, ahrefs\_keyword\_difficulty, intent * keyword\_ideas: items\[]: 与 keyword\_overview 相同的行结构 * serp: items\[]: position ，自然排名，1 为第一条自然结果，不计 SERP 特殊结果, url, domain, title, snippet ，仅自然结果 * domain\_overview: organic\_keywords, organic\_traffic, organic\_traffic\_value\_usd, paid\_keywords, paid\_traffic * ranked\_keywords: items\[]: keyword, position ，自然排名，1 为第一条自然结果，不计 SERP 特殊结果, url, volume, cpc\_usd, traffic * organic\_competitors: items\[]: domain, common\_keywords, organic\_keywords ，竞争对手总数, organic\_traffic ，排除目标域及其子域 * backlinks\_overview: backlinks, referring\_domains, semrush\_authority\_score, dataforseo\_rank, serpstat\_domain\_rank, dofollow\_backlinks, nofollow\_backlinks * backlinks: items\[]: source\_url, target\_url, anchor, source\_ahrefs\_domain\_rating, source\_semrush\_authority\_score, source\_dataforseo\_rank, dofollow, first\_seen\_at ，ISO 8601 UTC；Semrush 未注明时区，不加 Z 后缀。各家均每个链接一行 * referring\_domains: items\[]: domain, ahrefs\_domain\_rating, semrush\_authority\_score, dataforseo\_rank, backlinks, dofollow\_backlinks, first\_seen\_at ，ISO 8601 UTC；Semrush 未注明时区，不加 Z 后缀 * domain\_rating: ahrefs\_domain\_rating * site\_audit: dataforseo\_task\_id ，用于 DataForSEO OnPage 报告接口的输入, crawl\_progress, crawl\_stop\_reason ，DataForSEO 词汇, pages\_crawled, dataforseo\_onpage\_score, broken\_links, non\_indexable, duplicate\_title, duplicate\_description, duplicate\_content * keyword\_gap: items\[]: keyword, volume, cpc\_usd, semrush\_keyword\_difficulty, dataforseo\_keyword\_difficulty, positions `{domain: 自然排名；null 表示不在前 100 名}`，键为传入域名。Semrush 返回任一域名有排名的关键词并集；DataForSEO 返回竞争对手有排名而你没有的关键词 * backlink\_gap: items\[]: domain, dataforseo\_rank, backlinks\_per\_target `{竞争域名: 数量}` * page\_audit: url, status\_code, title, description, canonical, dataforseo\_onpage\_score, internal\_links, external\_links * visibility\_history: items\[]: month, organic\_keywords, organic\_traffic, organic\_traffic\_value\_usd, paid\_keywords, paid\_traffic * ai\_citations: items\[]: url, platform, mentions, ai\_search\_volume, is\_target\_domain ，提及该域名的 AI 回答中被引用最多的页面，可来自任意网站 * ai\_visibility: ahrefs\_ai\_citations, ahrefs\_ai\_cited\_pages, ahrefs\_ai\_citations\_by\_platform `{platform: 引用次数}`, dataforseo\_ai\_mentions\_by\_platform `{platform: 提及次数}`, dataforseo\_ai\_search\_volume\_by\_platform `{platform: AI 搜索量}`。各家仅填自己的字段，不跨家汇总 ```json { "action": "ranked_keywords", "provider": "dataforseo", "status": "COMPLETED", "result_status": "success", "output": { "items": [ { "keyword": "zero interest business loan", "position": 1, "url": "https://stripe.com/resources/more/zero-interest-business-loans", "volume": 1600, "cpc_usd": 14.54, "traffic": 486.4 } ] }, "charge_usd": "0.01236", "runs": [{ "provider": "dataforseo", "status": "COMPLETED", "charge_usd": "0.01236" }], "result_url": "/v1/solutions/gtm/seo_research/result?token=…" } ``` ## OpenAPI ````yaml /openapi.zh.json post /v1/solutions/gtm/seo_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/seo_research: post: tags: - Solutions summary: SEO 研究 description: >- 研究关键词搜索量和难度、搜索排名、外链、与竞争对手的关键词和外链差距、排名历史、网站抓取、单页检查及 AI 回答引用。选择操作，并提供关键词、域名或页面 URL。 所有操作返回规范化 output，以及最后一个 Run 的 id、provider 和生命周期 status。列表类操作 keyword_ideas、serp、ranked_keywords、organic_competitors、backlinks、referring_domains、keyword_gap、backlink_gap、visibility_history、ai_citations，以及每个关键词一行的 keyword_overview，均提供字段固定的 output.items[]；概览类操作 domain_overview、backlinks_overview、domain_rating、ai_visibility、page_audit、site_audit 提供固定顶层字段。原生输出不在 output 中重复，保留在 Run 中，可通过 GET /v1/runs/:id 读取。所选数据提供商未报告的值为 null。数值为响应方自身数据；搜索量、流量和 CPC 为估算，只宜在同一家内比较。数据提供商自身模型分数带有名称，例如 ahrefs_domain_rating、semrush_keyword_difficulty，不在不同家之间换算。金额统一为美元。 分别检查 result_status 和 status：前者为 success、no_result、error 或 pending。COMPLETED 表示最终 Run 收到数据提供商响应并已结算；有效空结果为 no_result，保留操作结构，items 为 [] 或各字段为 null。错误或等待中时 output 为 null。 charge_usd 汇总本响应 runs 的费用，包括收费空结果和失败，所有 Run 结算前为 null。runs[] 包含各自费用和 charge_basis，不重复正文；多个 Run 的汇总 charge_basis 为 null。GET /v1/runs/:id 仍返回原生输出和单笔费用。 provider=auto 选择第一家符合条件的数据提供商，仅在 PROVIDER_ERROR、TIMED_OUT 或受理时 503 后尝试下一家。无结果和执行中的 Run 不触发切换。对于 QUEUED/RUNNING，即 HTTP 202，在 API 服务地址上使用认证轮询 result_url。有意重试时复用相同 Idempotency-Key 和执行参数。 operationId: gtm-seo-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: use_case: anyOf: - type: string description: >- 简述当前 SEO 任务，并包含研究对象。配合 task_id 使用时，会保存为 Task 描述，供结果复核和任务完成度评估。仅包含与任务相关的信息，不包含对话历史或无关个人信息。后续调用省略则保留原描述。 - type: 'null' action: anyOf: - type: string enum: - keyword_overview - keyword_ideas - serp - domain_overview - ranked_keywords - organic_competitors - backlinks_overview - backlinks - referring_domains - domain_rating - site_audit - ai_visibility - keyword_gap - backlink_gap - page_audit - visibility_history - ai_citations description: >- 默认为 keyword_overview。 - keyword_overview：提供一个或多个 keywords。 - keyword_ideas 或 serp：keywords 中必须恰好一个关键词。 - site_audit：提供 domain；limit 为抓取页数，默认 20，最多 100，异步运行。 - keyword_gap 和 backlink_gap：提供 domain 和一至四个 competitors。 - page_audit：提供单页 url。 - visibility_history：提供 domain；limit 为月数，默认 12，最多 24。 - 其他操作提供 domain。organic_competitors 查找相同关键词下排名的域名；ai_visibility 返回响应方自身口径的 AI 回答可见度，Ahrefs 为域名页面引用，DataForSEO 为 LLM 对域名的提及；ai_citations 返回提及该域名的 AI 回答中被引用最多的页面，可来自任意网站。 - keyword_gap 各家口径不同：Semrush 返回任一域名排名的关键词并集；DataForSEO 返回竞争对手有排名而你没有的关键词。 - type: 'null' provider: anyOf: - type: string enum: - auto - semrush - serpstat - dataforseo - ahrefs - serper description: >- 默认为 auto，按 Glasser 偏好顺序选择第一家符合条件的数据提供商。指定的数据提供商必须支持请求且获得当前 API Key 的允许，不会切换到其他家。可用值见下方。 - type: 'null' keywords: anyOf: - type: array items: type: string minLength: 1 maxLength: 200 minItems: 1 maxItems: 20 - type: 'null' domain: anyOf: - type: string minLength: 3 maxLength: 253 description: 网站域名，例如 stripe.com。也接受完整 URL，并提取主机名。 - type: 'null' competitors: anyOf: - type: array items: type: string minLength: 3 maxLength: 253 description: 网站域名，例如 stripe.com。也接受完整 URL，并提取主机名。 minItems: 1 maxItems: 4 description: keyword_gap 和 backlink_gap 的竞争域名，一至四个。完整 URL 会提取为主机名。 - type: 'null' url: anyOf: - type: string minLength: 1 maxLength: 2048 description: page_audit 的单页 URL，例如 https://stripe.com/pricing。 - type: 'null' country: anyOf: - type: string minLength: 2 maxLength: 60 description: >- 国家，使用两位 ISO 代码或名称，例如 us、gb、de、Germany。默认为 us。支持代码：us、gb、ca、au、nz、ie、in、sg、de、at、ch、fr、be、es、mx、ar、it、nl、pt、br、jp、kr、cn、hk、tw、ru、pl、se、no、dk、fi、tr、id、th、vn、ph、my、za、ae、il、sa、eg、ng、ua、cz、gr、hu、ro、co、cl、pe、lu。可用范围还取决于操作和数据提供商。不支持的国家会在创建 Run 前被拒绝。不要为了绕过错误而更换国家，这会改变请求的数据。 - 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/SeoResearchResult' '202': description: 成功 content: application/json: schema: anyOf: - $ref: '#/components/schemas/SeoResearchResult' '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: SeoResearchResult: 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: items: type: array items: type: object properties: keyword: anyOf: - type: string - type: 'null' volume: anyOf: - type: integer - type: 'null' cpc_usd: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' semrush_keyword_difficulty: anyOf: - type: integer - type: 'null' serpstat_keyword_difficulty: anyOf: - type: integer - type: 'null' dataforseo_keyword_difficulty: anyOf: - type: integer - type: 'null' ahrefs_keyword_difficulty: anyOf: - type: integer - type: 'null' intent: anyOf: - type: string - type: 'null' required: - keyword - volume - cpc_usd - semrush_keyword_difficulty - serpstat_keyword_difficulty - dataforseo_keyword_difficulty - ahrefs_keyword_difficulty - intent additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: position: anyOf: - type: integer - type: 'null' url: anyOf: - type: string - type: 'null' domain: anyOf: - type: string - type: 'null' title: anyOf: - type: string - type: 'null' snippet: anyOf: - type: string - type: 'null' required: - position - url - domain - title - snippet additionalProperties: false required: - items additionalProperties: false - type: object properties: organic_keywords: anyOf: - type: integer - type: 'null' organic_traffic: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' organic_traffic_value_usd: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' paid_keywords: anyOf: - type: integer - type: 'null' paid_traffic: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' required: - organic_keywords - organic_traffic - organic_traffic_value_usd - paid_keywords - paid_traffic additionalProperties: false - type: object properties: items: type: array items: type: object properties: keyword: anyOf: - type: string - type: 'null' position: anyOf: - type: integer - type: 'null' url: anyOf: - type: string - type: 'null' volume: anyOf: - type: integer - type: 'null' cpc_usd: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' traffic: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' required: - keyword - position - url - volume - cpc_usd - traffic additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: domain: anyOf: - type: string - type: 'null' common_keywords: anyOf: - type: integer - type: 'null' organic_keywords: anyOf: - type: integer - type: 'null' organic_traffic: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' required: - domain - common_keywords - organic_keywords - organic_traffic additionalProperties: false required: - items additionalProperties: false - type: object properties: backlinks: anyOf: - type: integer - type: 'null' referring_domains: anyOf: - type: integer - type: 'null' semrush_authority_score: anyOf: - type: integer - type: 'null' dataforseo_rank: anyOf: - type: integer - type: 'null' serpstat_domain_rank: anyOf: - type: integer - type: 'null' dofollow_backlinks: anyOf: - type: integer - type: 'null' nofollow_backlinks: anyOf: - type: integer - type: 'null' required: - backlinks - referring_domains - semrush_authority_score - dataforseo_rank - serpstat_domain_rank - dofollow_backlinks - nofollow_backlinks additionalProperties: false - type: object properties: items: type: array items: type: object properties: source_url: anyOf: - type: string - type: 'null' target_url: anyOf: - type: string - type: 'null' anchor: anyOf: - type: string - type: 'null' source_ahrefs_domain_rating: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' source_semrush_authority_score: anyOf: - type: integer - type: 'null' source_dataforseo_rank: anyOf: - type: integer - type: 'null' dofollow: anyOf: - type: boolean - type: 'null' first_seen_at: anyOf: - type: string - type: 'null' required: - source_url - target_url - anchor - source_ahrefs_domain_rating - source_semrush_authority_score - source_dataforseo_rank - dofollow - first_seen_at additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: domain: anyOf: - type: string - type: 'null' ahrefs_domain_rating: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' semrush_authority_score: anyOf: - type: integer - type: 'null' dataforseo_rank: anyOf: - type: integer - type: 'null' backlinks: anyOf: - type: integer - type: 'null' dofollow_backlinks: anyOf: - type: integer - type: 'null' first_seen_at: anyOf: - type: string - type: 'null' required: - domain - ahrefs_domain_rating - semrush_authority_score - dataforseo_rank - backlinks - dofollow_backlinks - first_seen_at additionalProperties: false required: - items additionalProperties: false - type: object properties: ahrefs_domain_rating: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' required: - ahrefs_domain_rating additionalProperties: false - type: object properties: dataforseo_task_id: anyOf: - type: string - type: 'null' crawl_progress: anyOf: - type: string - type: 'null' crawl_stop_reason: anyOf: - type: string - type: 'null' pages_crawled: anyOf: - type: integer - type: 'null' dataforseo_onpage_score: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' broken_links: anyOf: - type: integer - type: 'null' non_indexable: anyOf: - type: integer - type: 'null' duplicate_title: anyOf: - type: integer - type: 'null' duplicate_description: anyOf: - type: integer - type: 'null' duplicate_content: anyOf: - type: integer - type: 'null' required: - dataforseo_task_id - crawl_progress - crawl_stop_reason - pages_crawled - dataforseo_onpage_score - broken_links - non_indexable - duplicate_title - duplicate_description - duplicate_content additionalProperties: false - type: object properties: items: type: array items: type: object properties: keyword: anyOf: - type: string - type: 'null' volume: anyOf: - type: integer - type: 'null' cpc_usd: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' semrush_keyword_difficulty: anyOf: - type: integer - type: 'null' dataforseo_keyword_difficulty: anyOf: - type: integer - type: 'null' positions: type: object additionalProperties: anyOf: - type: integer - type: 'null' required: - keyword - volume - cpc_usd - semrush_keyword_difficulty - dataforseo_keyword_difficulty - positions additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: domain: anyOf: - type: string - type: 'null' dataforseo_rank: anyOf: - type: integer - type: 'null' backlinks_per_target: type: object additionalProperties: anyOf: - type: integer - type: 'null' required: - domain - dataforseo_rank - backlinks_per_target additionalProperties: false required: - items additionalProperties: false - type: object properties: url: anyOf: - type: string - type: 'null' status_code: anyOf: - type: integer - type: 'null' title: anyOf: - type: string - type: 'null' description: anyOf: - type: string - type: 'null' canonical: anyOf: - type: string - type: 'null' dataforseo_onpage_score: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' internal_links: anyOf: - type: integer - type: 'null' external_links: anyOf: - type: integer - type: 'null' required: - url - status_code - title - description - canonical - dataforseo_onpage_score - internal_links - external_links additionalProperties: false - type: object properties: items: type: array items: type: object properties: month: anyOf: - type: string - type: 'null' organic_keywords: anyOf: - type: integer - type: 'null' organic_traffic: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' organic_traffic_value_usd: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' paid_keywords: anyOf: - type: integer - type: 'null' paid_traffic: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' required: - month - organic_keywords - organic_traffic - organic_traffic_value_usd - paid_keywords - paid_traffic additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: url: anyOf: - type: string - type: 'null' platform: anyOf: - type: string - type: 'null' mentions: anyOf: - type: integer - type: 'null' ai_search_volume: anyOf: - type: integer - type: 'null' is_target_domain: anyOf: - type: boolean - type: 'null' required: - url - platform - mentions - ai_search_volume - is_target_domain additionalProperties: false required: - items additionalProperties: false - type: object properties: ahrefs_ai_citations: anyOf: - type: integer - type: 'null' ahrefs_ai_cited_pages: anyOf: - type: integer - type: 'null' ahrefs_ai_citations_by_platform: anyOf: - type: object additionalProperties: anyOf: - type: integer - type: 'null' - type: 'null' dataforseo_ai_mentions_by_platform: anyOf: - type: object additionalProperties: anyOf: - type: integer - type: 'null' - type: 'null' dataforseo_ai_search_volume_by_platform: anyOf: - type: object additionalProperties: anyOf: - type: integer - type: 'null' - type: 'null' required: - ahrefs_ai_citations - ahrefs_ai_cited_pages - ahrefs_ai_citations_by_platform - dataforseo_ai_mentions_by_platform - dataforseo_ai_search_volume_by_platform additionalProperties: false - type: 'null' description: >- 各操作的规范化字段。原生输出保留在 Run 中，可通过 GET /v1/runs/:id 读取。未报告的值为 null，金额为美元。权威度保留响应方口径和名称，不换算：ahrefs_domain_rating 为 0–100，semrush_authority_score 为 0–100，dataforseo_rank 为 0–1000，serpstat_domain_rank 为 0–100。关键词难度同样分为 semrush_keyword_difficulty、serpstat_keyword_difficulty、dataforseo_keyword_difficulty、ahrefs_keyword_difficulty，各自模型范围为 0–100。只填写实际响应方字段，其他家为 null。volume、traffic、cpc 为响应方估算，只宜在同一家内比较，见 runs[].provider。有效空结果的 result_status 为 no_result，保留操作结构，items 为 [] 或各字段为 null。 - keyword_overview: items[]: keyword, volume, cpc_usd, semrush_keyword_difficulty, serpstat_keyword_difficulty, dataforseo_keyword_difficulty, ahrefs_keyword_difficulty, intent - keyword_ideas: items[]: 与 keyword_overview 相同的行结构 - serp: items[]: position ，自然排名，1 为第一条自然结果，不计 SERP 特殊结果, url, domain, title, snippet ，仅自然结果 - domain_overview: organic_keywords, organic_traffic, organic_traffic_value_usd, paid_keywords, paid_traffic - ranked_keywords: items[]: keyword, position ，自然排名，1 为第一条自然结果，不计 SERP 特殊结果, url, volume, cpc_usd, traffic - organic_competitors: items[]: domain, common_keywords, organic_keywords ，竞争对手总数, organic_traffic ，排除目标域及其子域 - backlinks_overview: backlinks, referring_domains, semrush_authority_score, dataforseo_rank, serpstat_domain_rank, dofollow_backlinks, nofollow_backlinks - backlinks: items[]: source_url, target_url, anchor, source_ahrefs_domain_rating, source_semrush_authority_score, source_dataforseo_rank, dofollow, first_seen_at ，ISO 8601 UTC；Semrush 未注明时区，不加 Z 后缀。各家均每个链接一行 - referring_domains: items[]: domain, ahrefs_domain_rating, semrush_authority_score, dataforseo_rank, backlinks, dofollow_backlinks, first_seen_at ，ISO 8601 UTC；Semrush 未注明时区，不加 Z 后缀 - domain_rating: ahrefs_domain_rating - site_audit: dataforseo_task_id ，用于 DataForSEO OnPage 报告接口的输入, crawl_progress, crawl_stop_reason ，DataForSEO 词汇, pages_crawled, dataforseo_onpage_score, broken_links, non_indexable, duplicate_title, duplicate_description, duplicate_content - keyword_gap: items[]: keyword, volume, cpc_usd, semrush_keyword_difficulty, dataforseo_keyword_difficulty, positions {domain: 自然排名；null 表示不在前 100 名}，键为传入域名。Semrush 返回任一域名有排名的关键词并集；DataForSEO 返回竞争对手有排名而你没有的关键词 - backlink_gap: items[]: domain, dataforseo_rank, backlinks_per_target {竞争域名: 数量} - page_audit: url, status_code, title, description, canonical, dataforseo_onpage_score, internal_links, external_links - visibility_history: items[]: month, organic_keywords, organic_traffic, organic_traffic_value_usd, paid_keywords, paid_traffic - ai_citations: items[]: url, platform, mentions, ai_search_volume, is_target_domain ，提及该域名的 AI 回答中被引用最多的页面，可来自任意网站 - ai_visibility: ahrefs_ai_citations, ahrefs_ai_cited_pages, ahrefs_ai_citations_by_platform {platform: 引用次数}, dataforseo_ai_mentions_by_platform {platform: 提及次数}, dataforseo_ai_search_volume_by_platform {platform: AI 搜索量}。各家仅填自己的字段，不跨家汇总 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: - keyword_overview - keyword_ideas - serp - domain_overview - ranked_keywords - organic_competitors - backlinks_overview - backlinks - referring_domains - domain_rating - site_audit - ai_visibility - keyword_gap - backlink_gap - page_audit - visibility_history - ai_citations result_status: type: string enum: - success - no_result - error - pending description: >- 业务交付状态，与 status 中的最终 Run 生命周期独立。no_result 为有效空结果；error 表示数据提供商输出无法交付。 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 - 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.