发起运行
curl --request POST \
--url https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runsimport requests
url = "https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runs"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const options = {method: 'POST'};
fetch('https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runs"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runs")
.asString();<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}require 'uri'
require 'net/http'
url = URI("https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodyusing RestSharp;
var options = new RestClientOptions("https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runs");
var client = new RestClient(options);
var request = new RestRequest("");
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
val client = OkHttpClient()
val request = Request.Builder()
.url("https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runs")
.post(null)
.build()
val response = client.newCall(request).execute()false{
"run_id": "<string>",
"namespace": "<string>",
"app_name": "<string>",
"app_version": "<string>",
"build_id": "<string>",
"run_kind": "<string>",
"state": {},
"input": {},
"progress": {
"done": 123,
"total": 123,
"status_text": "<string>"
},
"dataset_id": "<string>",
"partial": true,
"cancel_requested": true,
"triggered_by": "<string>",
"upstream_ref": "<string>",
"created_at": "<string>",
"started_at": "<string>",
"first_started_at": "<string>",
"finished_at": "<string>",
"usage": {
"metrics": {},
"duration_ms": 123
},
"billing": {
"events": [
{
"event": "<string>",
"label": "<string>",
"qty": 123,
"unit_price": 123,
"amount": 123,
"unit_size": 123,
"raw_qty": 123
}
],
"total": 123,
"currency": "<string>",
"charged": true
},
"error": {
"code": "<string>",
"category": "<string>",
"message": "<string>",
"retryable": true,
"retry_after": 123,
"item_index": 123,
"details": [
{}
]
},
"sample_records": [
{}
],
"warnings": [
{
"code": "<string>",
"event": "<string>",
"detail": {},
"count": 123,
"updated_at": "<string>"
}
]
}运行与结果
发起运行
用满足输入契约的参数发起一次 Data App 运行,可选择等待结果。
POST
/
v1
/
data-apps
/
{app_id}
/
runs
发起运行
curl --request POST \
--url https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runsimport requests
url = "https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runs"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const options = {method: 'POST'};
fetch('https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runs"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runs")
.asString();<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}require 'uri'
require 'net/http'
url = URI("https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodyusing RestSharp;
var options = new RestClientOptions("https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runs");
var client = new RestClient(options);
var request = new RestRequest("");
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
val client = OkHttpClient()
val request = Request.Builder()
.url("https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runs")
.post(null)
.build()
val response = client.newCall(request).execute()false{
"run_id": "<string>",
"namespace": "<string>",
"app_name": "<string>",
"app_version": "<string>",
"build_id": "<string>",
"run_kind": "<string>",
"state": {},
"input": {},
"progress": {
"done": 123,
"total": 123,
"status_text": "<string>"
},
"dataset_id": "<string>",
"partial": true,
"cancel_requested": true,
"triggered_by": "<string>",
"upstream_ref": "<string>",
"created_at": "<string>",
"started_at": "<string>",
"first_started_at": "<string>",
"finished_at": "<string>",
"usage": {
"metrics": {},
"duration_ms": 123
},
"billing": {
"events": [
{
"event": "<string>",
"label": "<string>",
"qty": 123,
"unit_price": 123,
"amount": 123,
"unit_size": 123,
"raw_qty": 123
}
],
"total": 123,
"currency": "<string>",
"charged": true
},
"error": {
"code": "<string>",
"category": "<string>",
"message": "<string>",
"retryable": true,
"retry_after": 123,
"item_index": 123,
"details": [
{}
]
},
"sample_records": [
{}
],
"warnings": [
{
"code": "<string>",
"event": "<string>",
"detail": {},
"count": 123,
"updated_at": "<string>"
}
]
}端点
POST https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runs
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 复制一份再修改最稳妥。
示例请求
curl -X POST \
-H "Authorization: Bearer $BAZHUAYU_API_KEY" \
-H "Content-Type: application/json" \
-d '{"product": "p-9001"}' \
"https://api-datahub.bazhuayu.com/v1/data-apps/carol/probe-b/runs?wait=60"
响应
200 成功
{
"data": {
"run_id": "run_c62bc0fb8df2",
"namespace": "carol",
"app_name": "probe-b",
"app_version": "0.1.0",
"build_id": null,
"run_kind": "production",
"state": "SUCCEEDED",
"input": {
"product": "p-now"
},
"progress": {
"done": 20,
"total": null,
"status_text": null
},
"dataset_id": "ds_0bd5345d13d0",
"partial": false,
"cancel_requested": false,
"triggered_by": "api",
"upstream_ref": null,
"created_at": "2026-09-15T07:45:40.411993+00:00",
"started_at": "2026-09-15T07:45:40.419610+00:00",
"first_started_at": "2026-09-15T07:45:40.419610+00:00",
"finished_at": "2026-09-15T07:45:40.822250+00:00",
"usage": {
"metrics": {
"records_collected": 20
},
"duration_ms": 402
},
"billing": {
"events": [
{
"event": "record",
"label": "获取一条",
"qty": 20.0,
"unit_price": 0.001,
"amount": 0.02,
"unit_size": null,
"raw_qty": null
}
],
"total": 0.02,
"currency": "CNY",
"charged": true
},
"error": null,
"sample_records": null,
"warnings": []
}
}
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 的字段会被打码。string
结果数据集标识。
boolean
true 表示部分成功或被取消,已产出的记录可用。boolean
是否已收到取消请求。
string
发起渠道。
string
上游原始任务号(如有)。
string
发起时间,也是时间范围筛选与账单归属的依据。
string
最近一次开始执行的时间。
string
首次开始执行的时间,重试不会改写。
string
结束时间。
object
object
object[]
返回时已到终态则带首批记录,否则为
null。错误
| HTTP | code | category | 说明 |
|---|---|---|---|
| 401 | unauthorized | forbidden | 缺少或无效的 API Key。 |
| 400 | invalid-input | invalid_input | 请求体不满足 App 的输入契约,details[] 逐项指出字段路径与原因。 |
| 404 | app-not-found | not_found | App 不存在、已改名,或对当前凭证不可见(私有 / 分享范围之外)。 |
| 403 | app-not-accepting-runs | forbidden | App 处于维护中,作者暂停接收新运行;message 带作者留言。 |
| 402 | balance-negative | forbidden | 钱包余额为负,暂停发起新运行;充值后原样重试。 |
| 503 | billing-unavailable | temporary | 账号有欠费记录且计费服务暂时无法核验余额;retryable 为 true,稍后重试。 |
| 422 | version-yanked | invalid_input | 指定的版本已被作者撤回,不再接受新运行。 |
{"error": {code, category, message, retryable}},见错误。
客户端库
# 发起并等待终态(SDK 内部轮询)
run = client.call("carol/probe-b", {"product": "p-9001"}, max_records=100)
print(run["state"], run["billing"]["total"])
# 只发起,不等待
run = client.run("carol/probe-b", {"product": "p-9001"}, wait=0)
run_id = run["run_id"]
// 发起并等待终态(SDK 内部轮询,超时参数单位毫秒)
const run = await client.call("carol/probe-b", { product: "p-9001" }, { maxRecords: 100, timeout: 120_000 });
console.log(run.state, run.billing.total);
// 只发起,不等待
const started = await client.run("carol/probe-b", { product: "p-9001" }, { wait: 0 });
const runId = started.run_id;
注意事项
- 状态词汇:
PENDING、QUEUED、RUNNING、SUCCEEDED、PARTIALLY_SUCCEEDED、FAILED、CANCELLED、EXPIRED。后五个是终态。 - 同一目标不要因为等待超时而重复发起;先用
run_id查询状态。 - 失败不计费;部分成功与取消只按已产出记录计费。
