Descripción general de las APIs de Cursor

Cursor ofrece varias APIs para acceder de forma programática a los datos de tu equipo, a agentes de codificación con IA y a analíticas.

APIs disponibles

La API de Cloud Agents y los SDK ejecutan flujos de trabajo de agentes de Cursor (contexto del espacio de trabajo, herramientas, comandos y ediciones). No son una API independiente de inferencia de modelos ni de completions de chat. Cursor Router selecciona modelos para esas ejecuciones de agentes cuando usas Auto / auto-smart; consulta Router en el SDK de TypeScript o el SDK de Python.

Autenticación

Las API de administración, Analytics, Seguimiento de Código con IA y Bugbot aceptan autenticación básica. La API de Cloud Agents acepta autenticación básica o Bearer. La API de Origin usa credenciales Bearer mediante la Origin CLI o una Origin App.

Autenticación básica

Usa tu clave de API como nombre de usuario en la autenticación básica (deja la contraseña en blanco):

curl https://api.cursor.com/teams/members \  -u TU_API_KEY:

O establece el encabezado Authorization directamente:

Authorization: Basic {base64_encode('TU_CLAVE_API:')}

Autenticación Bearer (API de Cloud Agents)

La API de Cloud Agents también acepta encabezados Authorization: Bearer <key>. Ambos métodos funcionan igual; usa el que te resulte más fácil con tu cliente HTTP.

curl https://api.cursor.com/v1/me \  -H "Authorization: Bearer YOUR_API_KEY"

Creación de claves de API

Los administradores del equipo pueden crear y gestionar claves de API desde la página de Claves de API del Panel de control.

API de administración y API de Seguimiento de Código con IA

1. Ve a cursor.com/dashboard → Claves de API
2. Haz clic en Nueva clave de API
3. Asigna a tu clave un nombre descriptivo (p. ej., "Integración del panel de control de consumo")
4. Copia la clave generada de inmediato. No volverás a verla

Formato de la clave: crsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Alcance requerido: admin:*

Analytics API

Genera una clave de API desde el Panel de control de Cursor → Claves de API.

API de Cloud Agents

Crea una clave de API de usuario desde Cursor Dashboard → API Keys, o usa una clave de API de cuenta de servicio desde los ajustes del equipo.

API de Origin

Para solicitudes autenticadas como usuario, inicia sesión con la CLI de Origin o proporciónale una clave de API de usuario personal. La CLI intercambia la clave por un token de acceso de corta duración antes de llamar a Origin. Las claves de API de administrador de equipo con el scope admin:* no sirven para autenticarse en Origin. Las aplicaciones usan JWT de aplicación y tokens de acceso de instalación. Consulta Autenticación de la API de Origin.

Límites de uso

Todas las API implementan límites de uso para garantizar un uso equitativo y la estabilidad del sistema. Los límites se aplican por usuario autenticado, equipo u organización, y la mayoría se limitan a un único endpoint. A menos que un endpoint documente un límite distinto, el valor predeterminado es de 20 solicitudes por minuto.

Límites de uso por API

Respuesta por límite de uso

Cuando superes el límite de uso, recibirás una respuesta 429 Too Many Requests. Las respuestas de la API de Admin y de la API de organización incluyen Retry-After: 60 y este cuerpo:

{  "code": "error",  "message": "Rate limit exceeded"}

Caché

Varias API admiten el almacenamiento en caché HTTP con ETags para reducir el uso de ancho de banda y mejorar el rendimiento.

APIs compatibles

• Analytics API: Todos los endpoints (tanto a nivel de equipo como por usuario) admiten almacenamiento en caché HTTP
• AI Code Tracking API: Los endpoints admiten almacenamiento en caché HTTP

Cómo funciona la caché

1. Solicitud inicial: Realiza una solicitud a cualquier endpoint compatible
2. La respuesta incluye ETag: La API devuelve un encabezado ETag en la respuesta
3. Solicitudes posteriores: Incluye el valor de ETag en el encabezado If-None-Match
4. 304 Not Modified: Si los datos no han cambiado, recibirás una respuesta 304 Not Modified sin cuerpo

Ejemplo

# Solicitud inicialcurl -X GET "https://api.cursor.com/analytics/team/dau" \  -H "Authorization: Bearer YOUR_API_KEY" \  -D headers.txt# La respuesta incluye: ETag: "abc123xyz"# Solicitud posterior con ETagcurl -X GET "https://api.cursor.com/analytics/team/dau" \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "If-None-Match: \"abc123xyz\""# Devuelve 304 Not Modified si los datos no han cambiado

Duración de la caché

• Duración de la caché: 15 minutos (Cache-Control: public, max-age=900)
• Las respuestas incluyen un encabezado ETag
• Incluye el encabezado If-None-Match en solicitudes posteriores para recibir un 304 Not Modified cuando los datos no hayan cambiado

Beneficios

• Reduce el uso de ancho de banda: las respuestas 304 no incluyen cuerpo
• Respuestas más rápidas: evita procesar datos que no cambiaron
• Compatible con límites de solicitudes: las respuestas 304 no cuentan para los límites
• Mejor rendimiento: especialmente útil para endpoints consultados con frecuencia

