List Worker Runs

Method: GET

Endpoint: /api/v2/worker-runs

Authentication: Supports Authorization: Bearer <YOUR_API_KEY>, api-key: <YOUR_API_KEY>, and ?token=<YOUR_API_KEY>. Prefer Bearer token.

Try it

GET/api/v2/worker-runsList worker runs

AuthenticationRequired

Auth mode

Authorization: Bearerapi-key headerQuery token

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.

Send Request Clear all

When to use this endpoint

Use this endpoint to list run history in the account scope, optionally filtered by Worker and status; it does not list Workers.

Identifier Notes

• workerId / worker_id accepts a Worker slug or a path encoded as owner~name from owner/name.

Query Parameters

Parameter	Required	Type	Description
offset	No	integer	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.
limit	No	integer	Page size. limit is capped at 100 on list and result endpoints. Constraints: default 20; range 1-100.
worker_id	No	string	Worker slug or path. You may paste owner/name; the playground sends it as owner~name for query values.
status	No	enum: ready, running, succeeded, failed, aborting	Run status filter. Constraints: allowed values: ready, running, succeeded, failed, aborting.
start_time	No	integer	Filter runs by created_at start time, Unix seconds. When provided, end_time is also required, and both must fall in the same calendar month.
end_time	No	integer	Filter runs by created_at end date, Unix seconds. Pass the day at 00:00:00; the server adds 86400 seconds to include the whole day. Must be in the same calendar month as start_time.

Request Example

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"

Response Example

{
  "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"
}

Response Fields

Each run record in data.list[] contains these fields (data.count is the total record count):

Field	Type	Description
slug	string	Run identifier; pass it as runId to detail, log, result, and export endpoints.
scraper_slug	string	Identifier of the Worker that ran.
scraper_title	string	Worker display name.
version	string	Worker version that actually ran, for example v1.2.8.
status	string	Run status and the primary outcome field. See Run Lifecycle & Status for values.
results	integer	Current or final number of result rows. 0 does not mean failure.
usage	string	Platform-recorded resource usage (numeric string) for observability and billing diagnostics.
traffic	integer	Platform-recorded traffic diagnostic value.
origin	string	Run origin, for example api_v2.
started_at	integer	Execution start time, Unix seconds.
finished_at	integer	Execution end time, Unix seconds.
duration	integer	Execution duration in seconds.
err_msg	string	Optional diagnostic text. It may be absent (successful runs usually omit it); use it only as supporting evidence, never as the sole success/failure signal.

Timestamps are Unix seconds (UTC). Cancellation, queueing, or state synchronization can produce incomplete or non-intuitive timing combinations; always treat status as authoritative.

Notes

• API v2 supports Bearer token, the legacy api-key header, and query token. Prefer Bearer token for new integrations.
• Without start_time/end_time, this endpoint only returns runs from the current month. Pass both start_time and end_time (Unix seconds, same calendar month) to list archived runs from a prior month; cross-month ranges are rejected with code:11000 "run list time range cannot cross months".
• end_time is interpreted as a day boundary at 00:00:00: the server adds 86400 seconds before querying so the entire end day is included. When the end day is the last day of a month, pass it at 00:00:00 exactly (Beijing time, UTC+8) — any later time on that day causes the +86400 upper bound to cross into the next month and the request is rejected.
• See Run Lifecycle & Status for status handling, polling, failure diagnosis, and cancellation behavior.

HTTP Responses

HTTP Status	Application Code	Meaning
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