跳转到主要内容
POST
亚马逊研究
必须指定市场。action 为 search、product、keywords、keyword_volume、reviews、price_history、offers、merchant_search、merchant_page。先报价;超过 max_charge_usd 的请求在创建 Run 前拒绝。未知为 null。明确实际评论页及筛选条件,不能声称总体占比。保留价格序列、币种和观察时间;缓存报价不是核验后的结账价格。pending 使用原 result_url 免费重读,原始证据保留在 Run。

请求头

idempotency-key
string
必填

每次独立查询都生成新的唯一值(建议使用随机 UUID),即使参数相同且发生在同一天。仅在恢复同一次预期执行时沿用原键与参数,取回原 Run,不再次扣费。同键更改执行参数返回 409;更换 task_id 或 metadata 不会创建新 Run。旧的不透明键仍可用于恢复。

Minimum string length: 1

请求体

application/json

merchant_search:query、可选 language;merchant_page:公开 url。search:query、可选 page;product/reviews/offers:精确 asin。reviews 支持 review_pages、review_rating、review_sort、verified_only、review_keyword。keywords:query 与可选 language/limit/offset,仅 us/en。keyword_volume:keywords 与 language。max_charge_usd 在 Run 前限制最高费用。price_history:asin 与可选 days,默认 180。不支持的字段在收费前拒绝。不修改商品、不估算费用、不创建自动监控。

action
enum<string>
必填
可用选项:
search,
product,
keywords,
keyword_volume,
reviews,
price_history,
offers,
merchant_search,
merchant_page
country
string
必填

必须明确亚马逊市场。常规取数支持 us、gb、de、fr、it、es、ca、jp、in、au;相关词只支持 us/en,精确词量另有已开放的地区/语言配对。

Minimum string length: 1
provider
enum<string> | null

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

可用选项:
auto,
serpapi,
dataforseo,
apify,
keepa,
serper
max_charge_usd
string | null

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

Maximum string length: 20
Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
review_pages
integer | null
必填范围: 1 <= x <= 10
review_rating
integer | null
必填范围: 1 <= x <= 5
review_sort
enum<string> | null
可用选项:
recent,
helpful
verified_only
boolean | null
review_keyword
string | null
Required string length: 1 - 200
url
string | null
Required string length: 1 - 2048
Pattern: ^https?:\/\/
query
string | null
Required string length: 1 - 200
keywords
string[] | null
Required array length: 1 - 1000 elements
Minimum string length: 1
asin
string | null
Pattern: ^[A-Z0-9]{10}$
page
integer | null
必填范围: 1 <= x <= 20
limit
integer | null
必填范围: 1 <= x <= 100
offset
integer | null
必填范围: 0 <= x <= 10000
language
string | null
Minimum string length: 1
days
integer | null
必填范围: x >= 1
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
必填
provider_response
object | null
必填

仅在 status 为 COMPLETED 时非 null。

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

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

charge_usd
string | null
必填

所列 Run 的历史费用总和,包括重放或读取的 Run。所有 Run 结算前为 null。这不是当前请求的新增支出;request_charge 单独报告新增费用。失败也可能收费。

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,
product,
keywords,
keyword_volume,
reviews,
price_history,
offers,
merchant_search,
merchant_page
result_status
enum<string>
必填
可用选项:
success,
no_result,
error,
pending
error
object | null
必填
runs
object[]
必填
result_url
string
必填

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

response_file
object

以 JSON 文件完整交付较大的 Provider 正文。Glasser 对接收的正文和序列化文件应用 32 MiB 的运行时资源保护。body_field 指明被替代的字段;output 为 null,或省略 provider_response.error。下载链接最多一小时后过期。在文件的 7 天可用期内,通过已认证的 Get Run 刷新链接。读取和下载不会再次执行 Run 或重复收费。state 为 link_pending 时,读取同一 Run 即可准备链接,不会再次执行或重复收费。链接授予临时读取权限,请仅与预期接收者分享。

review_invitation
object

每个 Run 至多出现一次,只在部分已完成 Run 的首次交付中出现。用完本次结果后,按 instruction 提交评价,然后继续任务。可选;不影响 Run 及其费用。

request_charge
object

当前请求的受理与费用证据。在同一件用户工作中保存 created_run_ids,每个已结算 Run 只计一次费用。更换 task_id 不会把幂等重放变成新 Run。读取结果的费用为零,受理列表为空。