METAGROK
API / list-and-get-cloud-agents-via-api

API

List and get Cloud Agents with the Cloud Agents API

list-and-get-cloud-agents-via-api

Enumerate agents with GET https://api.cursor.com/v1/agents, then load a full record with GET https://api.cursor.com/v1/agents/{id}. Official reference: Cloud Agents API → List Agents / Get An Agent.

Authenticate with Basic (-u YOUR_API_KEY:) or Bearer. Keys: Cursor Dashboard → API Keys. API v1 is public beta; availability Beta (all plans).

List returns newest first and only durable identity fields. Call Get for repos, workOnCurrentBranch, autoCreatePR, and the rest. Run execution status lives on runs — use latestRunId with Get A Run.

List query parameters

Parameter Rules
limit Optional. Default 20, max 100.
cursor Optional. Pass nextCursor from the previous page.
prUrl Optional. Filter by GitHub pull request URL.
includeArchived Optional. Default true.

nextCursor is omitted when there are no more pages (not returned as null). Treat absence as end of results.

List request

curl --request GET \
  --url 'https://api.cursor.com/v1/agents?limit=20' \
  -u YOUR_API_KEY:

Filter to a PR:

curl --request GET \
  --url 'https://api.cursor.com/v1/agents?prUrl=https%3A%2F%2Fgithub.com%2Fyour-org%2Fyour-repo%2Fpull%2F123' \
  -u YOUR_API_KEY:

Example list response:

{
  "items": [
    {
      "id": "bc-00000000-0000-0000-0000-000000000001",
      "name": "Add README with setup instructions",
      "status": "ACTIVE",
      "env": { "type": "cloud" },
      "url": "https://cursor.com/agents/bc-00000000-0000-0000-0000-000000000001",
      "createdAt": "2026-04-13T18:30:00.000Z",
      "updatedAt": "2026-04-13T18:45:00.000Z",
      "latestRunId": "run-00000000-0000-0000-0000-000000000001"
    }
  ],
  "nextCursor": "bc-00000000-0000-0000-0000-000000000002"
}

Get An Agent

curl --request GET \
  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001 \
  -u YOUR_API_KEY:

Agent status values

Status Meaning
ACTIVE A turn is running, waiting on background work, or about to start. Keep the machine up.
IDLE Last turn finished; follow-ups accepted. Machine may hibernate. Recoverable run errors also report IDLE — details stay on Get A Run.
ARCHIVED Archived or expired. Terminal; claims end and workspace state can be deleted.

Example get response:

{
  "id": "bc-00000000-0000-0000-0000-000000000001",
  "name": "Add README with setup instructions",
  "status": "ACTIVE",
  "env": { "type": "cloud" },
  "repos": [
    {
      "url": "https://github.com/your-org/your-repo",
      "startingRef": "main"
    }
  ],
  "workOnCurrentBranch": false,
  "autoCreatePR": true,
  "url": "https://cursor.com/agents/bc-00000000-0000-0000-0000-000000000001",
  "createdAt": "2026-04-13T18:30:00.000Z",
  "updatedAt": "2026-04-13T18:30:00.000Z",
  "latestRunId": "run-00000000-0000-0000-0000-000000000001"
}

Related how-tos