Skip to main content

Command Palette

Search for a command to run...

API

API de Cloud Agents

La API de Cloud Agents te permite lanzar y gestionar de forma programática agentes de programación en la nube que trabajan en tus repositorios.

Endpoints

Crear un agente

POST/v1/agents

Crea un agente en la nube y encola inmediatamente su ejecución inicial. La respuesta devuelve tanto el agent duradero como el run inicial.

Cuerpo de la solicitud

prompt objeto (obligatorio)

La instrucción de la tarea para el agente, incluyendo imágenes opcionales.

prompt.text string (obligatorio)

El texto de instrucciones para el agente.

prompt.images array (opcional)

Entradas de imagen para el prompt. Cada entrada debe incluir ya sea data (bytes codificados en base64 con un mimeType obligatorio) o url (una URL http o https que Cursor recupera). Máximo 5 imágenes, 15 MB cada una. Tipos MIME compatibles: image/png, image/jpeg, image/gif, image/webp.

model objeto (opcional)

Selección de modelo. Omita este campo para usar el valor predeterminado configurado. Si se omite, Cursor resolverá primero su modelo predeterminado de usuario, luego el modelo predeterminado del equipo y, por último, un valor predeterminado del sistema.

model.id string (obligatorio si se proporciona model)

Un ID de modelo explícito devuelto por GET /v1/models (por ejemplo, claude-4-sonnet-thinking).

model.params arreglo (opcional)

Parámetros por modelo que se aplican a la ejecución, como el esfuerzo de razonamiento o el tamaño de la ventana de contexto. Cada elemento tiene un id y un value. Usa solo los parámetros compatibles con el modelo seleccionado: llama a GET /v1/models para descubrir las combinaciones válidas de id/params.

name string (opcional)

Nombre visible del agente. Máximo 100 caracteres. Si se omite, Cursor deriva automáticamente un nombre a partir del mensaje.

env objeto (opcional)

Destino del entorno de ejecución. Usa un entorno cloud con nombre, o enruta a un pool o machine que tú alojes. Es mutuamente excluyente con repos explícitos al seleccionar un entorno con nombre alojado por Cursor.

env.type cadena (obligatoria si se proporciona env)

Tipo de entorno de ejecución. cloud utiliza máquinas virtuales alojadas por Cursor; pool y machine enrutan a tus propios workers.

env.name string (opcional)

Nombre del entorno alojado por Cursor, del pool o de la máquina. Para env.type: "pool", este es el nombre del pool (si se omite, el valor predeterminado es default). Un nombre de pool desconocido devuelve 400 en lugar de quedar encolado indefinidamente.

repos array (opcional)

Configuración del repositorio. Es mutuamente excluyente con un entorno en la nube con nombre. Omita tanto repos como env para iniciar un agente sin repositorios. También puede omitir repos cuando env.type es pool para apuntar a un pool de cualquier repositorio. Máximo: 20 repositorios.

repos[0].url string (obligatorio)

