Présentation des API Cursor

Cursor propose plusieurs API permettant d’accéder par programmation aux données de votre équipe, aux agents de programmation basés sur l’IA et aux analyses.

API disponibles

L’API des Cloud Agents et les SDK exécutent des flux de travail d’agents Cursor (contexte de l’espace de travail, outils, commandes et modifications). Ils ne constituent pas une API autonome d’inférence de modèles ou de complétions de chat. Cursor Router sélectionne les modèles pour ces exécutions d’agents lorsque vous utilisez Auto / auto-smart ; consultez Router dans le TypeScript SDK ou Python SDK.

Authentification

Toutes les API Cursor acceptent l’authentification de base. L’API des Cloud Agents accepte également les jetons Bearer ; utilisez la méthode la plus simple pour votre client HTTP.

Authentification de base

Utilisez votre clé API comme nom d’utilisateur pour l’authentification de base (laissez le mot de passe vide) :

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

Ou définissez directement l’en-tête Authorization :

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

Authentification Bearer (API des Cloud Agents)

L’API des Cloud Agents accepte également les en-têtes Authorization: Bearer <key>. Les deux méthodes fonctionnent de manière identique : utilisez celle qui convient le mieux à votre client HTTP.

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

Création de clés API

Les administrateurs de l’équipe peuvent créer et gérer des clés API depuis la page Clés API du tableau de bord.

API d'administration & AI Code Tracking API

1. Accédez à cursor.com/dashboard → clé API
2. Cliquez sur New API Key
3. Donnez à votre clé un nom explicite (par ex. « Intégration du tableau de bord d’usage »)
4. Copiez immédiatement la clé générée. Vous ne pourrez plus la voir

Format de la clé : crsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Portée requise : admin:*

API Analytics

Générez une clé API depuis Cursor Dashboard → clé API.

API des Cloud Agents

Créez une clé API utilisateur dans Cursor Dashboard → clé API, ou utilisez une clé API de compte de service dans les paramètres de l’équipe.

Limites de débit

Toutes les API appliquent une limitation de débit afin de garantir une utilisation équitable et la stabilité du système. Les limites de débit sont appliquées par équipe et réinitialisées chaque minute.

Limites de débit par API

Réponse en cas de dépassement de la limite de débit

Lorsque vous dépassez la limite de débit, vous recevez une réponse 429 Too Many Requests :

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

Mise en cache

Plusieurs API prennent en charge la mise en cache HTTP avec des ETags afin de réduire l’utilisation de la bande passante et d’améliorer les performances.

API prises en charge

• Analytics API : Tous les endpoints (au niveau de l’équipe et par utilisateur) prennent en charge la mise en cache HTTP
• AI Code Tracking API : Les endpoints prennent en charge la mise en cache HTTP

Fonctionnement de la mise en cache

1. Requête initiale : envoyez une requête à n’importe quel endpoint pris en charge
2. La réponse inclut un ETag : l’API renvoie un en-tête ETag dans la réponse
3. Requêtes suivantes : incluez la valeur ETag dans un en-tête If-None-Match
4. 304 Not Modified : si les données n’ont pas changé, vous recevrez une réponse 304 Not Modified sans corps

Exemple

# Requête initialecurl -X GET "https://api.cursor.com/analytics/team/dau" \  -H "Authorization: Bearer YOUR_API_KEY" \  -D headers.txt# La réponse contient : ETag: "abc123xyz"# Requête suivante avec l’ETagcurl -X GET "https://api.cursor.com/analytics/team/dau" \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "If-None-Match: \"abc123xyz\""# Renvoie 304 Not Modified si les données n’ont pas changé

Durée de mise en cache

• Durée de mise en cache : 15 minutes (Cache-Control: public, max-age=900)
• Les réponses incluent un en-tête ETag
• Incluez l’en-tête If-None-Match dans les requêtes ultérieures pour recevoir un code 304 Not Modified lorsque les données n’ont pas changé

Avantages

• Réduit l'utilisation de la bande passante : les réponses 304 ne contiennent aucun corps de réponse
• Réponses plus rapides : évite le traitement de données inchangées
• Préserve les limites de débit : les réponses 304 ne sont pas comptabilisées dans les limites de débit
• Meilleures performances : particulièrement utile pour les endpoints interrogés fréquemment

