查询 Worker 运行记录

方法: GET

端点: /api/v2/worker-runs

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

在线试用

GET/api/v2/worker-runsList worker runs

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.

worker_idquery · stringOptional

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

statusquery · enum: ready, running, succeeded, failed, aborting · allowed values: `ready`, `running`, `succeeded`, `failed`, `aborting`Optional

Run status filter. Constraints: allowed values: `ready`, `running`, `succeeded`, `failed`, `aborting`.

start_timequery · integerOptional

Run created_at start time, Unix seconds.

end_timequery · integerOptional

Run created_at end date, Unix seconds at 00:00:00. The server includes the whole end date by adding 86400 seconds before querying.

Request BodyNot applicable

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

什么时候使用这个接口

用于按账户范围查询运行历史，可按 Worker 和状态筛选；它不返回 Worker 清单。

标识符说明

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

查询参数

参数	必填	类型	说明
`offset`	否	`integer`	页码，从 1 开始。`offset=1` 为第 1 页，`offset=2` 为第 2 页；`offset=0` 兼容作为第 1 页。超出总页数时返回空列表。约束：默认 `1`；最小 0。
`limit`	否	`integer`	每页返回数量；列表和结果接口的 `limit` 上限为 `100`。约束：默认 `20`；范围 1-100。
`worker_id`	否	`string`	Worker slug 或 path；如果使用 `owner/name` 路径，请写成 `owner~name`。
`status`	否	`enum: ready, running, succeeded, failed, aborting`	运行状态筛选。约束：可选值：`ready`、`running`、`succeeded`、`failed`、`aborting`。
`start_time`	否	`integer`	按 `created_at` 起始时间筛选，Unix 秒。传入时必须同时传 `end_time`，且两者必须落在同一个自然月内。
`end_time`	否	`integer`	按 `created_at` 结束日期筛选，Unix 秒。传该日 `00:00:00`；服务端会 +86400 秒以包含整个结束日。必须与 `start_time` 在同一个自然月内。

请求示例

curl -X GET "https://openapi.coreclaw.com/api/v2/worker-runs?offset=1&limit=20&worker_id=YOUR_WORKER_ID&status=running" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例

{
  "code": 0,
  "data": {
    "count": 1,
    "list": [
      {
        "duration": 10,
        "err_msg": "",
        "finished_at": 1782091210,
        "origin": "openapi",
        "results": 1,
        "scraper_slug": "demo-worker",
        "scraper_title": "Demo Worker",
        "slug": "01KKDXV2G26BT7NH4ZQR2R4NPZ",
        "started_at": 1782091200,
        "status": "running",
        "traffic": 0,
        "usage": "1.00",
        "version": "latest"
      }
    ]
  },
  "message": "success",
  "request_id": "req-123"
}

响应字段

data.list[] 中的每一条运行记录都包含以下字段（data.count 为总记录数）：

字段	类型	说明
`slug`	`string`	运行标识；作为后续详情、日志、结果和导出接口的 `runId`。
`scraper_slug`	`string`	实际运行的 Worker 标识。
`scraper_title`	`string`	Worker 展示名称。
`version`	`string`	实际运行的 Worker 版本，例如 `v1.2.8`。
`status`	`string`	运行状态，唯一的主要结果判断字段。取值见运行生命周期与状态。
`results`	`integer`	当前或最终结果行数。`0` 不代表失败。
`usage`	`string`	平台记录的资源用量（字符串数值），用于观测与计费诊断。
`traffic`	`integer`	平台记录的流量诊断值。
`origin`	`string`	运行来源，例如 `api_v2`。
`started_at`	`integer`	执行开始时间，Unix 秒。
`finished_at`	`integer`	执行结束时间，Unix 秒。
`duration`	`integer`	执行耗时，秒。
`err_msg`	`string`	可选诊断信息。可能缺失（例如成功运行时通常不返回该字段）；仅作辅助排障，不要单独用它判断成败。

时间戳为 Unix 秒（UTC）。取消、排队或状态同步时，时间字段可能出现不完整或不直观的组合；请始终以 status 为准。

注意事项

API v2 同时支持 Bearer token、旧版 api-key 请求头和 query token；新集成建议优先使用 Bearer token。
不传 start_time/end_time 时，本接口只返回当月运行记录。同时传入 start_time 和 end_time（Unix 秒，同一自然月）可查询历史归档记录；跨月范围会返回 code:11000 "run list time range cannot cross months"。
end_time 按某日 00:00:00 解释：服务端查询前会 +86400 秒以包含该日全天。当结束日为某月最后一天时，请传该日 00:00:00 整（北京时间 UTC+8）——该日任意更晚时刻都会使 +86400 后的上界跨入下月，导致请求被拒绝。
运行状态、轮询、失败诊断和取消处理请参阅运行生命周期与状态。

HTTP 响应

HTTP 状态	应用代码	含义
`200`	`0`	请求成功。
`400`	`11000`	请求参数不合法。
`401`	`12001`	认证缺失或无效。
`404`	`11004`	目标资源不存在。
`422`	`11000`	请求语义或字段校验未通过。
`429`	`13000`	请求过于频繁。
`500`	`10000`	服务端内部错误。