Cursor

App · 25 actions

Create and manage Cursor Cloud Agents, follow their runs, and manage saved environments and builds.

Actions

ActionWhat it does
Archive agentArchive an agent.
Cancel runStop an agent's run that is still going.
Create environmentSave an environment agents can start from.
Delete agentDelete an agent for good.
Delete environmentDelete a saved environment for good.
Get active environment buildFind out what an agent started on this environment starts from: one of its builds, or Cursor's own.
Get agentGet an agent's details: its name, status and repositories.
Get agent usageGet how much an agent has used, run by run.
Get API key detailsGet the name of the API key this connection uses, and when it was made.
Get environmentGet a saved environment, its setup and how it is built.
Get environment buildGet one of an environment's builds.
Get runGet a run's status, and when it started and finished.
List agentsList your agents, newest first.
List artifactsList the files an agent made.
List environment buildsList an environment's builds, newest first.
List environment historyList the changes made to an environment, newest first.
List environmentsList your saved environments, most recently changed first.
List modelsList the models an agent can use.
List repositoriesList the GitHub repositories Cursor can work in.
List runsList an agent's runs, newest first.
Send follow-upGive a running agent another instruction.
Start agentStart a Cursor agent on a coding task in a repository.
Start environment buildBuild an environment.
Unarchive agentBring an archived agent back, so it can be given work again.
Update environmentRename an environment, or change its setup or repositories.

Archive agent

Archive an agent.

Inputs

Agentagent_idtextRequired
Unique identifier for the agent.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "id": "example"
  },
  "has_more": false,
  "next_cursor": null
}

Cancel run

Stop an agent's run that is still going.

Inputs

Agentagent_idtextRequired
Unique identifier for the agent.
Run IDrun_idtextRequired
Unique identifier for the run.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "id": "example"
  },
  "has_more": false,
  "next_cursor": null
}

Create environment

Save an environment agents can start from.

Inputs

OwnerownertextRequired
`personal` creates an environment for the API key's user, and `team` creates one for the team.One of: personal, team.
NamenametextRequired
Display name. It must differ from the names of the owner's other environments; a name the owner already uses returns `409 environment_name_conflict`.
ReposreposlistRequired
Repositories for the environment, or an empty array for an environment without repositories. Cursor must be able to reach each one through your source control integration; otherwise the request returns `400 repository_access`.
Environment JSONenvironment_jsonobjectRequired
The environment's `environment.json`, as a JSON-encoded string, using the same schema as a `.cursor/environment.json` file. An invalid configuration returns `400 validation_error`.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "createdAt": "example",
    "id": "example",
    "name": "example",
    "owner": "example",
    "repos": [],
    "updatedAt": "example"
  },
  "has_more": false,
  "next_cursor": null
}

Delete agent

Delete an agent for good.

Inputs

Agentagent_idtextRequired
Unique identifier for the agent.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "id": "example"
  },
  "has_more": false,
  "next_cursor": null
}

Delete environment

Delete a saved environment for good.

Inputs

Environmentenvironment_idtextRequired
Unique identifier for the environment.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "id": "example"
  },
  "has_more": false,
  "next_cursor": null
}

Get active environment build

Find out what an agent started on this environment starts from: one of its builds, or Cursor's own.

Inputs

Environmentenvironment_idtextRequired
Unique identifier for the environment.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "buildId": "example",
    "type": "example"
  },
  "has_more": false,
  "next_cursor": null
}

Get agent

Get an agent's details: its name, status and repositories.

Inputs

Agentagent_idtextRequired
Unique identifier for the agent.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "autoCreatePR": false,
    "createdAt": "example",
    "customSubagents": [],
    "env": {
      "name": "example",
      "type": "example"
    },
    "id": "example",
    "latestRunId": "example",
    "name": "example",
    "repos": [],
    "skipReviewerRequest": false,
    "status": "example",
    "updatedAt": "example",
    "url": "example",
    "workOnCurrentBranch": false
  },
  "has_more": false,
  "next_cursor": null
}

Get agent usage

Get how much an agent has used, run by run.

Inputs

Agentagent_idtextRequired
Unique identifier for the agent.
Run IDrun_idtext
Scope usage to a single run. Omit to return usage for every run on the agent.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "runs": [],
    "totalUsage": {
      "cacheReadTokens": 0,
      "cacheWriteTokens": 0,
      "inputTokens": 0,
      "outputTokens": 0,
      "totalTokens": 0
    }
  },
  "has_more": false,
  "next_cursor": null
}

