List pool workers via the Cloud Agents API

List Self-Hosted Machines pool workers with GET https://api.cursor.com/v0/private-workers. Official reference: Cloud Agents API → List Workers (Workers and Pools).

The Cloud Agents API v1 is in public beta. Paths under Workers and Pools 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 scale to zero and bring capacity back when pending requests appear. Creating an agent with env.type: "pool" is covered on Create An Agent; this endpoint is for monitoring connected workers.

Request

Query parameters:

Param	Default	Meaning
status	all	Filter: all, in_use, or idle.
scope	all	Filter: all, team_pool, or personal.
limit	50	Results per page (1–100).
pageToken	—	Pagination cursor from nextPageToken on the previous response.

curl --request GET \
  --url "https://api.cursor.com/v0/private-workers?status=idle&scope=team_pool&limit=50" \
  -u "$CURSOR_API_KEY:"

Response fields

workers is an array of connected workers, newest first. Each entry includes:

Field	Meaning
workerId	Unique worker id. Auto-generated ids are UUIDs; workers started with CURSOR_AGENT_WORKER_ID report that custom id.
isInUse	Whether the worker currently has an assigned agent.
repoOwner, repoName	Primary repository metadata when the worker registered a git remote. Empty strings for any-repo workers.
repoUrl	Optional primary repository URL. Omitted for any-repo workers.
workspaceRootPath	Primary workspace path on the worker.
connectedAtMs	Connection time in Unix milliseconds.
userId	Owning user id. 0 for workers authenticated with a service account key.
teamId	Optional team id for team pool workers.
serviceAccountId	Optional service account that authenticated the worker.
activeBcId	Optional id of the agent currently running on the worker, when in use.
name	Optional display name (--name, defaults to the machine hostname).

totalCount is the total workers matching the filter across all pages. nextPageToken is omitted when there are no more pages.

Example response:

{
  "workers": [
    {
      "workerId": "a8574fe8-248e-424a-a078-7584a2b93724",
      "repoOwner": "acme",
      "repoName": "payments-service",
      "repoUrl": "https://github.com/acme/payments-service",
      "workspaceRootPath": "/home/agent/payments-service",
      "connectedAtMs": 1737306880000,
      "userId": 0,
      "teamId": 456,
      "serviceAccountId": "sa_abc123",
      "isInUse": false,
      "name": "gpu-worker-1"
    }
  ],
  "totalCount": 1
}