排队运行 Worker

方法: POST

端点: /api/v2/workers/{workerId}/queued-runs

认证: 支持 Authorization: Bearer <YOUR_API_KEY>、api-key: <YOUR_API_KEY> 和 ?token=<YOUR_API_KEY>。推荐优先使用 Bearer token。

在线试用

POST/api/v2/workers/{workerId}/queued-runsQueue worker run

AuthenticationRequired

Auth mode

API token

Stored only in this browser tab. Sent only to https://openapi.coreclaw.com.

Parameters

workerIdpath · stringRequired

Worker slug or path. You may paste `owner/name`; the playground sends it as `owner~name` for path values. The playground prefills an official Worker (`coreclaw/google-maps-scraper`); replace it with your own.

Request BodyRequiredapplication/json

FieldTypeRequiredDescription

callback_urlstringOptionalCallback URL. When provided, CoreClaw sends a POST request after the run status changes or finishes.

inputanyOptionalWorker input payload. Put Worker form fields under `input.parameters.custom`. If left empty in the playground, it will try to load schema defaults before sending.

is_asyncbooleanOptional`true` submits asynchronously and does not wait for execution results; `false` waits for the run to finish. Defaults to `true`.

limitintegerOptionalResult limit for synchronous run. Constraints: default `20`; range 1-100.

offsetintegerOptionalResult offset for synchronous run. Constraints: default `0`; minimum 0.

versionstringOptionalOptional Worker version. Omit it unless you have confirmed a concrete available version for this Worker; not every Worker accepts `latest`.

Request body (JSON)

什么时候使用这个接口

用于把一次 Worker 运行提交到运行队列。和运行 Worker（POST /api/v2/workers/{workerId}/runs，立即开始执行）不同，排队版本会把运行放进队列并返回一个 queue_ref，由你决定这次运行何时（以及是否）真正开始。

常见的结果是运行进入 waiting 状态后并不会自动开始——比如提交时账户余额不足，运行会被挂起而不是被拒绝。你解决条件后（例如充值补足余额），再用激活运行队列项手动启动这次运行。如果决定不跑了，用释放运行队列项把它移除。

标识符说明

workerId / worker_id 支持 Worker slug，也支持把路径 owner/name 写成 owner~name。

路径参数

参数	必填	类型	说明
`workerId`	是	`string`	Worker slug 或 path；如果使用 `owner/name` 路径，请写成 `owner~name`。

请求体

使用 Content-Type: application/json 发送请求体。表格中的必填/选填描述字段本身是否必须提供；整个请求体是否必填以在线试用区的 Request Body 标记为准。

字段	必填	类型	说明
`callback_url`	否	`string`	回调地址。传入后，CoreClaw 会在运行状态变化或结束时向该地址发送 `POST` 请求。
`input`	否	`any`	Worker 输入参数。Worker 表单字段通常放在 `input.parameters.custom` 下；应先读取该 Worker 的 input schema，再按 schema 构造。
`is_async`	否	`boolean`	出于 API 一致性而接受，但对排队运行无效：排队运行始终进入队列，响应返回 `queue_ref`，不会返回同步运行结果。如需同步运行，请改用运行 Worker。
`limit`	否	`integer`	出于 API 一致性而接受，但对排队运行响应无效——响应返回 `queue_ref` 而非结果窗口。约束：默认 `20`；范围 1-100。
`offset`	否	`integer`	出于 API 一致性而接受，但对排队运行响应无效。约束：默认 `1`；最小 0。
`version`	否	`string`	可选 Worker 版本。除非已经确认该 Worker 存在某个具体可用版本，否则建议省略；并非所有 Worker 都接受 `latest` 作为显式版本值。

JSON 示例

{
  "callback_url": "https://client.example.com/openapi/callback",
  "input": {
    "parameters": {
      "custom": {
        "keywords": [
          "coffee"
        ],
        "base_location": "New York,USA",
        "max_results": 1
      }
    }
  },
  "version": "latest"
}

请求示例

curl -X POST "https://openapi.coreclaw.com/api/v2/workers/YOUR_WORKER_ID/queued-runs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"callback_url":"https://client.example.com/openapi/callback","input":{"parameters":{"custom":{"keywords":["coffee"],"base_location":"New York,USA","max_results":1}}},"version":"latest"}'

响应示例

{
  "code": 0,
  "data": {
    "queue_ref": "123456",
    "queue_status": "waiting",
    "queued": true
  },
  "message": "success",
  "request_id": "req-123"
}

响应字段

字段	类型	说明
`queue_ref`	`string`	队列项 ID。之后可用它来激活或释放这次运行。
`queue_status`	`string`	该项在队列中的状态，例如 `waiting`。处于 `waiting` 的项暂存在队列里，在你激活之前不会开始执行。
`queued`	`boolean`	该运行是否已成功进入队列。

说明

API v2 支持 Bearer token、旧版 api-key 请求头和 query token。新集成推荐使用 Bearer token。
构造 input 前应先读取该 Worker 的 input schema；不同 Worker 字段不同。
version 为可选项。除非已确认存在具体可用版本，否则建议省略；并非所有 Worker 都接受 latest 作为显式版本值。
如果运行进入 waiting（例如余额不足），它不会自动开始——解决条件后请调用激活运行队列项。
状态处理、轮询、失败诊断与取消行为可参考运行生命周期与状态。
传入 callback_url 后，CoreClaw 会在状态变化或完成时发送回调通知，详见回调通知。

HTTP 响应

HTTP 状态码	应用码	含义
`200`	`0`	OK
`400`	`11000`	Bad Request
`401`	`12001`	Unauthorized
`404`	`11004`	Not Found
`422`	`11000`	Unprocessable Entity
`429`	`13000`	Too Many Requests
`500`	`10000`	Internal Server Error