Get API key details

Get the name of the API key this connection uses, and when it was made.

Inputs

None.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "apiKeyName": "example",
    "createdAt": "example",
    "userEmail": "example",
    "userFirstName": "example",
    "userId": 0,
    "userLastName": "example"
  },
  "has_more": false,
  "next_cursor": null
}

Get environment

Get a saved environment, its setup and how it is built.

Inputs

Environmentenvironment_idtextRequired
Unique identifier for the environment.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "buildSettings": {
      "installTimeoutMinutes": null,
      "pullLatestCode": "example",
      "stalenessThresholdHours": null
    },
    "createdAt": "example",
    "environmentJson": "example",
    "id": "example",
    "name": "example",
    "owner": "example",
    "repoFile": {
      "path": "example",
      "url": "example"
    },
    "repos": [],
    "updatedAt": "example",
    "versionId": "example"
  },
  "has_more": false,
  "next_cursor": null
}

Get environment build

Get one of an environment's builds.

Inputs

Environmentenvironment_idtextRequired
Unique identifier for the environment.
Build IDbuild_idtextRequired
Unique identifier for the build.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "completedAt": "example",
    "createdAt": "example",
    "draft": false,
    "environmentId": "example",
    "failure": {
      "code": "example",
      "type": "example"
    },
    "id": "example",
    "repoCommits": [],
    "requestedRefs": [],
    "snapshotState": "example",
    "source": "example",
    "status": "example",
    "trigger": "example",
    "updatedAt": "example"
  },
  "has_more": false,
  "next_cursor": null
}

Get run

Get a run's status, and when it started and finished.

Inputs

Agentagent_idtextRequired
Unique identifier for the agent.
Run IDrun_idtextRequired
Unique identifier for the run.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "agentId": "example",
    "createdAt": "example",
    "durationMs": 0,
    "git": {
      "branches": []
    },
    "id": "example",
    "result": "example",
    "status": "example",
    "updatedAt": "example"
  },
  "has_more": false,
  "next_cursor": null
}

List agents

List your agents, newest first. Gets one page; to see more, run it again with the next page it gives.

Inputs

Limitlimitnumber
Number of agents to return.From 1 to 100.
Cursorcursortext
Pagination cursor from the previous response.
Pr URLpr_urltext
Filter agents by GitHub pull request URL.
Include archivedinclude_archivedtrue/false
Whether to include archived agents.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "items": [],
    "nextCursor": "example"
  },
  "has_more": false,
  "next_cursor": null
}

List artifacts

List the files an agent made.

Inputs

Agentagent_idtextRequired
Unique identifier for the agent.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "items": []
  },
  "has_more": false,
  "next_cursor": null
}

List environment builds

List an environment's builds, newest first. Gets one page; to see more, run it again with the next page it gives.

Inputs

Environmentenvironment_idtextRequired
Unique identifier for the environment.
Statusstatustext
Only builds with this status.One of: IN_PROGRESS, SUCCEEDED, FAILED, CANCELLED, SKIPPED.
Created aftercreated_afterdate and time
Only builds created at or after this time. Use an ISO 8601 timestamp with `Z` or a UTC offset and at most millisecond precision.
Created beforecreated_beforedate and time
Only builds created before this time, in the same format as `createdAfter`. It must be later than `createdAfter`.
Limitlimitnumber
Number of builds to return.From 1 to 100.
Cursorcursortext
Pagination cursor from `nextCursor` on the previous response. Send the same filters with it.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "items": [],
    "nextCursor": "example"
  },
  "has_more": false,
  "next_cursor": null
}

List environment history

List the changes made to an environment, newest first. Gets one page; to see more, run it again with the next page it gives.

Inputs

Environmentenvironment_idtextRequired
Unique identifier for the environment.
Limitlimitnumber
Number of events to return.From 1 to 100.
Cursorcursortext
Pagination cursor from `nextCursor` on the previous response.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "items": [],
    "nextCursor": "example"
  },
  "has_more": false,
  "next_cursor": null
}

List environments

List your saved environments, most recently changed first. Gets one page; to see more, run it again with the next page it gives.

Inputs