URL del repositorio de GitHub (por ejemplo, https://github.com/your-org/your-repo). Obligatorio en cada entrada del repositorio, incluso cuando se proporciona prUrl.

repos[0].startingRef string (opcional)

Nombre de la rama o SHA del commit que se utilizará como punto de partida. Se ignora cuando se proporciona prUrl.

repos[0].prUrl string (opcional)

URL de la pull request de GitHub. Si se proporciona, el agente trabaja en el repositorio y las ramas de esta PR; startingRef se ignora. url debe seguir estando establecido en la misma entrada de repos.

workOnCurrentBranch booleano (opcional, predeterminado: false)

Cuando es false (el valor predeterminado), Cursor envía los commits a una nueva rama generada automáticamente (cursor/...) basada en repos[0].startingRef (o en la ref base del PR cuando se establece prUrl). Cuando es true, Cursor hace push directamente a esa ref de inicio: para una creación sin PR, esa es la rama que pasaste en startingRef; para una creación con prUrl, esa es la rama head del PR. La rama a la que el agente hizo push aparece en git.branches[] del agente.

autoCreatePR boolean (opcional)

Si Cursor debe abrir un pull request cuando finalice la ejecución.

skipReviewerRequest booleano (opcional)

Si se debe omitir solicitar al usuario como revisor cuando Cursor abra un PR. Solo se aplica cuando autoCreatePR es true.

envVars objeto (opcional)

Variables de entorno con alcance de sesión para el agente en la nube. Los valores se cifran en reposo, se inyectan en el shell del agente y se eliminan junto con el agente. Máximo 50 entradas; nombres de hasta 255 bytes (no pueden comenzar con CURSOR_), valores de hasta 4096 bytes. No se puede combinar con un agentId proporcionado por el cliente.
Beta: envVars se está implementando. Si aún no está habilitado para tu cuenta, el campo se ignora silenciosamente al crear en lugar de provocar el fallo de la solicitud — verifica que los valores estén presentes inspeccionando el shell del agente en la primera ejecución antes de confiar en ellos en producción.

mcpServers array (opcional)

Definiciones inline de servidores MCP disponibles para el agente. Máximo 50 servidores. Los servidores remotos admiten headers o auth de OAuth; los servidores stdio se ejecutan dentro de la VM en la nube y pueden recibir env. Los nombres de los servidores deben ser únicos.

mcpServers[0].name string (obligatorio)

El nombre del servidor MCP expuesto al agente.

mcpServers[0].type string (opcional)

Tipo de transporte: http, sse o stdio. Por defecto, http para servidores remotos con url, y stdio para servidores con command.

mcpServers[0].url string (obligatorio para MCP remoto)

URL HTTP o HTTPS de un servidor MCP remoto. No se permiten URL con nombre de usuario ni contraseña.

mcpServers[0].command string (obligatorio para MCP stdio)

Comando para iniciar un servidor MCP stdio dentro de la VM del agente en la nube. Usa args y env para los argumentos y los secretos en tiempo de ejecución.

customSubagents array (opcional)

Defina subagentes personalizados a los que el agente principal puede delegar durante la ejecución. Máximo 20 subagentes. Cada entrada requiere name, description y prompt, además de un model opcional (cadena con el ID del modelo, objeto ModelSelection o "inherit"). Los nombres deben ser únicos y no pueden coincidir con los integrados (explore, debug, shell, computerUse, etc.).

mode string (opcional, predeterminado: agent)

Modo de conversación inicial para la primera ejecución del agente. plan explora y redacta un plan antes de programar (modo Plan); agent implementa los cambios directamente.

agentId string (opcional)

Identificador de agente proporcionado por el cliente en el formato bc-<uuid>. Útil para flujos de creación idempotentes: volver a enviar un POST con el mismo agentId devuelve 409 agent_id_conflict en lugar de crear un duplicado. No se puede combinar con envVars; omite agentId para que el servidor emita uno cuando necesites secretos de sesión.
curl --request POST \  --url https://api.cursor.com/v1/agents \  -u YOUR_API_KEY: \  --header 'Content-Type: application/json' \  --data '{    "prompt": {      "text": "Add a README with setup instructions"    },    "model": {      "id": "composer-2",      "params": [        { "id": "fast", "value": "true" }      ]    },    "repos": [      {        "url": "https://github.com/your-org/your-repo",        "startingRef": "main"      }    ],    "mcpServers": [      {        "name": "linear",        "type": "http",        "url": "https://mcp.linear.app/sse",        "headers": {          "Authorization": "Bearer YOUR_LINEAR_API_KEY"        }      },      {        "name": "github",        "type": "stdio",        "command": "npx",        "args": ["-y", "@modelcontextprotocol/server-github"],        "env": {          "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN"        }      }    ],    "autoCreatePR": true  }'

Pool de workers (incluido cualquier repositorio):

curl --request POST \  --url https://api.cursor.com/v1/agents \  -u YOUR_API_KEY: \  --header 'Content-Type: application/json' \  --data '{    "prompt": {      "text": "Clone the payments service and add a health check"    },    "env": {      "type": "pool",      "name": "sandbox"    }  }'

Respuesta:

{  "agent": {    "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"  },  "run": {    "id": "run-00000000-0000-0000-0000-000000000001",    "agentId": "bc-00000000-0000-0000-0000-000000000001",    "status": "CREATING",    "createdAt": "2026-04-13T18:30:00.000Z",    "updatedAt": "2026-04-13T18:30:00.000Z"  }}

Listar agentes de programación

GET/v1/agents

Lista los agentes de programación del usuario autenticado, empezando por los más recientes.

Parámetros de consulta

limit number (opcional)

Número de agentes de programación que se devolverán. Predeterminado: 20. Máximo: 100.

cursor string (opcional)

Cursor de paginación tomado de nextCursor en la respuesta anterior.

prUrl string (opcional)

Filtra los agentes de programación por la URL del pull request de GitHub.

includeArchived boolean (opcional, valor predeterminado: true)

Indica si la respuesta debe incluir agentes de programación archivados.
curl --request GET \  --url 'https://api.cursor.com/v1/agents?limit=20' \  -u YOUR_API_KEY:

Respuesta:

{  "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"}

Obtener un agente de programación

GET/v1/agents/{id}

Recupera los metadatos persistentes de un agente de programación. El estado de ejecución se almacena en las ejecuciones: obtén latestRunId y llama a Obtener una ejecución para consultar su estado.

Parámetros de ruta

id string

Identificador único del agente de programación (por ejemplo, bc-00000000-0000-0000-0000-000000000001).

Campos de respuesta

status string

Estado del ciclo de vida del agente de programación. Los controladores lo usan para decidir si una máquina debe permanecer encendida:
  • ACTIVE — Hay una interacción en curso, esperando trabajo en segundo plano o a punto de comenzar. Mantén encendida la máquina del agente de programación.
  • IDLE — La última interacción finalizó y se aceptan mensajes de seguimiento. La máquina del agente de programación puede hibernarse o crear una instantánea. Las ejecuciones que terminaron con un error recuperable también indican IDLE; el detalle del error a nivel de ejecución permanece en Obtener una ejecución.
  • ARCHIVED — El agente de programación se archivó o expiró. Estado terminal; las afirmaciones finalizan y el estado del espacio de trabajo puede eliminarse.
curl --request GET \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001 \  -u YOUR_API_KEY:

Respuesta:

{  "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"}

Crear una ejecución

POST/v1/agents/{id}/runs

Envía una instrucción de seguimiento a un agente de programación activo. La nueva ejecución usa la conversación y el estado actual del espacio de trabajo del agente de programación.

Parámetros de ruta

id string

Identificador único del agente de programación (por ejemplo, bc-00000000-0000-0000-0000-000000000001).

Cuerpo de la solicitud

prompt object (required)

La instrucción de seguimiento, incluidas imágenes opcionales.

prompt.text string (required)

El texto de la instrucción de seguimiento.

prompt.images array (optional)

Entradas de imagen para el seguimiento. Cada entrada debe incluir data (bytes codificados en base64 con un mimeType obligatorio) o url. Máximo 5 imágenes de 15 MB cada una. Tipos MIME compatibles: image/png, image/jpeg, image/gif, image/webp.

mcpServers array (optional)

Definiciones inline de servidores MCP para esta ejecución de seguimiento. Cuando se proporcionan, sustituyen cualquier definición inline de servidores MCP configurada al crear esta ejecución. Omítelo para mantener la configuración actual de MCP del agente de programación.

mode string (optional)

Anulación del modo de conversación para esta ejecución de seguimiento: agent o plan. Omítelo para mantener el modo actual de la conversación de ejecuciones anteriores.
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"    },    "mcpServers": [      {        "name": "docs",        "type": "http",        "url": "https://example.com/mcp"      }    ]  }'

Respuesta:

{  "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"  }}

Listar ejecuciones

GET/v1/agents/{id}/runs

Lista las ejecuciones de un agente de programación, con las más recientes primero.

Parámetros de ruta

id string

Identificador único del agente de programación.

Parámetros de consulta

limit number (opcional)

Número de ejecuciones que se devolverán. Predeterminado: 20. Máx.: 100.

cursor string (opcional)

Cursor de paginación de nextCursor de la respuesta anterior.
curl --request GET \  --url 'https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/runs?limit=20' \  -u YOUR_API_KEY:

Respuesta:

{  "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"          }        ]      }    }  ]}

Obtener una ejecución

GET/v1/agents/{id}/runs/{runId}

Recupera el estado, las marcas de tiempo y, en las ejecuciones finalizadas, el resultado final, la duración y las ramas enviadas de una ejecución específica.

Parámetros de ruta

id string

Identificador único del agente de programación.

runId string

Identificador único de la ejecución (por ejemplo, run-00000000-0000-0000-0000-000000000001).

Campos de respuesta

Los campos base de la ejecución (id, agentId, status, createdAt, updatedAt) siempre están presentes. Los siguientes se completan en cuanto hay datos disponibles:

durationMs entero (ejecuciones finalizadas)

Duración real transcurrida de la ejecución en milisegundos, calculada una vez que la ejecución alcanza FINISHED, ERROR, CANCELLED o EXPIRED.

result string (ejecuciones finalizadas)

