查询运行队列项

方法: GET

端点: /api/v2/run-queue/items

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

在线试用

GET/api/v2/run-queue/itemsList run queue items

AuthenticationRequired

Auth mode

API token

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

Parameters

offsetquery · integer · default `1`; minimum 0Optional

Page number, 1-based. `offset=1` is page 1, `offset=2` is page 2; `offset=0` is accepted as page 1. Out-of-range pages return an empty list. Constraints: default `1`; minimum 0.

limitquery · integer · default `20`; range 1-100Optional

Page size. Constraints: default `20`; range 1-100.

statusquery · stringOptional

Run status filter.

Request BodyNot applicable

No JSON request body. Fill the path or query parameters above.

什么时候使用这个接口

用于查看运行队列里目前有哪些项。每一项都是你通过排队运行 Worker 提交、但尚未开始执行的运行——比如提交时账户余额不足，运行就会停在队列里等待。

常见用途：

决定下一步之前，先看看队列里积压了多少运行。
找到要激活（开始执行）或释放（放弃并移除）的项的 queue_ref。

查询参数

参数	必填	类型	说明
`offset`	否	`integer`	页码，从 1 开始。`offset=1` 为第 1 页，`offset=2` 为第 2 页；`offset=0` 兼容作为第 1 页。超出总页数时返回空列表。约束：默认 `1`；最小 0。
`limit`	否	`integer`	每页数量，列表接口上限 `100`。约束：默认 `20`；范围 1-100。
`status`	否	`string`	按队列状态过滤。允许值：`waiting`（运行暂存在队列、尚未开始执行）和 `inactive`。

请求示例

curl -X GET "https://openapi.coreclaw.com/api/v2/run-queue/items?offset=1&limit=20&status=waiting" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例

{
  "code": 0,
  "data": {
    "count": 1,
    "list": [
      {
        "queue_ref": "123456",
        "queue_status": "waiting"
      }
    ]
  },
  "message": "success",
  "request_id": "req-123"
}

data.list[] 内的具体字段以平台实际返回的队列项结构为准。最常用的是 queue_ref——把它复制出来用于后续激活或释放。

说明

API v2 支持 Bearer token、旧版 api-key 请求头和 query token。新集成推荐使用 Bearer token。
queue_ref 是传给激活运行队列项、释放运行队列项、释放单个运行队列项的标识符。
运行状态的背景可参考运行生命周期与状态。

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