# Cursor

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

App · 25 actions. Web page: https://docs.lodol.com/docs/integrations/cursor

## Actions

### Archive agent

Archive an agent.

**Inputs**

- Agent (`agent_id`, text, required): Unique identifier for the agent.

**Outputs**: Result.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "data": {
    "id": "example"
  },
  "has_more": false,
  "next_cursor": null
}
```

### Cancel run

Stop an agent's run that is still going.

**Inputs**

- Agent (`agent_id`, text, required): Unique identifier for the agent.
- Run ID (`run_id`, text, required): Unique identifier for the run.

**Outputs**: Result.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "data": {
    "id": "example"
  },
  "has_more": false,
  "next_cursor": null
}
```

### Create environment

Save an environment agents can start from.

**Inputs**

- Owner (`owner`, text, required): `personal` creates an environment for the API key's user, and `team` creates one for the team. One of: `personal`, `team`.
- Name (`name`, text, required): 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`.
- Repos (`repos`, list, required): 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 JSON (`environment_json`, object, required): 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.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "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**

- Agent (`agent_id`, text, required): Unique identifier for the agent.

**Outputs**: Result.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "data": {
    "id": "example"
  },
  "has_more": false,
  "next_cursor": null
}
```

### Delete environment

Delete a saved environment for good.

**Inputs**

- Environment (`environment_id`, text, required): Unique identifier for the environment.

**Outputs**: Result.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "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**

- Environment (`environment_id`, text, required): Unique identifier for the environment.

**Outputs**: Result.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "data": {
    "buildId": "example",
    "type": "example"
  },
  "has_more": false,
  "next_cursor": null
}
```

### Get agent

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

**Inputs**

- Agent (`agent_id`, text, required): Unique identifier for the agent.

**Outputs**: Result.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "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**

- Agent (`agent_id`, text, required): Unique identifier for the agent.
- Run ID (`run_id`, text): Scope usage to a single run. Omit to return usage for every run on the agent.

**Outputs**: Result.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "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.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "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**

- Environment (`environment_id`, text, required): Unique identifier for the environment.

**Outputs**: Result.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "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**

- Environment (`environment_id`, text, required): Unique identifier for the environment.
- Build ID (`build_id`, text, required): Unique identifier for the build.

**Outputs**: Result.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "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**

- Agent (`agent_id`, text, required): Unique identifier for the agent.
- Run ID (`run_id`, text, required): Unique identifier for the run.

**Outputs**: Result.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "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**

- Limit (`limit`, number): Number of agents to return. From 1 to 100.
- Cursor (`cursor`, text): Pagination cursor from the previous response.
- Pr URL (`pr_url`, text): Filter agents by GitHub pull request URL.
- Include archived (`include_archived`, true/false): Whether to include archived agents.

**Outputs**: Result.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "data": {
    "items": [],
    "nextCursor": "example"
  },
  "has_more": false,
  "next_cursor": null
}
```

### List artifacts

List the files an agent made.

**Inputs**

- Agent (`agent_id`, text, required): Unique identifier for the agent.

**Outputs**: Result.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "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**

