List Run Queue Items

Method: GET

Endpoint: /api/v2/run-queue/items

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/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.

When to use this endpoint

Use this endpoint to see what is currently in the Run Queue. Each item represents a Worker run you submitted via Queue Worker Run that has not started executing yet — for example, a run that is waiting because the account balance was insufficient at submit time.

Typical uses:

Check how many runs are waiting before you decide what to do next.
Find the queue_ref of items you want to activate (start running) or release (give up and remove).

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 endpoints. Constraints: default `20`; range 1-100.
`status`	No	`string`	Filter by queue status. Allowed values: `waiting` (the run is held in the queue and not running yet) and `inactive`.

Request Example

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

Response Example

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

The exact fields inside data.list[] follow the platform’s queue item shape. The one you will use most is queue_ref — copy it to activate or release the item.

Notes

API v2 supports Bearer token, the legacy api-key header, and query token. Prefer Bearer token for new integrations.
queue_ref is the identifier you pass to Activate Run Queue Items, Release Run Queue Items, and Release One Run Queue Item.
For background on run states, see Run Lifecycle & Status.

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