Skip to main content
POST
发起运行

端点

认证:需要 API Key(Authorization: Bearer <API Key>)。 请求体是 App 输入契约(详情里的 input_schema)的一个实例,严格校验。 wait 决定这次调用是否等待结果:
  • 省略:按 App 的 execution.mode 默认行为。sync 型一直等到终态(上限为 App 的 execution.timeout_seconds);async 型立即返回 run_id。
  • 显式给出 0-60:两种模式行为一致,最多等 wait 秒;wait=0 入队即返回,sync 型也可以先拿到 run_id 再用 查询运行 的 wait 长轮询。
返回时运行已到终态的话,sample_records 带首批记录。完整结果通过读取运行结果分页取。 version 把运行钉到历史版本(契约与价格都随该版本);build 是作者调试用,钉住一个不可变的 Build 快照(run_kind=test,不进公开统计,但照常计费),与 version 互斥。 运行门与详情门一致:不可见即 404;可见但作者暂停接收运行为 403(作者自测不受限);钉到已撤回版本的新运行被拒(422)。

请求

路径参数

string
必填
App 引用,app_<hex> 或 <namespace>/<app_name>。

查询参数

number
最多等待多少秒到终态。省略按 App 模式默认;0 发起即返回。范围 0 到 60。
integer
最多产出多少条记录,达到后运行正常结束。用于控制费用与耗时。范围 ≥ 1。
string
默认值:"api"
发起渠道标记,默认 api;SDK 与 MCP 会自动填自己的值。可作为运行列表与账单的筛选维度。
string
钉到指定版本运行,默认最新版本。
string
作者调试用,钉到某个 Build 快照;与 version 互斥。

请求体

JSON 对象,结构由 App 的 input_schema 决定,从详情里的 examples 复制一份再修改最稳妥。

示例请求

响应

200 成功

响应包在 data 字段中,其内容如下。
string
必填
运行标识,后续查询、读取、取消都用它。
string
App 发布者用户名。
string
应用名。
string
钉住的版本号;调试运行为 null。
string
调试运行钉住的 Build 快照;生产运行为 null。
string
production 生产运行,test 作者调试运行。
enum
必填
运行状态。 取值:PENDING / QUEUED / RUNNING / SUCCEEDED / PARTIALLY_SUCCEEDED / FAILED / CANCELLED / EXPIRED。
object
输入回显;输入契约中标记 sensitive 的字段会被打码。
object
进度。done / total 由 App 上报,status_text 是 App 写的人读状态。
string
结果数据集标识。
boolean
true 表示部分成功或被取消,已产出的记录可用。
boolean
是否已收到取消请求。
string
发起渠道。
string
上游原始任务号(如有)。
string
发起时间,也是时间范围筛选与账单归属的依据。
string
最近一次开始执行的时间。
string
首次开始执行的时间,重试不会改写。
string
结束时间。
object
客观用量:metrics 记录数等计数,duration_ms 执行耗时。
object
费用明细:events[] 逐个计费事件的数量、单价与金额,total 合计,charged 是否实际收费。终态后才完整。
object
失败时的错误对象(code / category / message / retryable)。
object[]
返回时已到终态则带首批记录,否则为 null。
object[]
结构化告警,例如 billing-qty-missing。

错误

错误响应统一为 {"error": {code, category, message, retryable}},见错误。

客户端库

注意事项

  • 状态词汇:PENDING、QUEUED、RUNNING、SUCCEEDED、PARTIALLY_SUCCEEDED、FAILED、CANCELLED、EXPIRED。后五个是终态。
  • 同一目标不要因为等待超时而重复发起;先用 run_id 查询状态。
  • 失败不计费;部分成功与取消只按已产出记录计费。