- Environment (`environment_id`, text, required): Unique identifier for the environment.
- Status (`status`, text): Only builds with this status. One of: `IN_PROGRESS`, `SUCCEEDED`, `FAILED`, `CANCELLED`, `SKIPPED`.
- Created after (`created_after`, date 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 before (`created_before`, date and time): Only builds created before this time, in the same format as `createdAfter`. It must be later than `createdAfter`.
- Limit (`limit`, number): Number of builds to return. From 1 to 100.
- Cursor (`cursor`, text): Pagination cursor from `nextCursor` on the previous response. Send the same filters with it.

**Outputs**: Result.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "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**

- Environment (`environment_id`, text, required): Unique identifier for the environment.
- Limit (`limit`, number): Number of events to return. From 1 to 100.
- Cursor (`cursor`, text): Pagination cursor from `nextCursor` on the previous response.

**Outputs**: Result.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "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**

- Query (`query`, text): Only environments whose name contains this text, ignoring case.
- Owner (`owner`, text): Only environments with this `owner`. One of: `personal`, `team`.
- Named (`named`, true/false): `true` for only environments with a `name`, or `false` for only environments without one.
- Repo (`repo`, list): Only environments that include this repository. Repeat it, up to 100 times, to list environments that include any of the repositories.
- Target user ID (`target_user_id`, text): 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`.
- Limit (`limit`, number): Number of environments to return. From 1 to 100.
- Cursor (`cursor`, text): Pagination cursor from the previous response. Send the same filters with each `cursor`.

**Outputs**: Result.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "data": {
    "items": [],
    "nextCursor": "example"
  },
  "has_more": false,
  "next_cursor": null
}
```

### List models

List the models an agent can use.

**Inputs**: None.

**Outputs**: Result.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "data": {
    "items": []
  },
  "has_more": false,
  "next_cursor": null
}
```

### List repositories

List the GitHub repositories Cursor can work in.

**Inputs**: None.

**Outputs**: Result.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "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**

- Agent (`agent_id`, text, required): Unique identifier for the agent.
- Limit (`limit`, number): Limit. From 1 to 100.
- Cursor (`cursor`, text): Pagination cursor from the previous response.

**Outputs**: Result.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "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**

- Agent (`agent_id`, text, required): Unique identifier for the agent.
- Prompt (`prompt`, text, required): The task or follow-up instructions.
- Model (`model_id`, text): Choose a model, or leave empty to use your configured default.
- Mcp servers (`mcp_servers`, list): Inline MCP server definitions for this follow-up run. When provided, these definitions replace any create-time inline MCP servers for this run.
- Env vars (`env_vars`, object): Environment variables for this follow-up run only, applied while it executes. Names and values follow the `EnvVars` rules.
- Mode (`mode`, text): 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`.
- Delivery (`delivery`, text): 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.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "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**

- Prompt (`prompt`, text, required): The task or follow-up instructions.
- Model (`model_id`, text): Choose a model, or leave empty to use your configured default.
- Name (`name`, text): Display name for the agent. Auto-derived from the prompt when omitted.
- Agent (`agent_id`, text): 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.
- Env (`env`, object): Env.
- Repos (`repos`, list): 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 branch (`work_on_current_branch`, true/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 pr (`auto_create_pr`, true/false): Whether Cursor should open a pull request when the run completes.
- Skip reviewer request (`skip_reviewer_request`, true/false): Whether to skip requesting the user as a reviewer when Cursor opens a PR. Only applies when `autoCreatePR` is true.
- Env vars (`env_vars`, object): 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 servers (`mcp_servers`, list): 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 subagents (`custom_subagents`, list): Custom subagents the main agent can delegate to. Names must be unique and not collide with built-ins.
- Mode (`mode`, text): Initial conversation mode for the agent's first run. One of: `agent`, `plan`.

**Outputs**: Result.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "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**

- Environment (`environment_id`, text, required): Unique identifier for the environment.
- Draft (`draft`, true/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.
- Refs (`refs`, list): 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.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "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**

- Agent (`agent_id`, text, required): Unique identifier for the agent.

**Outputs**: Result.

- `data` (object): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "data": {
    "id": "example"
  },
  "has_more": false,
  "next_cursor": null
}
```

### Update environment

Rename an environment, or change its setup or repositories.

**Inputs**

- Environment (`environment_id`, text, required): Unique identifier for the environment.
- Name (`name`, text): 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 JSON (`environment_json`, object): 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`.
- Repos (`repos`, list): 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 settings (`build_settings`, object): 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.

- `data` (null): The complete service response; record and list fields retain their API names.
- `has_more` (true/false): Whether the API reports another page.
- `next_cursor` (text): Pass to the pagination field for the next page, when Has more is true.

**Example output**

```json
{
  "data": null,
  "has_more": false,
  "next_cursor": null
}
```
