List pending pool requests via the Cloud Agents API

List pool requests that have not been assigned to a worker yet with GET https://api.cursor.com/v0/private-workers/pending-requests. Official reference: Cloud Agents API → List Pending Pool Requests (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.

Use this endpoint to scale capacity when users are waiting for an available pool worker, or pair it with Claim A Pending Request before starting an ephemeral worker. The response includes a streamCursor you can pass to Watch Pending Pool Requests for real-time queue changes after this snapshot. Related endpoints on the same docs page: Watch Pending Pool Requests (GET /v0/private-workers/pending-requests/stream), Claim A Pending Request (POST /v0/private-workers/claim), and Release A Claim (POST /v0/private-workers/claims/{id}/release).

This endpoint returns requests for the key's team and excludes My Machines requests. If the key is scoped to specific repositories, pass repository; the repository must be in the key's allowed scope.

Request

Query parameters:

Param	Default	Meaning
limit	50	Number of pending requests to return (max 100).
pageToken	—	Pagination cursor from the previous response. Page tokens are bound to the repository and pool filters that issued them.
repository	—	Filter by repository URL. Required for repo-scoped service account API keys. Omit for any-repo pending requests.
pool	—	Filter by pool name. Exact, case-sensitive match against the request's pool label. Omit to list requests for every pool on the team.

curl --request GET \
  --url "https://api.cursor.com/v0/private-workers/pending-requests?limit=50&repository=https%3A%2F%2Fgithub.com%2Facme%2Fpayments-service" \
  -u "$CURSOR_API_KEY:"

Response fields

Each entry in requests includes:

Field	Meaning
id	Pending request / agent id (pass to Claim or Release A Claim as id).
userId	Cursor user id that created the request.
userEmail	Optional email of the requesting user, when available.
serviceAccountId	Optional service account associated with the request.
repoOwner, repoName, repoUrl	Optional repository metadata when the request targets a repo. Omitted for any-repo pool requests. repoUrl omits embedded credentials when the original URL includes userinfo.
labels	Request labels as { key, value } pairs (includes repo= and pool= when set).
createdAtMs	Request creation time in Unix milliseconds.
claimedWorkerId	Optional. Present on claimed-but-offline entries: the request is claimed by this worker, which is currently offline. Start a worker with this id (CURSOR_AGENT_WORKER_ID) to resume the agent on its machine.
wakeTimeoutMs	Optional. Milliseconds left in the reconnect window of a claimed-but-offline entry. When the window lapses, the claim expires and the request is re-advertised as an unclaimed entry.

For pools configured with workerReadyTimeoutSeconds, the listing also surfaces claimed-but-offline entries so a controller can revive the machine.

nextPageToken is omitted when there are no more pages. To measure queue depth, paginate to completion and count the requests. streamCursor is an opaque resume position for Watch Pending Pool Requests; every page of one logical listing repeats the same streamCursor. It expires five minutes after the list that issued it.

Example response:

{
  "requests": [
    {
      "id": "bc-00000000-0000-0000-0000-000000000002",
      "userId": 321,
      "userEmail": "owner@acme.example",
      "serviceAccountId": "sa_abc123",
      "repoOwner": "acme",
      "repoName": "payments-service",
      "repoUrl": "https://github.com/acme/payments-service",
      "labels": [
        { "key": "repo", "value": "acme/payments-service" },
        { "key": "pool", "value": "gpu" },
        { "key": "env", "value": "production" }
      ],
      "createdAtMs": 1737306880000
    }
  ],
  "nextPageToken": "eyJjcmVhdGVkQXRNcyI6MTczNzMwNjg4MDAwMH0=",
  "streamCursor": "djQuZXhhbXBsZS1vcGFxdWUtY3Vyc29y"
}