Queryquerytext
Only environments whose name contains this text, ignoring case.
Ownerownertext
Only environments with this `owner`.One of: personal, team.
Namednamedtrue/false
`true` for only environments with a `name`, or `false` for only environments without one.
Reporepolist
Only environments that include this repository. Repeat it, up to 100 times, to list environments that include any of the repositories.
Target user IDtarget_user_idtext
Only one user's personal environments, by the numeric `userId` from GET /v1/me or the `user_` ID from the Admin API's team members list. Your own ID lists your personal environments. A team admin's user API key can also pass a current team member's ID, and gets that member's personal environments that have at least one repository, all of which the admin can read. A valid ID for a user you aren't allowed to list returns `items: []` with no `nextCursor`, not an error. Combining `userId` with `owner=team` returns `400 validation_error`.
Limitlimitnumber
Number of environments to return.From 1 to 100.
Cursorcursortext
Pagination cursor from the previous response. Send the same filters with each `cursor`.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "items": [],
    "nextCursor": "example"
  },
  "has_more": false,
  "next_cursor": null
}

List models

List the models an agent can use.

Inputs

None.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "items": []
  },
  "has_more": false,
  "next_cursor": null
}

List repositories

List the GitHub repositories Cursor can work in.

Inputs

None.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "items": []
  },
  "has_more": false,
  "next_cursor": null
}

List runs

List an agent's runs, newest first. Gets one page; to see more, run it again with the next page it gives.

Inputs

Agentagent_idtextRequired
Unique identifier for the agent.
Limitlimitnumber
Limit.From 1 to 100.
Cursorcursortext
Pagination cursor from the previous response.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "items": [],
    "nextCursor": "example"
  },
  "has_more": false,
  "next_cursor": null
}

Send follow-up

Give a running agent another instruction. It counts towards your Cursor usage.

Inputs

Agentagent_idtextRequired
Unique identifier for the agent.
PromptprompttextRequired
The task or follow-up instructions.
Modelmodel_idtext
Choose a model, or leave empty to use your configured default.
Mcp serversmcp_serverslist
Inline MCP server definitions for this follow-up run. When provided, these definitions replace any create-time inline MCP servers for this run.
Env varsenv_varsobject
Environment variables for this follow-up run only, applied while it executes. Names and values follow the `EnvVars` rules.
Modemodetext
Conversation mode. `plan` explores and drafts a plan before coding; `agent` implements changes directly. On follow-up runs, omit to keep the conversation's current mode; set explicitly to switch modes for that run.One of: agent, plan.
Deliverydeliverytext
Choose steer to interrupt an active run with this prompt; leave empty to start a follow-up run. Steering accepts only the prompt, without model, mode, environment variables or MCP servers.One of: steer.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "run": {
      "agentId": "example",
      "createdAt": "example",
      "durationMs": 0,
      "git": {
        "branches": []
      },
      "id": "example",
      "result": "example",
      "status": "example",
      "updatedAt": "example"
    }
  },
  "has_more": false,
  "next_cursor": null
}

Start agent

Start a Cursor agent on a coding task in a repository. It runs in the cloud and counts towards your Cursor usage.

Inputs