Texto de la respuesta final del asistente para una ejecución terminada.

git object (cuando se ha enviado una rama)

Las ramas y pull request actuales enviadas por el agente de programación. git.branches[] contiene entradas { repoUrl, branch?, prUrl? }: una por cada rama que el agente de programación haya enviado (los agentes de programación encadenados generan varias).
Estado por agente de programación, no por ejecución. Cada ejecución del mismo agente de programación devuelve la misma instantánea de git. Usa el latestRunId del agente de programación o el flujo SSE para atribuir el trabajo a una ejecución específica.
repoUrl se devuelve sin el esquema (por ejemplo, github.com/your-org/your-repo), a diferencia de repos[].url en la solicitud, que mantiene el prefijo https://.
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:

Respuesta:

{  "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": "Se añadió README.md con instrucciones de instalación y ejemplos de uso.",  "git": {    "branches": [      {        "repoUrl": "github.com/your-org/your-repo",        "branch": "cursor/add-readme-a1b2",        "prUrl": "https://github.com/your-org/your-repo/pull/123"      }    ]  }}

Transmitir el flujo de una ejecución

GET/v1/agents/{id}/runs/{runId}/stream

Transmite eventos Server-Sent Events (SSE) para una ejecución. El flujo se limita a la ejecución solicitada y no reproduce ejecuciones anteriores.

Tipos de eventos

  • status — actualización del estado de la ejecución. Payload: { runId, status }.
  • assistant — delta de texto del asistente. Payload: { text }.
  • thinking — delta de texto de razonamiento. Payload: { text }.
  • tool_call — actualización del estado de la llamada a herramienta. Payload: { callId, name, status, args?, result?, truncated? }.
  • interaction_update — evento enriquecido opcional emitido junto con los eventos simplificados anteriores. El payload coincide con la estructura InteractionUpdate consumida por el SDK de TypeScript, con subtipos como text-delta, tool-call-started / tool-call-completed, step-started / step-completed y turn-ended. Si solo necesitas texto sin formato y llamadas a herramientas, gestiona los eventos simplificados e ignora interaction_update. Si quieres el flujo completo con la estructura del SDK, gestiona interaction_update e ignora los eventos simplificados.
  • heartbeat — evento de keepalive. Payload: {}.
  • result — estado terminal de la ejecución. Payload: { runId, status, text?, durationMs?, git? }. text es la respuesta final del asistente, durationMs es la duración total de la ejecución en milisegundos, y git refleja Run.git (las ramas actuales enviadas por el agente, no solo las de esta ejecución).
  • error — error del flujo. Payload: { code, message }.
  • done — flujo completado. Payload: {}.

Payloads de llamadas a herramientas

Los eventos tool_call usan una estructura estable en torno a las entradas y salidas específicas de cada herramienta:

type JsonValue =  | string  | number  | boolean  | null  | JsonValue[]  | { [key: string]: JsonValue };interface ToolCallEventData {  callId: string;  name: string;  status: "running" | "completed";  args?: JsonValue;  result?: JsonValue;  truncated?: {    args?: true;    result?: true;  };}

callId identifica una invocación de herramienta a lo largo de las actualizaciones. name es el nombre público de la herramienta, como read_file, run_terminal_cmd o mcp. args y result son valores JSON específicos de la herramienta. Si args o result es demasiado grande para incluirlo en el flujo, Cursor omite ese campo y establece el indicador truncated correspondiente.

Reanudar un flujo

La mayoría de los eventos incluyen una línea id — una cadena opaca que no debes analizar (el formato actual se parece a 1713033006000-0, pero trátalo como opaco). El evento status inicial no tiene id — es un evento de encuadre persistente que se vuelve a enviar al inicio de cada reconexión.

Para reanudar después de una desconexión, vuelve a conectarte con Last-Event-ID configurado con el id del evento recibido más reciente. El id del evento debe pertenecer a la ejecución solicitada; de lo contrario, la solicitud devuelve 400 invalid_last_event_id. Después de una reanudación correcta, espera otro evento status antes de que comience el rango reanudado.

Retención

Las respuestas del flujo incluyen el encabezado X-Cursor-Stream-Retention-Seconds. Una vez transcurrida la ventana de retención, este endpoint puede devolver 410 stream_expired. Tómalo como una señal para consultar el estado terminal mediante Obtener una ejecución en lugar de reintentar el flujo.

curl --request GET \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/runs/run-00000000-0000-0000-0000-000000000001/stream \  -u YOUR_API_KEY: \  --header 'Accept: text/event-stream'

Ejemplo de flujo:

event: statusdata: {"runId":"run-00000000-0000-0000-0000-000000000001","status":"RUNNING"}id: 1713033000000-0event: assistantdata: {"text":"Actualizaré el README ahora."}id: 1713033005000-0event: tool_calldata: {"callId":"call-1","name":"read_file","status":"running","args":{"path":"README.md"}}id: 1713033006000-0event: tool_calldata: {"callId":"call-1","name":"read_file","status":"completed","args":{"path":"README.md"},"result":{"success":{"content":"# Project","totalLines":1,"fileSize":9,"path":"README.md"}}}id: 1713033010000-0event: resultdata: {"runId":"run-00000000-0000-0000-0000-000000000001","status":"FINISHED","text":"Se agregó README.md con instrucciones de instalación.","durationMs":12357,"git":{"branches":[{"repoUrl":"github.com/your-org/your-repo","branch":"cursor/add-readme-a1b2"}]}}id: 1713033010000-0event: donedata: {}

Cancelar una ejecución

POST/v1/agents/{id}/runs/{runId}/cancel

Cancela la ejecución activa de un agente de programación. La cancelación es definitiva: la ejecución pasa a CANCELLED y no puede reanudarse. Para continuar la conversación, crea una nueva ejecución en el mismo agente de programación.

Parámetros de ruta

id string

Identificador único del agente de programación.

runId string

Identificador único de la ejecución que se va a cancelar.
curl --request POST \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/runs/run-00000000-0000-0000-0000-000000000001/cancel \  -u YOUR_API_KEY:

Respuesta:

{  "id": "run-00000000-0000-0000-0000-000000000001"}

Obtener el consumo del agente

GET/v1/agents/{id}/usage

Recupera el consumo de tokens de un agente, desglosado por ejecución. La respuesta suma el consumo de todas las ejecuciones del agente y muestra el consumo de cada ejecución individual. El consumo de tokens refleja el valor de tokenUsage informado por el endpoint de eventos de consumo del equipo.

Parámetros de ruta

id string

Identificador único del agente (por ejemplo, bc-00000000-0000-0000-0000-000000000001).

