METAGROK
API / create-and-list-cloud-agent-runs-via-api

API

Create and list Cloud Agent runs with the Cloud Agents API

create-and-list-cloud-agent-runs-via-api

Send a follow-up with POST https://api.cursor.com/v1/agents/{id}/runs, list history with GET .../runs, and read one run with GET .../runs/{runId}. Official reference: Cloud Agents API → Create A Run / List Runs / Get A Run.

Authenticate with Basic or Bearer. The new run reuses the agent's conversation and workspace. Only one run can be active per agent. Calling create while another run is CREATING or RUNNING returns 409 agent_busy — wait for it to finish, or cancel it.

Create A Run body

Field Rules
prompt.text Required follow-up instruction.
prompt.images Optional. Max 5 images, 15 MB each; data+mimeType or url.
mcpServers Optional. Replaces create-time inline MCP servers for this run. Omit to keep current MCP config.
mode Optional override: agent or plan. Omit to keep the conversation's current mode. 
curl --request POST \
  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/runs \
  -u YOUR_API_KEY: \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": {
      "text": "Also add troubleshooting steps"
    }
  }'

Response:

{
  "run": {
    "id": "run-00000000-0000-0000-0000-000000000002",
    "agentId": "bc-00000000-0000-0000-0000-000000000001",
    "status": "CREATING",
    "createdAt": "2026-04-13T18:50:00.000Z",
    "updatedAt": "2026-04-13T18:50:00.000Z"
  }
}

List Runs

Query: limit (default 20, max 100), cursor from prior nextCursor. Newest first.

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

Example item (may include git.branches once a branch is pushed):

{
  "items": [
    {
      "id": "run-00000000-0000-0000-0000-000000000002",
      "agentId": "bc-00000000-0000-0000-0000-000000000001",
      "status": "RUNNING",
      "createdAt": "2026-04-13T18:50:00.000Z",
      "updatedAt": "2026-04-13T18:51:00.000Z",
      "git": {
        "branches": [
          {
            "repoUrl": "github.com/your-org/your-repo",
            "branch": "cursor/add-readme-a1b2"
          }
        ]
      }
    }
  ]
}

Get A Run

Base fields (id, agentId, status, createdAt, updatedAt) are always present. Terminal runs add:

Field When
durationMs After FINISHED, ERROR, CANCELLED, or EXPIRED.
result Final assistant reply text for a terminated run.
git When a branch has been pushed. Per-agent snapshot, same across every run on that agent — attribute work with latestRunId or the SSE stream.

git.branches[].repoUrl omits the scheme (github.com/org/repo). Create requests still use full https:// URLs.

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

{
  "id": "run-00000000-0000-0000-0000-000000000001",
  "agentId": "bc-00000000-0000-0000-0000-000000000001",
  "status": "FINISHED",
  "createdAt": "2026-04-13T18:30:00.000Z",
  "updatedAt": "2026-04-13T18:45:00.000Z",
  "durationMs": 12357,
  "result": "Added README.md with installation instructions and usage examples.",
  "git": {
    "branches": [
      {
        "repoUrl": "github.com/your-org/your-repo",
        "branch": "cursor/add-readme-a1b2",
        "prUrl": "https://github.com/your-org/your-repo/pull/123"
      }
    ]
  }
}

Related how-tos