跳转到主要内容
GET
读取 SEO 研究结果
通过 SEO 研究返回的 result_url,读取相同 Run 的规范化输出、业务 result_status 和总费用。HTTP 200 仍可能包含 result_status=pending。此认证读取不创建 Run、不调用数据提供商,也不恢复切换。GET /v1/runs/:id 仍返回单个 Run 的原生输出。结果上下文带签名,绑定工作空间,并对每个 Run 按当前 API Key Policy 检查权限。

查询参数

token
string
必填

result_url 中返回的不透明结果上下文。保持原样,并使用有权读取所列全部 Run 的 API Key 认证。

Required string length: 1 - 16384

响应

SeoResearchResult

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。