Parámetros de consulta

runId string (opcional)

Limita la respuesta a una sola ejecución (por ejemplo, run-00000000-0000-0000-0000-000000000001). Omítelo para devolver el consumo de todas las ejecuciones del agente. Un runId desconocido devuelve 404 run_not_found.

Campos de la respuesta

totalUsage object

Consumo de tokens sumado en todas las ejecuciones devueltas. Contiene los mismos campos que el objeto usage de cada ejecución.

runs array

Consumo por ejecución, una entrada por cada ejecución (o una sola entrada cuando se establece runId). Cada objeto contiene:
  • id string - Identificador de la ejecución (por ejemplo, run-00000000-0000-0000-0000-000000000001).
  • usageUuid string (opcional) - Identificador interno de consumo de la ejecución. Se omite cuando la ejecución aún no tiene consumo registrado.
  • usage object - Consumo de tokens de esta ejecución:
    • inputTokens number - Tokens de entrada consumidos.
    • outputTokens number - Tokens de salida generados.
    • cacheWriteTokens number - Tokens escritos en la caché.
    • cacheReadTokens number - Tokens leídos de la caché.
    • totalTokens number - Suma de los cuatro conteos de tokens anteriores.
# Todas las ejecuciones del agentecurl --request GET \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/usage \  -u YOUR_API_KEY:# Una sola ejecucióncurl --request GET \  --url 'https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/usage?runId=run-00000000-0000-0000-0000-000000000001' \  -u YOUR_API_KEY:

Respuesta:

{  "totalUsage": {    "inputTokens": 12480,    "outputTokens": 3110,    "cacheWriteTokens": 18200,    "cacheReadTokens": 42600,    "totalTokens": 76390  },  "runs": [    {      "id": "run-00000000-0000-0000-0000-000000000002",      "usageUuid": "00000000-0000-0000-0000-000000000002",      "usage": {        "inputTokens": 6320,        "outputTokens": 1450,        "cacheWriteTokens": 7100,        "cacheReadTokens": 21300,        "totalTokens": 36170      }    },    {      "id": "run-00000000-0000-0000-0000-000000000001",      "usageUuid": "00000000-0000-0000-0000-000000000001",      "usage": {        "inputTokens": 6160,        "outputTokens": 1660,        "cacheWriteTokens": 11100,        "cacheReadTokens": 21300,        "totalTokens": 40220      }    }  ]}

Artefactos

Los artefactos están limitados al agente, ya que el espacio de trabajo persiste entre ejecuciones.

Listar artefactos

GET/v1/agents/{id}/artifacts

Enumera los artefactos generados por un agente. El path de cada artefacto es relativo al directorio artifacts/ del espacio de trabajo.

Parámetros de ruta

id string

Identificador único del agente.
curl --request GET \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/artifacts \  -u YOUR_API_KEY:

Respuesta:

{  "items": [    {      "path": "artifacts/screenshot.png",      "sizeBytes": 12345,      "updatedAt": "2026-04-13T18:45:00.000Z"    }  ]}

Descargar un artefacto

GET/v1/agents/{id}/artifacts/download

Obtén una URL temporal prefirmada de S3, válida durante 15 minutos, para un artefacto específico.

Parámetros de ruta

id string

Identificador único del agente.

Parámetros de consulta

path string

Ruta relativa del artefacto devuelta por Listar artefactos (por ejemplo, artifacts/screenshot.png). Debe estar dentro de artifacts/.
curl --request GET \  --url 'https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/artifacts/download?path=artifacts/screenshot.png' \  -u YOUR_API_KEY:

Respuesta:

{  "url": "https://cloud-agent-artifacts.s3.us-east-1.amazonaws.com/...",  "expiresAt": "2026-04-13T19:00:00.000Z"}

Ciclo de vida del agente de programación

Archivar un agente de programación

POST/v1/agents/{id}/archive

Archiva un agente de programación. Los agentes de programación archivados se pueden seguir consultando, pero no pueden aceptar nuevas ejecuciones hasta que se desarchiven. Úsalo para flujos reversibles de "eliminación suave".

Parámetros de ruta

id string

Identificador único del agente de programación.
curl --request POST \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/archive \  -u YOUR_API_KEY:

Respuesta:

{  "id": "bc-00000000-0000-0000-0000-000000000001"}

Desarchivar un agente de programación

POST/v1/agents/{id}/unarchive

Desarchiva un agente de programación para que pueda volver a aceptar nuevas ejecuciones.

Parámetros de ruta

id string

Identificador único del agente de programación.
curl --request POST \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/unarchive \  -u YOUR_API_KEY:

Respuesta:

{  "id": "bc-00000000-0000-0000-0000-000000000001"}

Eliminar un agente de programación de forma permanente

DELETE/v1/agents/{id}

Elimina un agente de programación de forma permanente. Esta acción es irreversible. Usa Archivar para una eliminación reversible.

Parámetros de ruta

id string

Identificador único del agente de programación.
curl --request DELETE \  --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001 \  -u YOUR_API_KEY:

Respuesta:

{  "id": "bc-00000000-0000-0000-0000-000000000001"}

Tokens de worker

Crear un token de worker con alcance de usuario

POST/v1/sub-tokens

Crea un token con alcance de usuario con una validez de una hora para que un worker se ejecute como un miembro activo del equipo.

Requiere una clave de API de cuenta de servicio del equipo limitada al agente. Los tokens con alcance de usuario no pueden generar otros tokens con alcance de usuario.

Cuerpo de la solicitud

Especifica exactamente una de las siguientes opciones para identificar al usuario de destino:

forUserEmail string (optional)

Correo electrónico del miembro activo del equipo. No distingue entre mayúsculas y minúsculas.

forUserId integer (optional)

ID numérico de usuario de Cursor del miembro activo del equipo.

Por correo electrónico:

curl --request POST \  --url https://api.cursor.com/v1/sub-tokens \  --header "Authorization: Bearer $CURSOR_SERVICE_ACCOUNT_API_KEY" \  --header "Content-Type: application/json" \  --data '{    "forUserEmail": "alice@company.com"  }'

Por ID de usuario:

curl --request POST \  --url https://api.cursor.com/v1/sub-tokens \  --header "Authorization: Bearer $CURSOR_SERVICE_ACCOUNT_API_KEY" \  --header "Content-Type: application/json" \  --data '{    "forUserId": 42  }'

Respuesta:

{  "accessToken": "eyJ...",  "expiresAt": "2026-04-24T19:00:00.000Z",  "userId": 42,  "teamId": 456}

Workers y pools