Bonnes pratiques

1. Mettre en place un backoff exponentiel

Lorsque vous recevez une réponse 429, attendez avant de réessayer, en augmentant progressivement le délai :

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:            # Délai d’attente exponentiel : 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. Répartir les requêtes dans le temps

Répartissez vos appels d’API dans le temps plutôt que d’envoyer des requêtes en rafale :

• Planifiez l’exécution des tâches par lots à des intervalles différents
• Ajoutez des délais entre les requêtes lors du traitement de jeux de données volumineux
• Utilisez des systèmes de mise en file d’attente pour lisser les pics de trafic

3. Tirer parti de la mise en cache

Pour Analytics API et AI Code Tracking API :

Ces API prennent en charge la mise en cache HTTP avec des ETags. Consultez la section Mise en cache ci-dessus pour savoir comment utiliser les ETags afin de réduire l’utilisation de la bande passante et d’éviter les requêtes inutiles.

Principaux avantages :

• Réduction de l’utilisation de la bande passante
• Réponses plus rapides lorsque les données n’ont pas changé
• Non décompté des limites de débit (pour les réponses 304)

Utilisez les raccourcis de date (7d, 30d) plutôt que des horodatages pour une meilleure prise en charge de la mise en cache dans Analytics API.

4. Surveillez votre utilisation

Suivez vos habitudes de requêtes afin de respecter les limites :

• Enregistrez les horodatages des appels d’API et les codes de réponse
• Configurez des alertes pour les réponses 429
• Surveillez les tendances d’utilisation quotidiennes et hebdomadaires
• Ajustez les intervalles d’interrogation en fonction des besoins réels

5. Traitez les données par lots

Pour les endpoints avec pagination :

• Utilisez une taille de page adaptée pour obtenir plus de données par requête
• Pour les endpoints de l’API Analytics par utilisateur : utilisez le paramètre users pour filtrer des utilisateurs spécifiques
• Pour les extractions de gros volumes de données : utilisez les endpoints CSV lorsqu’ils sont disponibles (ils transmettent efficacement les données en continu)

6. Interrogez les API à des intervalles appropriés

N’interrogez pas trop fréquemment les endpoints rarement mis à jour :

• API d'administration /teams/daily-usage-data : au maximum une fois par heure (données agrégées chaque heure)
• API d'administration /teams/filtered-usage-events : au maximum une fois par heure (données agrégées chaque heure)
• API d'administration /organizations/pooled-usage : au maximum une fois par heure (données agrégées chaque heure)
• API d'administration /organizations/filtered-usage-events : au maximum une fois par heure (données agrégées chaque heure)
• Analytics API : utilisez les raccourcis de date (7d, 30d) pour bénéficier d'une meilleure mise en cache
• AI Code Tracking API : les données sont ingérées quasi en temps réel, mais une interrogation toutes les quelques minutes suffit

7. Gérez les erreurs avec élégance

Mettez en place une gestion des erreurs adaptée pour tous les appels d’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) {      // Limite de débit atteinte : mettez en place un backoff exponentiel      throw new Error('Rate limit exceeded');    }        if (response.status === 401) {      // Clé API non valide      throw new Error('Authentication failed');    }        if (response.status === 403) {      // Autorisations insuffisantes      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;  }}

Réponses d’erreur courantes

Toutes les API utilisent des codes d’état HTTP standard :

400 Requête incorrecte

Les paramètres de la requête sont invalides ou des champs obligatoires sont manquants.

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

401 Non autorisé

Clé API invalide ou manquante.

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

403 Interdit

Clé API valide, mais autorisations insuffisantes (p. ex., fonctionnalités Enterprise avec un forfait non Enterprise).

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

404 Introuvable

La ressource demandée n’existe pas.

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

429 Trop de requêtes

Limite de débit dépassée. Implémentez une stratégie de backoff exponentiel.

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

500 Erreur interne du serveur

Erreur côté serveur. Contactez le support si le problème persiste.

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