Descripción general de las APIs de Cursor

Cursor ofrece varias APIs para acceder mediante programación a los datos de tu equipo, los agentes de programación con IA y la analítica.

API 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 completado de chat. Cursor Router selecciona modelos para esas ejecuciones de agentes cuando usas Auto / auto-smart; consulta Cursor Router en el SDK de TypeScript o el SDK de Python.

Autenticación

Todas las API de Cursor admiten autenticación básica. La API de Cloud Agents también admite tokens Bearer; elige la opción que resulte más sencilla para tu cliente HTTP.

Autenticación básica

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

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

O establezca directamente el encabezado Authorization:

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

Autenticación con token Bearer (API de Cloud Agents)

La API de Cloud Agents también acepta encabezados Authorization: Bearer <key>. Ambos métodos funcionan de forma idéntica; usa el que resulte más sencillo 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 de equipo pueden crear y gestionar claves de API desde la página Claves de API del Panel de control.

Admin API 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 podrás volver a verla

Formato de la clave: crsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Alcance requerido: admin:*

Analytics API

Genera una clave de API en Cursor Panel de control → clave de API.

API de Cloud Agents

Crea una clave de API de usuario en Cursor Panel de control → clave de API o usa una clave de API de cuenta de servicio en los ajustes de equipo.

Límites de uso

Todas las API aplican límites de uso para garantizar un uso equitativo y la estabilidad del sistema. Los límites de uso se aplican por equipo y se restablecen cada minuto.

Límites de uso por API

Respuesta de límite de uso

Si superas el límite de uso, recibirás una respuesta 429 Too Many Requests:

{  "error": "Too Many Requests",  "message": "Rate limit exceeded. Please try again later."}

Almacenamiento en caché

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

API compatibles

• Analytics API: Todos los endpoints (tanto a nivel de equipo como por usuario) admiten el almacenamiento en caché HTTP
• API de Seguimiento de Código con IA: Los endpoints admiten el almacenamiento en caché HTTP

Cómo funciona el almacenamiento en caché

1. Solicitud inicial: Realiza una solicitud a cualquier endpoint compatible
2. La respuesta incluye un ETag: La API devuelve una cabecera ETag en la respuesta
3. Solicitudes posteriores: Incluye el valor de ETag en una cabecera If-None-Match
4. 304 Sin modificaciones: 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 una cabecera ETag
• Incluye la cabecera If-None-Match en las solicitudes posteriores para recibir un 304 Not Modified cuando los datos no hayan cambiado

Ventajas

• Reduce el consumo de ancho de banda: las respuestas 304 no incluyen cuerpo
• Respuestas más rápidas: evita procesar datos sin cambios
• No afecta a los límites de uso: las respuestas 304 no cuentan para los límites de uso
• Mejor rendimiento: especialmente útil para endpoints consultados con frecuencia

Mejores prácticas

1. Implementa el retroceso exponencial

Cuando recibas una respuesta 429, espera antes de volver a intentarlo, aumentando el tiempo de espera:

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:            # Espera exponencial: 1 s, 2 s, 4 s, 8 s, 16 s            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. Distribuya las solicitudes a lo largo del tiempo

Distribuya las llamadas a la API a lo largo del tiempo en lugar de hacer solicitudes en ráfaga:

• Programe trabajos en lote para que se ejecuten a intervalos distintos
• Añada pausas entre solicitudes al procesar conjuntos de datos grandes
• Use sistemas de colas para reducir los picos de tráfico

3. Aprovecha el almacenamiento en caché

Para Analytics API y la API de Seguimiento de Código con IA:

Estas API admiten almacenamiento en caché HTTP con ETags. Consulta la sección Almacenamiento en caché anterior para saber cómo usar ETags para reducir el consumo de ancho de banda y evitar solicitudes innecesarias.

Ventajas principales:

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

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

4. Supervisa tu consumo

Haz un seguimiento de tus patrones de solicitudes para mantenerte dentro de los límites:

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

5. Procesa en lote de forma eficiente

Para endpoints con paginación:

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

6. Consulta a intervalos adecuados

No consultes con demasiada frecuencia endpoints que se actualizan poco:

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

7. Gestiona los errores adecuadamente

Implementa un manejo adecuado de errores 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) {      // Límite de uso alcanzado: implementar espera progresiva      throw new Error('Rate limit exceeded');    }        if (response.status === 401) {      // Clave de API no válida      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 error habituales

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

400 Solicitud incorrecta

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

{  "error": "Bad Request",  "message": "Some users are not in the team"}

401 No autorizado

Clave de API no válida o no proporcionada.

{  "error": "Unauthorized",  "message": "Invalid API key"}

403 Prohibido

Clave de API válida, pero sin permisos suficientes (p. ej., funciones Enterprise en un plan que no es Enterprise).

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

404 No encontrado

El recurso solicitado no existe.

{  "error": "Not Found",  "message": "Resource not found"}

429 Demasiadas solicitudes

Se superó el límite de uso. Implemente un retroceso exponencial.

{  "error": "Too Many Requests",  "message": "Rate limit exceeded. Please try again later."}

500 Error interno del servidor

Error del servidor. Contacta con soporte si el problema persiste.

{  "error": "Internal Server Error",  "message": "An unexpected error occurred"}