List and register pools via the Cloud Agents API

List durable pools with GET https://api.cursor.com/v0/private-workers/pools, and register a pool up front with POST to the same path. Official reference: Cloud Agents API → List Pools / Register A Pool (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 the pool's service account API key via Basic auth (-u "$CURSOR_API_KEY:") or Authorization: Bearer. Other API key types are rejected for these endpoints. Availability: Beta (all plans) per the API overview.

Durable pools stay registered after the last worker disconnects, so you can monitor scale-to-zero fleets and decide when to provision capacity. Starting a worker with --pool registers the pool implicitly; POST is only needed to create the pool before any worker connects (for example when a controller provisions capacity on demand).

List pools

Query parameters:

Param	Default	Meaning
scope	—	Filter: all, team_pool, or personal.
includeStale	false	When true, include pools marked stale after long inactivity.

curl --request GET \
  --url "https://api.cursor.com/v0/private-workers/pools?scope=team_pool&includeStale=false" \
  -u "$CURSOR_API_KEY:"

Each entry in pools includes:

Field	Meaning
scope	Pool ownership scope (user or team).
ownerId	Owning user or team id for the scope.
poolName	Pool name (for example default or gpu).
connectedWorkerCount	Workers currently connected to this pool.
inUseWorkerCount	Connected workers that currently have an assigned agent. Idle capacity is connectedWorkerCount - inUseWorkerCount.
firstSeenAtMs, lastSeenAtMs	First and last observation times in Unix milliseconds.
isStale	Whether the pool is marked stale after long inactivity.
repoOwner, repoName, repoUrl	Optional repository metadata when the pool is tied to a repo. Omitted for any-repo pools.
workerReadyTimeoutSeconds	Seconds a claimed request waits for this pool's offline worker to reconnect before the claim expires. 0 means follow-ups for an offline worker reacquire from the pool immediately.

Example response (any-repo sandbox omits repo fields and stays selectable with zero connected workers):

{
  "pools": [
    {
      "scope": "team",
      "ownerId": 456,
      "poolName": "gpu",
      "repoOwner": "acme",
      "repoName": "payments-service",
      "repoUrl": "https://github.com/acme/payments-service",
      "connectedWorkerCount": 2,
      "inUseWorkerCount": 1,
      "firstSeenAtMs": 1737000000000,
      "lastSeenAtMs": 1737306880000,
      "isStale": false,
      "workerReadyTimeoutSeconds": 900
    },
    {
      "scope": "team",
      "ownerId": 456,
      "poolName": "sandbox",
      "connectedWorkerCount": 0,
      "inUseWorkerCount": 0,
      "firstSeenAtMs": 1737100000000,
      "lastSeenAtMs": 1737200000000,
      "isStale": false,
      "workerReadyTimeoutSeconds": 0
    }
  ]
}

Register a pool

Request body:

Field	Required	Meaning
scope	yes	user or team.
poolName	yes	Pool name to register (for example gpu).
repoOwner, repoName	no	Provide both together, or omit both for an any-repo pool.
repoUrl	no	Display URL. Requires repoOwner and repoName.
workerReadyTimeoutSeconds	no (default 0)	Non-negative integer. Seconds a claimed request waits for an offline worker to reconnect before the claim expires. With 0, follow-ups reacquire from the pool immediately.

curl --request POST \
  --url "https://api.cursor.com/v0/private-workers/pools" \
  -u "$CURSOR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data '{
    "scope": "team",
    "poolName": "payments-pool",
    "repoOwner": "acme",
    "repoName": "payments-service",
    "repoUrl": "https://github.com/acme/payments-service"
  }'

Response: { "registered": true }.

Deregister a pool

DELETE https://api.cursor.com/v0/private-workers/pools soft-deletes a durable pool so it no longer appears in pool pickers or List Pools. Workers currently connected are not affected. Team pools require a team admin; user pools require their owner.

Required query params: scope (user or team) and pool_name. Optional repo_owner + repo_name together for a repo-scoped pool record; omit both for any-repo.

curl --request DELETE \
  --url "https://api.cursor.com/v0/private-workers/pools?scope=team&pool_name=sandbox" \
  -u "$CURSOR_API_KEY:"

Response: { "deregistered": true }.