跳转到主要内容
POST
SEO 研究
研究关键词搜索量和难度、搜索排名、外链、与竞争对手的关键词和外链差距、排名历史、网站抓取、单页检查及 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 搜索量}。各家仅填自己的字段，不跨家汇总

请求头

​
idempotency-key
string
必填

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

Minimum string length: 1

请求体

application/json
​
use_case
string | null

简述当前 SEO 任务，并包含研究对象。配合 task_id 使用时，会保存为 Task 描述，供结果复核和任务完成度评估。仅包含与任务相关的信息，不包含对话历史或无关个人信息。后续调用省略则保留原描述。

​
action
enum<string> | null

默认为 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 返回竞争对手有排名而你没有的关键词。
可用选项:
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
​
provider
enum<string> | null

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

可用选项:
auto,
semrush,
serpstat,
dataforseo,
ahrefs,
serper
​
keywords
string[] | null
Required array length: 1 - 20 elements
Required string length: 1 - 200
​
domain
string | null

网站域名，例如 stripe.com。也接受完整 URL，并提取主机名。

Required string length: 3 - 253
​
competitors
string[] | null

keyword_gap 和 backlink_gap 的竞争域名，一至四个。完整 URL 会提取为主机名。

Required array length: 1 - 4 elements

网站域名，例如 stripe.com。也接受完整 URL，并提取主机名。

Required string length: 3 - 253
​
url
string | null

page_audit 的单页 URL，例如 https://stripe.com/pricing。

Required string length: 1 - 2048
​
country
string | null

国家，使用两位 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 前被拒绝。不要为了绕过错误而更换国家，这会改变请求的数据。

Required string length: 2 - 60
​
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，金额为美元。权威度保留响应方口径和名称，不换算：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
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>
必填
可用选项:
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
enum<string>
必填

业务交付状态，与 status 中的最终 Run 生命周期独立。no_result 为有效空结果；error 表示数据提供商输出无法交付。

可用选项:
success,
no_result,
error,
pending
​
error
object | null
必填
​
runs
object[]
必填
​
result_url
string
必填

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