METAGROK
API / claim-a-pending-pool-request-via-api

API

Claim a pending pool request via the Cloud Agents API

claim-a-pending-pool-request-via-api

Reserve a pending pool request for a specific worker before that worker starts with POST https://api.cursor.com/v0/private-workers/claim. Official reference: Cloud Agents API → Claim A Pending Request (Workers and Pools).

The Cloud Agents API v1 is in public beta. Paths keep the older private-workers name; they refer to the same Self-Hosted Machines workers. Authenticate with a service account API key via Basic auth (-u "$CURSOR_API_KEY:") or Authorization: Bearer. Other API key types are rejected. Availability: Beta (all plans) per the API overview.

Controllers use this to atomically assign work across replicas: read pending requests (via List Pending Pool Requests or Watch Pending Pool Requests), claim one, then start a worker with a stable worker id that matches the claim.

A second claim while a live claim exists is rejected. Call Release A Claim (POST /v0/private-workers/claims/{id}/release) first, then claim a new workerId.

Request body

Field Required Meaning
id yes Pending request id. Same value as id from List Pending Pool Requests.
workerId yes Worker id to reserve for the request. Start the worker with the same id via CURSOR_AGENT_WORKER_ID (or the hidden --worker-id flag) so the bridge registers the claimed identity. 
curl --request POST \
  --url "https://api.cursor.com/v0/private-workers/claim" \
  -u "$CURSOR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "bc-00000000-0000-0000-0000-000000000002",
    "workerId": "pw_123"
  }'

Response

{
  "id": "bc-00000000-0000-0000-0000-000000000002",
  "workerId": "pw_123"
}

Start the worker after claim

After a successful claim, start the worker with the reserved id:

export CURSOR_API_KEY="your-service-account-api-key"
export CURSOR_AGENT_WORKER_ID="pw_123"
agent worker --pool gpu --worker-dir /workspace start

The CURSOR_AGENT_WORKER_ID value must match the workerId you passed in the claim body. Related monitoring: Get Worker By ID (GET /v0/private-workers/{id}) and List Workers (GET /v0/private-workers).