PromptprompttextRequired
The task or follow-up instructions.
Modelmodel_idtext
Choose a model, or leave empty to use your configured default.
Namenametext
Display name for the agent. Auto-derived from the prompt when omitted.
Agentagent_idtext
Optional client-supplied agent identifier in `bc- ` form. Re-POSTing the same `agentId` returns `409 agent_id_conflict` instead of creating a duplicate. Cannot be combined with `envVars`; omit `agentId` so the server mints one when you need session secrets.
Envenvobject
Env.
Reposreposlist
Repository configuration. Mutually exclusive with a named cloud environment. Omit both `repos` and `env` (or pass `repos: []`) to start a no-repo agent. On self-hosted targets, only a named any-repo pool takes more than one entry. `machine`, the `default` pool, and repo-backed pools take one and return `400` for more.
Work on current branchwork_on_current_branchtrue/false
When `false` (the default), Cursor pushes commits to a new auto-generated branch (`cursor/...`) based on `repos[0].startingRef` (or the PR base ref when `prUrl` is set). When `true`, Cursor pushes directly to that starting ref , for a non-PR create, that's the branch you passed in `startingRef`; for a `prUrl` create, that's the PR's head branch.
Auto create prauto_create_prtrue/false
Whether Cursor should open a pull request when the run completes.
Skip reviewer requestskip_reviewer_requesttrue/false
Whether to skip requesting the user as a reviewer when Cursor opens a PR. Only applies when `autoCreatePR` is true.
Env varsenv_varsobject
Session-scoped environment variables for the cloud agent. Values are encrypted at rest, injected into the agent's shell, and deleted with the agent. Names and values follow the `EnvVars` rules. Cannot be combined with a client-supplied `agentId`. Beta: `envVars` is rolling out. If it isn't enabled for your account yet, the field is silently ignored on create rather than failing the request , verify the values are present on a first run before relying on them in production.
Mcp serversmcp_serverslist
Inline MCP server definitions available to the initial run. Remote servers support `headers` or OAuth `auth`; stdio servers run inside the cloud agent VM and can receive `env`. Server names must be unique.
Custom subagentscustom_subagentslist
Custom subagents the main agent can delegate to. Names must be unique and not collide with built-ins.
Modemodetext
Initial conversation mode for the agent's first run.One of: agent, plan.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "agent": {
      "autoCreatePR": false,
      "createdAt": "example",
      "customSubagents": [],
      "env": {
        "name": "example",
        "type": "example"
      },
      "id": "example",
      "latestRunId": "example",
      "name": "example",
      "repos": [],
      "skipReviewerRequest": false,
      "status": "example",
      "updatedAt": "example",
      "url": "example",
      "workOnCurrentBranch": false
    },
    "run": {
      "agentId": "example",
      "createdAt": "example",
      "durationMs": 0,
      "git": {
        "branches": []
      },
      "id": "example",
      "result": "example",
      "status": "example",
      "updatedAt": "example"
    }
  },
  "has_more": false,
  "next_cursor": null
}

Start environment build

Build an environment. It counts towards your Cursor usage.

Inputs

Environmentenvironment_idtextRequired
Unique identifier for the environment.
Draftdrafttrue/false
`true` for a draft build, which agents don't start from until it's activated. A non-draft build is what agents start from once it succeeds.
Refsrefslist
Branches to build instead of the default branches. Repositories without an entry build their default branch, and a ref that names the default branch counts as no entry. Any other branch requires `draft` set to `true`; without it, and for a repository that isn't in the environment or a second ref for the same repository, the request returns `400 validation_error`. Cursor doesn't check that the branch exists, so a missing branch fails the build, not the request.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "environmentId": "example",
    "id": "example"
  },
  "has_more": false,
  "next_cursor": null
}

Unarchive agent

Bring an archived agent back, so it can be given work again.

Inputs

Agentagent_idtextRequired
Unique identifier for the agent.

Outputs

Result.

dataobject
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": {
    "id": "example"
  },
  "has_more": false,
  "next_cursor": null
}

Update environment

Rename an environment, or change its setup or repositories.

Inputs

Environmentenvironment_idtextRequired
Unique identifier for the environment.
Namenametext
New display name. It must differ from the names of the owner's other environments; a name the owner already uses returns `409 environment_name_conflict`.
Environment JSONenvironment_jsonobject
Replacement `environment.json`, as a JSON-encoded string, using the same schema as a `.cursor/environment.json` file. It replaces the whole configuration. An invalid configuration returns `400 validation_error`. If the environment reads its configuration from a file in its only repository, the request returns `409 repo_file_environment_locked`.
Reposreposlist
The environment's full list of repositories, replacing the current list. It follows the same rules as `repos` on POST /v1/environments. Send `environmentJson` with it, because a repository change saves the whole configuration; `repos` without `environmentJson` returns `400 validation_error`. To keep the current configuration, send the `environmentJson` from GET /v1/environments/{id}. Only environments with two or more repositories can change them, and they must keep at least two. Sending the current list unchanged doesn't count as a change. Otherwise an environment without repositories, a single-repository environment, or a list with fewer th
Build settingsbuild_settingsobject
New values for any of the build settings GET /v1/environments/{id} returns. Fields you leave out stay unchanged, and `null` resets a field to its default.

Outputs

Result.

datanull
The complete service response; record and list fields retain their API names.
has_moretrue/false
Whether the API reports another page.
next_cursortext
Pass to the pagination field for the next page, when Has more is true.
Example output
{
  "data": null,
  "has_more": false,
  "next_cursor": null
}

On this page