Queue Worker Run

Method: POST

Endpoint: /api/v2/workers/{workerId}/queued-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}/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)

When to use this endpoint

Use this endpoint to submit a Worker run into the Run Queue. Unlike Run Worker (POST /api/v2/workers/{workerId}/runs), which starts executing right away, the queued version places the run in the queue and returns a queue_ref. You then decide when (and whether) the run actually starts.

A common outcome is that the run lands in waiting and does not start on its own — for example, when the account balance is insufficient at submit time, the run is held instead of rejected. You resolve the condition (e.g. top up the balance) and then start the run yourself with Activate Run Queue Items. If you decide not to run it, remove it with Release Run Queue Items.

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`	Accepted for API consistency but has no effect: a queued run is always placed in the queue and the response returns a `queue_ref`, never a synchronous run result. To run synchronously, use Run Worker instead.
`limit`	No	`integer`	Accepted for API consistency but has no effect on the queued-run response, which returns a `queue_ref` rather than a result window. Constraints: default `20`; range 1-100.
`offset`	No	`integer`	Accepted for API consistency but has no effect on the queued-run response. Constraints: default `1`; 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

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

Request Example

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

Response Example

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

Response Fields

Field	Type	Description
`queue_ref`	`string`	The queue item ID. Use it to activate or release the run later.
`queue_status`	`string`	Status of the item in the queue, for example `waiting`. A `waiting` item is held in the queue and will not start until you activate it.
`queued`	`boolean`	Whether the run was accepted into the queue.

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.
version is optional. Omit it unless you have confirmed a concrete available version; not every Worker accepts latest as an explicit version value.
If the run lands in waiting (for example due to insufficient balance), it will not start on its own — call Activate Run Queue Items after resolving the condition.
See Run Lifecycle & Status for status handling, polling, failure diagnosis, and cancellation behavior.
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