Run Worker

Method: POST

Endpoint: /api/v2/workers/{workerId}/runs

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

Try it

POST/api/v2/workers/{workerId}/runsRun worker

AuthenticationRequired

Auth mode

Authorization: Bearerapi-key headerQuery token

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)Reset to example

{ "input": { "parameters": { "custom": {} } }, "is_async": true, "limit": 20, "offset": 0 }

Send Request Clear all

When to use this endpoint

Use this endpoint to start a Worker with a fresh input payload instead of a saved task.

Identifier Notes

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

Path Parameters

Parameter	Required	Type	Description
workerId	Yes	string	Worker slug or path. You may paste owner/name; the playground sends it as owner~name for path values.

Request Body

Send the request body with Content-Type: application/json. Required/Optional describes each field; the Try it Request Body badge shows whether the body itself is required.

Field	Required	Type	Description
callback_url	No	string	Callback URL. When provided, CoreClaw sends a POST request after the run status changes or finishes.
input	No	any	Worker input payload. Worker form fields usually belong under input.parameters.custom; read the Worker input schema first and build this object from that schema.
is_async	No	boolean	true submits asynchronously without waiting for results; false waits for the run to finish. Defaults to true. Sync mode waits at most 5 minutes; if the run has not finished by then, the request returns and you must poll status via the run query endpoint.
limit	No	integer	Synchronous result window size for runs or reruns. It only controls how many result rows are included in the synchronous response, not the full result set. Constraints: default 20; range 1-100.
offset	No	integer	Zero-based offset for the synchronous result window returned by runs or reruns. Constraints: default 0; minimum 0.
version	No	string	Optional Worker version. Omit it unless you have confirmed a concrete available version for this Worker; not every Worker accepts latest as an explicit version value.

JSON Example

{
  "input": {
    "parameters": {
      "custom": {
        "keywords": [
          "coffee"
        ],
        "base_location": "New York,USA",
        "max_results": 1
      }
    }
  },
  "is_async": true,
  "limit": 20,
  "offset": 0
}

Run Mode

• is_async: true submits the run asynchronously and returns without waiting for execution results. The response includes data.run_slug; then poll the run detail, log, and result endpoints.
• is_async: false waits for the run to finish, equivalent to run-and-wait behavior. Use offset / limit to control the result window returned by the synchronous run.

⚠️ Sync wait limit: 5 minutes. When is_async: false, the platform waits for the run for up to 5 minutes at most. If the run has not finished within 5 minutes, the request returns anyway and the run keeps executing in the background — you must then use the run query endpoint to poll status, logs, and results by runId. For runs that may exceed 5 minutes, prefer is_async: true.

Request Example

curl -X POST "https://openapi.coreclaw.com/api/v2/workers/YOUR_WORKER_ID/runs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"input":{"parameters":{"custom":{"keywords":["coffee"],"base_location":"New York,USA","max_results":1}}},"is_async":true,"limit":20,"offset":0}'

Response Example

{
  "code": 0,
  "data": {
    "run_slug": "01KKDXV2G26BT7NH4ZQR2R4NPZ"
  },
  "message": "success",
  "request_id": "req-123"
}

Notes

• API v2 supports Bearer token, the legacy api-key header, and query token. Prefer Bearer token for new integrations.
• Read the Worker input schema first before building input; fields differ by Worker.
• Use offset and limit only to control the synchronous result window; they do not change the full result set produced by the Worker.
• version is optional. Omit it unless you have confirmed a concrete available version; not every Worker accepts latest as an explicit version value.
• When callback_url is provided, CoreClaw sends callback notifications after status changes or completion. See Callback Notifications.

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