Supervisa el uso de los workers y configura el autoescalado para tus pools. Los pools persistentes permanecen registrados después de que se desconecta el último worker, por lo que puedes escalar a cero y recuperar capacidad cuando aparezcan solicitudes pendientes.

Las rutas de los endpoints conservan el nombre anterior private-workers; se refieren a los mismos workers.

Autentícate con la clave de API de la cuenta de servicio del pool mediante Basic auth o Bearer token. Se rechaza cualquier otro tipo de clave de API.

Listar workers

GET/v0/private-workers

Lista los workers del pool del equipo de la cuenta de servicio autenticada, ordenados del más reciente al más antiguo.

Parámetros de consulta

status string (opcional, predeterminado: all)

Filtra por estado del worker. Uno de all, in_use o idle.

scope string (opcional, predeterminado: all)

Filtra por ámbito del worker. Uno de all, team_pool o personal.

limit integer (opcional, predeterminado: 50)

Resultados por página. Rango: de 1 a 100.

pageToken string (opcional)

Cursor de paginación. Pasa el nextPageToken de la respuesta anterior.

Campos de respuesta

workers array

Workers conectados. Cada entrada incluye:
  • workerId string — Identificador único del worker. Los ID generados automáticamente son UUID; los workers iniciados con CURSOR_AGENT_WORKER_ID informan ese ID personalizado en su lugar.
  • isInUse boolean — Indica si el worker tiene actualmente un agente asignado.
  • repoOwner, repoName string — Metadatos del repositorio principal cuando el worker registró un git remote. Cadenas vacías para workers de cualquier repositorio.
  • repoUrl string (opcional) — URL del repositorio principal. Se omite para workers de cualquier repositorio.
  • workspaceRootPath string — Ruta principal del espacio de trabajo en el worker.
  • connectedAtMs integer — Hora de conexión en milisegundos Unix.
  • userId integer — ID del usuario propietario. 0 para workers autenticados con una clave de cuenta de servicio.
  • teamId integer (opcional) — ID de equipo para workers del pool de equipo.
  • serviceAccountId string (opcional) — Cuenta de servicio con la que se autenticó el worker.
  • activeBcId string (opcional) — ID del agente que se está ejecutando actualmente en el worker, cuando está en uso.
  • name string (opcional) — Nombre visible del worker (--name, el valor predeterminado es el hostname de la máquina).

totalCount integer

Total de workers que coinciden con el filtro en todas las páginas.

nextPageToken string (opcional)

Cursor de paginación para pageToken. Se omite cuando no hay más páginas.
curl --request GET \  --url "https://api.cursor.com/v0/private-workers?status=idle&scope=team_pool&limit=50" \  -u "$CURSOR_API_KEY:"

Respuesta:

{  "workers": [    {      "workerId": "a8574fe8-248e-424a-a078-7584a2b93724",      "repoOwner": "acme",      "repoName": "payments-service",      "repoUrl": "https://github.com/acme/payments-service",      "workspaceRootPath": "/home/agent/payments-service",      "connectedAtMs": 1737306880000,      "userId": 0,      "teamId": 456,      "serviceAccountId": "sa_abc123",      "isInUse": false,      "name": "gpu-worker-1"    }  ],  "totalCount": 1}

Obtener resumen de workers

GET/v0/private-workers/summary

Devuelve el número de workers conectados y en uso para el usuario autenticado y su equipo. Úsalo para tomar decisiones de escalado cuando el uso sea alto.

curl --request GET \  --url "https://api.cursor.com/v0/private-workers/summary" \  -u "$CURSOR_API_KEY:"

Ejemplo de comprobación de escalado:

