跳转到主要内容
POST
运行接口
  • 200: Run 已结束,请检查状态、数据提供商响应和费用。
  • 202: 异步 Run 仍在执行,通过获取 Run检查结果。
已结束的 Run 仍可能包含数据提供商错误。重试时复用相同 Idempotency-Key 和执行参数。

请求头

idempotency-key
string
必填

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

Minimum string length: 1

请求体

application/json
provider
string
必填
Pattern: ^[a-z0-9][a-z0-9-]*$
endpoint
string
必填
Pattern: ^\/.+$
input
object

数据提供商原生输入,按检查结果中的 input_schema 构造。

endpoint_version
integer | null

选择受支持版本,省略则使用默认版本。兼容更新保持版本号;版本不可用或已停用时返回 409。版本不锁定价格:新 Run 使用受理时价格,已受理 Run 保留至结算。

必填范围: x > 0
task_id
string | null

本次 Run 所属 Task,来自数据源搜索响应。仅用于分组,不影响路由、价格或幂等。

metadata

可选追踪字段,随 Run 返回,也可用于筛选。不会发送给数据提供商,也不影响路由、价格或幂等。

  • 最多 20 个键:小写字母、数字和下划线,以字母开头,最长 40 个字符。
  • 值:长度为 1–500 的字符串。
  • user_id:终端用户的不透明 ID,不得使用邮箱或姓名。

无效条目整体丢弃,不截断。请求继续执行,Run 返回实际保存的字段。

响应

终态 Run:COMPLETED、FAILED 或 STOPPED。

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
any
必填
provider_response
object | null
必填

仅在 status 为 COMPLETED 时非 null。

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

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

charge_usd
string | null
必填

最终费用,精确的美元十进制字符串。QUEUED 或 RUNNING 时为 null。FAILED 状态的 Run 仍可能按接口定价产生非零费用。

Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
charge_basis
object | null
必填

计算费用所用的价格条款。结算前或未尝试调用数据提供商时为 null。

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,不得使用邮箱或姓名。