Buenas prácticas

1. Implementar backoff exponencial

Cuando recibas una respuesta 429, espera antes de reintentar con demoras crecientes:

import timeimport requestsdef make_request_with_backoff(url, headers, max_retries=5):    for attempt in range(max_retries):        response = requests.get(url, headers=headers)                if response.status_code == 429:            # Exponential backoff: 1s, 2s, 4s, 8s, 16s            wait_time = 2 ** attempt            print(f"Rate limited. Waiting {wait_time}s before retry...")            time.sleep(wait_time)            continue                    return response        raise Exception("Max retries exceeded")

2. Distribuye las solicitudes en el tiempo

Distribuye las llamadas a la API en el tiempo en lugar de hacer ráfagas de solicitudes:

• Programa tareas por lotes para que se ejecuten en distintos intervalos
• Añade esperas entre solicitudes al procesar conjuntos de datos grandes
• Usa sistemas de colas para amortiguar los picos de tráfico

3. Aprovecha la caché

Para Analytics API y AI Code Tracking API:

Estas API admiten caché HTTP con ETags. Consulta la sección Caching anterior para ver detalles sobre cómo usar ETags para reducir el uso de ancho de banda y evitar solicitudes innecesarias.

Beneficios clave:

• Reduce el uso de ancho de banda
• Respuestas más rápidas cuando los datos no han cambiado
• No cuenta para los límites de tasa (para respuestas 304)

Usa accesos directos de fecha (7d, 30d) en lugar de marcas de tiempo para mejorar la compatibilidad con la caché en Analytics API.

4. Supervisa tu uso

Controla tus patrones de solicitudes para mantenerte dentro de los límites:

• Registra las marcas de tiempo y los códigos de respuesta de las llamadas a la API
• Configura alertas para las respuestas 429
• Supervisa las tendencias de uso diarias/semanales
• Ajusta los intervalos de sondeo según las necesidades reales

5. Agrupa con criterio

Para endpoints con paginación:

• Usa tamaños de página adecuados para obtener más datos por solicitud
• Para endpoints de Analytics API por usuario: usa el parámetro users para filtrar usuarios específicos
• Para extracciones de grandes volúmenes de datos: usa endpoints CSV cuando estén disponibles (transmiten datos de forma eficiente)

6. Haz sondeos a intervalos adecuados

No consultes en exceso los endpoints que se actualizan con poca frecuencia:

• Admin API /teams/daily-usage-data: Consulta como máximo una vez por hora (datos agregados por hora)
• Admin API /teams/filtered-usage-events: Consulta como máximo una vez por hora (datos agregados por hora)
• Admin API /organizations/pooled-usage: Consulta como máximo una vez por hora (datos agregados por hora)
• Admin API /organizations/filtered-usage-events: Consulta como máximo una vez por hora (datos agregados por hora)
• Analytics API: Usa atajos de fecha (7d, 30d) para mejorar la compatibilidad con la caché
• API de Seguimiento de Código con IA: Los datos se ingieren casi en tiempo real, pero consultar cada pocos minutos es suficiente

7. Gestiona los errores correctamente

Implementa un manejo de errores adecuado para todas las llamadas a la API:

async function fetchAnalytics(endpoint) {  try {    const response = await fetch(`https://api.cursor.com${endpoint}`, {      headers: {        'Authorization': `Basic ${btoa(API_KEY + ':')}`      }    });        if (response.status === 429) {      // Rate limited - implement backoff      throw new Error('Rate limit exceeded');    }        if (response.status === 401) {      // Invalid API key      throw new Error('Authentication failed');    }        if (response.status === 403) {      // Permisos insuficientes      throw new Error('Enterprise access required');    }        if (!response.ok) {      throw new Error(`API error: ${response.status}`);    }        return await response.json();  } catch (error) {    console.error('API request failed:', error);    throw error;  }}

Respuestas de errores comunes

Todas las API usan códigos de estado HTTP estándar:

400 Solicitud inválida

Los parámetros de la solicitud no son válidos o faltan campos obligatorios.

{  "error": "Solicitud incorrecta",  "message": "Algunos usuarios no pertenecen al equipo"}

401 No autorizado

Clave de API no válida o ausente.

{  "error": "No autorizado",  "message": "Clave de API inválida"}

403 Prohibido

La clave de API es válida, pero no tiene permisos suficientes (p. ej., funcionalidades exclusivas de Enterprise en un plan que no es Enterprise).

{  "error": "Forbidden",  "message": "Enterprise access required"}

404 No encontrado

El recurso solicitado no existe.

{  "error": "No encontrado",  "message": "Recurso no encontrado"}

429 Demasiadas solicitudes

Se superó el límite de peticiones. Implementa un backoff exponencial.

{  "error": "Demasiadas solicitudes",  "message": "Límite de velocidad excedido. Inténtalo de nuevo más tarde."}

500 Error interno del servidor

Error en el servidor. Contacta con soporte si persiste.

{  "error": "Error interno del servidor",  "message": "Ocurrió un error inesperado"}