const summary = await response.json();const team = summary.teamSummary;if (team && team.totalConnected > 0) {  const utilization = team.inUse / team.totalConnected;  if (utilization >= 0.9) {    // Escalar: aprovisionar workers adicionales  }}

Obtener worker por ID

GET/v0/private-workers/{id}

Obtiene un único worker del pool a partir de su ID.

Parámetros de ruta

id string

Identificador único del worker (por ejemplo, pw_123).
curl --request GET \  --url "https://api.cursor.com/v0/private-workers/pw_123" \  -u "$CURSOR_API_KEY:"

Listar pools

GET/v0/private-workers/pools

Enumera los pools persistentes del equipo de la cuenta de servicio autenticada. Los pools permanecen registrados después de que se desconecte el último worker, por lo que puedes supervisar flotas que escalan a cero y decidir cuándo aprovisionar capacidad.

Parámetros de consulta

scope string (opcional)

Filtra por el ámbito de la lista de pools. Puede ser all, team_pool o personal.

includeStale boolean (opcional, predeterminado: false)

Cuando es true, incluye pools marcados como obsoletos tras un periodo prolongado de inactividad.

Campos de respuesta

pools array

Pools registrados. Cada entrada incluye:
  • scope string — Ámbito de propiedad del pool (user o team).
  • ownerId integer — ID del usuario o equipo propietario en ese ámbito.
  • poolName string — Nombre del pool (por ejemplo, default o gpu).
  • connectedWorkerCount integer — Workers conectados actualmente a este pool.
  • inUseWorkerCount integer — Workers conectados que tienen un agente asignado. La capacidad inactiva es connectedWorkerCount - inUseWorkerCount.
  • firstSeenAtMs, lastSeenAtMs integer — Hora de la primera y última detección, en milisegundos Unix.
  • isStale boolean — Indica si el pool está marcado como obsoleto tras un periodo prolongado de inactividad.
  • repoOwner, repoName, repoUrl string (opcional) — Metadatos del repositorio cuando el pool está vinculado a un repositorio. Se omiten para los pools de cualquier repositorio.
  • workerReadyTimeoutSeconds integer — Segundos que una solicitud afirmada espera a que el worker desconectado de este pool se reconecte antes de que venza la afirmación. 0 significa que los mensajes de seguimiento de un worker desconectado vuelven a obtener un worker del pool inmediatamente.
curl --request GET \  --url "https://api.cursor.com/v0/private-workers/pools?scope=team_pool&includeStale=false" \  -u "$CURSOR_API_KEY:"

Respuesta:

{  "pools": [    {      "scope": "team",      "ownerId": 456,      "poolName": "gpu",      "repoOwner": "acme",      "repoName": "payments-service",      "repoUrl": "https://github.com/acme/payments-service",      "connectedWorkerCount": 2,      "inUseWorkerCount": 1,      "firstSeenAtMs": 1737000000000,      "lastSeenAtMs": 1737306880000,      "isStale": false,      "workerReadyTimeoutSeconds": 900    },    {      "scope": "team",      "ownerId": 456,      "poolName": "sandbox",      "connectedWorkerCount": 0,      "inUseWorkerCount": 0,      "firstSeenAtMs": 1737100000000,      "lastSeenAtMs": 1737200000000,      "isStale": false,      "workerReadyTimeoutSeconds": 0    }  ]}

La entrada sandbox es de cualquier repositorio: se omiten los campos del repositorio y el pool sigue siendo seleccionable sin workers conectados.

Registrar un pool

POST/v0/private-workers/pools

Registra un pool persistente sin iniciar un worker. Úsalo para que un pool pueda seleccionarse antes de que se conecte un worker, por ejemplo, cuando un controlador aprovisiona capacidad bajo demanda. Iniciar un worker con --pool registra el pool implícitamente; este endpoint solo es necesario para crear el pool por adelantado.

Cuerpo de la solicitud

scope string (obligatorio)

Ámbito de propiedad del pool: user o team.

poolName string (obligatorio)

Nombre del pool que se va a registrar (por ejemplo, gpu).

repoOwner, repoName string (opcional)

Metadatos del repositorio si el pool está vinculado a un repositorio. Proporciona ambos u omite ambos para un pool de cualquier repositorio.

repoUrl string (opcional)

URL del repositorio que se mostrará. Requiere repoOwner y repoName.

workerReadyTimeoutSeconds integer (opcional, predeterminado: 0)

Segundos que una solicitud afirmada espera a que un worker desconectado de este pool se reconecte antes de que expire la afirmación y la solicitud vuelva a la cola. Establece este valor cuando las máquinas hibernan entre interacciones y pueden reactivarse. Con 0, los mensajes de seguimiento de un worker desconectado vuelven a obtener un worker del pool inmediatamente. Debe ser un entero no negativo.

Campos de respuesta

registered boolean

Indica si el pool se registró.
curl --request POST \  --url "https://api.cursor.com/v0/private-workers/pools" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "scope": "team",    "poolName": "payments-pool",    "repoOwner": "acme",    "repoName": "payments-service",    "repoUrl": "https://github.com/acme/payments-service"  }'

Respuesta:

{  "registered": true}

Anular el registro de un pool

DELETE/v0/private-workers/pools

Anula el registro (eliminación lógica) de un pool persistente para que deje de aparecer en los selectores de pools o en Listar pools. Los workers conectados actualmente al pool no se ven afectados. Los pools de equipo requieren un administrador de equipo; los pools de usuario requieren a su propietario.

Parámetros de consulta

scope string (obligatorio)

Ámbito de propiedad del pool. Uno de los siguientes: user o team.

pool_name string (obligatorio)

Nombre del pool cuyo registro se va a anular.

repo_owner string (opcional)

Propietario del repositorio al anular el registro de un pool con ámbito de repositorio.

repo_name string (opcional)

Nombre del repositorio al anular el registro de un pool con ámbito de repositorio. Proporciona repo_owner y repo_name juntos, u omite ambos para un pool de cualquier repositorio.
curl --request DELETE \  --url "https://api.cursor.com/v0/private-workers/pools?scope=team&pool_name=sandbox" \  -u "$CURSOR_API_KEY:"

Respuesta:

{  "deregistered": true}

Listar solicitudes pendientes del pool

GET/v0/private-workers/pending-requests

Lista las solicitudes de pools que aún no se han asignado a un worker. Usa este endpoint para escalar la capacidad cuando los usuarios esperan que haya un worker del pool disponible, o combínalo con Reclamar una solicitud pendiente antes de iniciar un worker efímero.

En los pools configurados con workerReadyTimeoutSeconds, el listado también muestra las entradas reclamadas pero sin conexión: solicitudes cuyo worker reclamado está sin conexión mientras hay una ventana de reconexión abierta. Estas entradas incluyen claimedWorkerId y wakeTimeoutMs para que un controller pueda reactivar la máquina.

Este endpoint requiere una clave de API de cuenta de servicio. Devuelve las solicitudes del equipo asociado a la clave y excluye las solicitudes de Mis máquinas. Si la clave está limitada a repositorios específicos, proporciona repository; el repositorio debe estar dentro del alcance permitido de la clave.

La respuesta incluye un streamCursor. Pásalo a Supervisar solicitudes pendientes del pool para seguir los cambios en la cola en tiempo real después de esta instantánea.

Parámetros de consulta

limit número (opcional)

Número de solicitudes pendientes que se devolverán. Valor predeterminado: 50. Máximo: 100.

pageToken cadena (opcional)

Cursor de paginación de la respuesta anterior. Los tokens de página están vinculados a los filtros repository y pool con los que se emitieron.

repository cadena (opcional)

Filtra por la URL del repositorio. Obligatorio para las claves de API de cuentas de servicio con alcance limitado a repositorios. Omítelo para solicitudes pendientes de cualquier repositorio.

pool cadena (opcional)

Filtra por nombre del pool. Coincidencia exacta que distingue entre mayúsculas y minúsculas con la etiqueta pool de la solicitud. Omítelo para listar solicitudes de todos los pools del equipo.

Campos de respuesta

requests array

Solicitudes pendientes. Cada entrada incluye:
  • id cadena — ID de solicitud pendiente o de agente (pásalo a Reclamar o Liberar una reclamación como id).
  • userId entero — ID de usuario de Cursor que creó la solicitud.
  • userEmail cadena (opcional) — Correo electrónico del usuario que realizó la solicitud, cuando esté disponible. Úsalo para seleccionar capacidad asignada al usuario sin necesidad de otra consulta.
  • serviceAccountId cadena (opcional) — Cuenta de servicio asociada a la solicitud, cuando exista.
  • repoOwner, repoName, repoUrl cadena (opcional) — Metadatos del repositorio cuando la solicitud se dirige a un repositorio. Se omiten para solicitudes de pools de cualquier repositorio.
  • labels array — Etiquetas de la solicitud como pares { key, value } (incluye repo= y pool= cuando se especifican).
  • createdAtMs entero — Hora de creación de la solicitud en milisegundos Unix.
  • claimedWorkerId cadena (opcional) — Presente en entradas reclamadas pero sin conexión: la solicitud ha sido reclamada por este worker, que actualmente está sin conexión. Inicia un worker con este ID (CURSOR_AGENT_WORKER_ID) para reanudar el agente en su máquina.
  • wakeTimeoutMs entero (opcional) — Milisegundos restantes en la ventana de reconexión de una entrada reclamada pero sin conexión. Cuando vence la ventana, la reclamación caduca y la solicitud se vuelve a anunciar como una entrada sin reclamar.

nextPageToken cadena (opcional)

Cursor de paginación. Se omite cuando no hay más páginas. Para medir la longitud de la cola, pagina hasta el final y cuenta las solicitudes.

streamCursor cadena

Posición opaca para reanudar Supervisar solicitudes pendientes del pool. Cada página de un mismo listado lógico repite el mismo streamCursor; inicia la supervisión desde él después de terminar de paginar. Caduca cinco minutos después de la lista que lo emitió.
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:"

Respuesta:

{  "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"}

repoUrl omite las credenciales incluidas en la URL cuando la URL original del repositorio contiene información de usuario.

Observar solicitudes pendientes del pool

GET/v0/private-workers/pending-requests/stream

Transmita eventos del ciclo de vida de las solicitudes pendientes mediante Server-Sent Events (SSE) para que los controladores puedan reaccionar a cambios en la cola sin tener que sondearla.

Este endpoint requiere una clave de API de cuenta de servicio. Los controladores primero listan y luego observan: llame a Listar solicitudes pendientes del pool para crear su vista de la cola, conserve el streamCursor de la respuesta y, a continuación, abra la observación desde esa posición exacta. Use los mismos filtros de repository y pool para la lista y la observación; los cursores están vinculados a los filtros que los emitieron.

Parámetros de consulta

cursor string (obligatorio)

El streamCursor de una respuesta de lista o el id: de SSE del último evento procesado. Al reconectarse, un EventSource nativo reenvía ese id como encabezado Last-Event-ID, que tiene prioridad sobre el parámetro de consulta.

repository string (opcional)

Tiene la misma semántica que Listar solicitudes pendientes del pool. Obligatorio para las claves de API de cuentas de servicio con ámbito de repositorio. No se aceptan parámetros de paginación en el flujo.

pool string (opcional)

Observe solo los eventos de este pool. Coincidencia exacta, con distinción entre mayúsculas y minúsculas, con la etiqueta pool de la solicitud. Debe coincidir con el filtro usado en la lista que emitió el cursor. Omítalo para observar todos los pools del equipo.

Eventos

La observación reproduce las transiciones retenidas posteriores al cursor y luego sigue los eventos en tiempo real. El id: de SSE de cada evento es el cursor desde el que reanudar si se pierde la conexión.

  • created evento — Una solicitud entró en la cola, incluida una solicitud reclamada pero sin conexión cuya ventana de reconexión venció y cuya reclamación expiró. Payload: el mismo objeto de solicitud que Listar solicitudes pendientes del pool.
  • claimed evento — Un worker reclamó la solicitud o un worker sin conexión se reconectó y reanudó la solicitud que había reclamado. Payload: { id }.
  • claimed_offline evento — Llegó una actualización para una solicitud cuyo worker reclamado está sin conexión. Payload: el mismo objeto de solicitud que Listar solicitudes pendientes del pool, incluidos claimedWorkerId y wakeTimeoutMs. Reactive la máquina antes de que venza la ventana; de lo contrario, la reclamación vence y la solicitud se vuelve a anunciar con un nuevo evento created.
  • expired evento — La solicitud salió de la cola sin ser reclamada. Payload: { id }.
  • heartbeat evento — Punto de control del cursor sin cambio de estado, enviado aproximadamente cada 20 segundos en un flujo sin actividad. Payload: {}. Los heartbeats avanzan la posición de reanudación de una observación inactiva, pero no prolongan la vigencia del cursor.

Vigencia del cursor

Cada cursor de una cadena de observación vence cinco minutos después de la lista que lo emitió. Los heartbeats y las reconexiones no prolongan su vigencia. Cuando el cursor vence o la ventana de eventos retenidos ya no lo incluye, el endpoint devuelve HTTP 410 Gone con {"code": "cursor_expired"}: vuelva a listar y observe desde el nuevo streamCursor. Esto es normal, no una ruta de error. Vuelva a listar proactivamente cada cinco minutos con variación aleatoria, en lugar de esperar al 410, para evitar que una flota de controladores sincronice sus llamadas de lista.

Garantías de entrega

La entrega se realiza según el mejor esfuerzo y la lista es la fuente de verdad. Los eventos se publican tras confirmar cada transición, con reintentos, pero un fallo poco frecuente puede hacer que se pierda uno, y un evento perdido nunca se vuelve a entregar. Entre listas, trate los eventos como indicaciones de baja latencia: aplíquelos de forma idempotente (inserte o actualice solicitudes created y claimed_offline, elimine solicitudes claimed y expired por id) y deje que la siguiente lista corrija cualquier discrepancia. Un evento claimed para una solicitud que nunca vio no tiene efecto. Las reclamaciones siguen siendo atómicas del lado del servidor, independientemente de su vista local.

No persista los cursores. Una cuenta de servicio puede mantener como máximo cuatro flujos simultáneos; use un flujo por controlador y distribúyalo localmente.

curl --request GET --no-buffer \  --url "https://api.cursor.com/v0/private-workers/pending-requests/stream?cursor=$STREAM_CURSOR" \  --header 'Accept: text/event-stream' \  -u "$CURSOR_API_KEY:"

Flujo de ejemplo:

: connected

event: heartbeat
id: djQuY3Vyc29yLWNoZWNrcG9pbnQ
data: {}

event: created
id: djQuY3Vyc29yLWFmdGVyLWNyZWF0ZWQ
data: {"id":"bc-00000000-0000-0000-0000-000000000002","userId":321,"userEmail":"owner@acme.example","repoOwner":"acme","repoName":"payments-service","repoUrl":"https://github.com/acme/payments-service","labels":[{"key":"pool","value":"gpu"}],"createdAtMs":1737306880000}

event: claimed
id: djQuY3Vyc29yLWFmdGVyLWNsYWltZWQ
data: {"id":"bc-00000000-0000-0000-0000-000000000002"}

El bucle del controlador:

  1. Enumera las solicitudes pendientes hasta que se complete y reemplaza tu vista local con el resultado. Conserva el streamCursor de la respuesta.
  2. Abre la escucha con ?cursor=<streamCursor> y aplica los eventos a tu vista local. Haz un seguimiento del último id: de evento que procesaste.
  3. Al desconectarte, vuelve a conectarte con el id del evento más reciente como ?cursor=, o usa un EventSource nativo, que lo reenvía automáticamente como Last-Event-ID.
  4. Si recibes HTTP 410 Gone, vuelve al paso 1 y vuelve a enumerar las solicitudes.

Reclamar una solicitud pendiente

POST/v0/private-workers/claim

Reserve una solicitud pendiente del pool para un worker específico antes de iniciarlo. Los controladores usan este endpoint para asignar trabajo de forma atómica entre réplicas: leen las solicitudes pendientes, reclaman una y, luego, inician un worker con un ID de worker estable que coincida con la reclamación.

Se rechaza una segunda reclamación mientras exista una reclamación activa. Primero libere una reclamación y, luego, reclame un nuevo workerId.

Este endpoint requiere una clave de API de cuenta de servicio.

Cuerpo de la solicitud

id string (obligatorio)

ID de la solicitud pendiente. Es el mismo valor que id en Listar solicitudes pendientes del pool.

workerId string (obligatorio)

ID de worker que se reservará para la solicitud. Inicie el worker con el mismo ID mediante CURSOR_AGENT_WORKER_ID (o la opción oculta --worker-id) para que el bridge registre la identidad reclamada.
curl --request POST \  --url "https://api.cursor.com/v0/private-workers/claim" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "id": "bc-00000000-0000-0000-0000-000000000002",    "workerId": "pw_123"  }'

Respuesta:

{  "id": "bc-00000000-0000-0000-0000-000000000002",  "workerId": "pw_123"}

Tras reclamarla correctamente, inicie el worker con el ID reservado:

export CURSOR_API_KEY="your-service-account-api-key"export CURSOR_AGENT_WORKER_ID="pw_123"agent worker --pool gpu --worker-dir /workspace start

Liberar una reclamación

POST/v0/private-workers/claims/{id}/release

Elimina la reclamación de larga duración que vincula un agente a un worker autohospedado. Tras liberarla, Cursor deja de priorizar esa máquina para el agente.

La reclamación es una sugerencia de enrutamiento, no el estado de un proceso en ejecución. Al liberarla, no se comprueba si el worker está conectado. Una solicitud de seguimiento en espera vuelve a la cola del pool en el siguiente punto de programación. Un worker conectado finaliza su interacción actual sin interrupciones. Un worker de reemplazo puede reclamar el mismo agente inmediatamente después de liberarla.

Se rechaza una segunda Reclamar una solicitud pendiente mientras exista una reclamación activa. Libera primero la reclamación y, después, reclama un nuevo workerId.

--idle-release-timeout (variable de entorno CURSOR_WORKER_IDLE_RELEASE_TIMEOUT) hace que la CLI del worker se cierre tras un periodo de inactividad. Este endpoint solo elimina la reclamación de enrutamiento.

Este endpoint requiere una clave de API de cuenta de servicio.

Parámetros de ruta

id string

ID de la solicitud pendiente o del agente. Es el mismo valor que id en Reclamar una solicitud pendiente. Sin cuerpo de solicitud.
curl --request POST \  --url "https://api.cursor.com/v0/private-workers/claims/bc-00000000-0000-0000-0000-000000000002/release" \  -u "$CURSOR_API_KEY:"

Respuesta:

{  "id": "bc-00000000-0000-0000-0000-000000000002",  "workerId": "pw_123"}

HTTP 404 significa que no hay ninguna reclamación activa: ya se liberó, caducó o fue adoptada. No reintentes tras recibir un 404.

Endpoints de metadatos

Información de la clave de API

GET/v1/me

Obtiene información sobre la clave de API usada para la autenticación.

Campos de respuesta

apiKeyName string

Nombre para mostrar de la clave de API.

createdAt string

Fecha de creación de la clave de API (ISO 8601).

userId entero (claves con alcance de usuario)

ID numérico del usuario de Cursor propietario de la clave de API. Se omite en las claves de cuenta de servicio / Team API キー, que no están vinculadas a un usuario específico.

userEmail string (claves con alcance de usuario)

Dirección de correo electrónico del propietario de la clave de API.

userFirstName, userLastName string (claves con alcance de usuario)

Nombre y apellidos del propietario de la clave de API, cuando están disponibles.
curl --request GET \  --url https://api.cursor.com/v1/me \  -u YOUR_API_KEY:

Respuesta (clave con alcance de usuario):

{  "apiKeyName": "Production API Key",  "userId": 42,  "createdAt": "2026-04-13T18:30:00.000Z",  "userEmail": "developer@example.com",  "userFirstName": "Alex",  "userLastName": "Rivera"}

Respuesta (clave de cuenta de servicio):

{  "apiKeyName": "Production Service Account",  "createdAt": "2026-04-13T18:30:00.000Z"}

Listar modelos

GET/v1/models

Devuelve los modelos recomendados que puedes pasar al campo model.id en Crear un agente, junto con los parámetros y las variantes que acepta cada modelo. Los parámetros del modelo usan la misma forma de model.params que TypeScript SDK ModelSelection.

Campos de respuesta

Cada elemento de items describe un modelo:

id string

Pasa este valor como model.id al crear un agente.

displayName string

Nombre legible que se muestra en la interfaz de Cursor.

description string (opcional)

Descripción breve del modelo.

aliases array (opcional)

IDs alternativos que apuntan al mismo modelo (por ejemplo, composer-latest).

parameters array (opcional)

Definiciones de parámetros por modelo. Cada entrada tiene un id, un displayName opcional y un array values con las entradas permitidas { value, displayName? }. Úsalas para completar model.params en la solicitud de creación.

variants array (opcional)

Combinaciones concretas de id + params que acepta el modelo. Cada entrada tiene un array params (que puede estar vacío), un displayName, una description opcional y una marca isDefault opcional.
curl --request GET \  --url https://api.cursor.com/v1/models \  -u YOUR_API_KEY:

Respuesta:

{  "items": [    {      "id": "composer-2",      "displayName": "Composer 2",      "aliases": ["composer-latest", "composer"],      "parameters": [        {          "id": "fast",          "displayName": "Fast",          "values": [            { "value": "false" },            { "value": "true", "displayName": "Fast" }          ]        }      ],      "variants": [        {          "params": [{ "id": "fast", "value": "true" }],          "displayName": "Composer 2",          "isDefault": true        },        {          "params": [{ "id": "fast", "value": "false" }],          "displayName": "Composer 2"        }      ]    },    {      "id": "claude-4.6-sonnet-thinking",      "displayName": "Claude 4.6 Sonnet (Thinking)",      "variants": [        {          "params": [],          "displayName": "Claude 4.6 Sonnet (Thinking)",          "isDefault": true        }      ]    }  ]}

Listar repositorios de GitHub

GET/v1/repositories

Lista los repositorios de GitHub a los que puede acceder el usuario autenticado mediante la instalación de la aplicación de GitHub de Cursor.

curl --request GET \  --url https://api.cursor.com/v1/repositories \  -u YOUR_API_KEY:

Respuesta:

{  "items": [    {      "url": "https://github.com/your-org/your-repo"    }  ]}