Visão geral das APIs do Cursor

O Cursor oferece várias APIs para acessar programaticamente os dados da sua equipe, agentes de programação com IA e análises.

APIs disponíveis

A Cloud Agents API e os SDKs executam fluxos de trabalho de agentes do Cursor (contexto do espaço de trabalho, ferramentas, comandos e edições). Eles não são uma API independente de inferência de modelos nem de conclusões de chat. O Cursor Router seleciona modelos para essas execuções de agentes quando você usa Auto / auto-smart; consulte Router no TypeScript SDK ou Python SDK.

Autenticação

Todas as APIs do Cursor aceitam autenticação básica. A API Cloud Agents também aceita tokens Bearer — escolha a opção mais prática para seu cliente HTTP.

Autenticação básica

Use sua chave de API como nome de usuário na autenticação básica (deixe o campo de senha em branco):

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

Ou defina diretamente o cabeçalho Authorization:

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

Autenticação Bearer (Cloud Agents API)

A Cloud Agents API também aceita cabeçalhos Authorization: Bearer <key>. Ambos os métodos funcionam da mesma forma — use o que for mais fácil com seu cliente HTTP:

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

Como criar chaves de API

Os administradores da equipe podem criar e gerenciar chaves de API na página Chaves de API do dashboard.

API de administração e API de Rastreamento de Código com IA

1. Acesse cursor.com/dashboard → Chaves de API
2. Clique em Nova chave de API
3. Dê à sua chave um nome descritivo (por exemplo, "Integração com o dashboard de uso")
4. Copie a chave gerada imediatamente. Ela não será exibida novamente

Formato da chave: crsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Escopo obrigatório: admin:*

Analytics API

Gere uma chave de API no dashboard do Cursor → Chaves de API.

Cloud Agents API

Crie uma chave de API de usuário no Dashboard do Cursor → Chaves de API ou use uma chave de API de conta de serviço nas configurações da equipe.

Limites de taxa

Todas as APIs implementam limitação de taxa para garantir o uso justo e a estabilidade do sistema. Os limites de taxa são aplicados por equipe e redefinidos a cada minuto.

Limites de taxa por API

Resposta de limite de taxa

Quando você exceder o limite de taxa, receberá uma resposta 429 Too Many Requests:

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

Cache

Diversas APIs oferecem suporte ao cache HTTP com ETags para reduzir o uso de largura de banda e melhorar o desempenho.

APIs compatíveis

• Analytics API: Todos os endpoints (em nível de equipe e por usuário) oferecem suporte a cache HTTP
• API de Rastreamento de Código com IA: Os endpoints oferecem suporte a cache HTTP

Como o cache funciona

1. Solicitação inicial: Faça uma solicitação a qualquer endpoint compatível
2. A resposta inclui ETag: A API retorna um cabeçalho ETag na resposta
3. Solicitações subsequentes: Inclua o valor de ETag em um cabeçalho If-None-Match
4. 304 Not Modified: Se os dados não tiverem sido alterados, você receberá uma resposta 304 Not Modified sem corpo

Exemplo

# Solicitação inicialcurl -X GET "https://api.cursor.com/analytics/team/dau" \  -H "Authorization: Bearer YOUR_API_KEY" \  -D headers.txt# A resposta inclui: ETag: "abc123xyz"# Solicitação subsequente com ETagcurl -X GET "https://api.cursor.com/analytics/team/dau" \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "If-None-Match: \"abc123xyz\""# Retorna 304 Not Modified se os dados não tiverem sido alterados

Duração do cache

• Duração do cache: 15 minutos (Cache-Control: public, max-age=900)
• As respostas incluem um cabeçalho ETag
• Inclua o cabeçalho If-None-Match em solicitações subsequentes para receber 304 Not Modified quando os dados não forem alterados

Benefícios

• Reduz o uso de largura de banda: as respostas 304 não têm corpo
• Respostas mais rápidas: evita o processamento de dados inalterados
• Compatível com limites de taxa: as respostas 304 não contam para os limites de taxa
• Melhor desempenho: especialmente útil para endpoints consultados com frequência

Melhores práticas

1. Implemente o Exponential Backoff

Ao receber uma resposta 429, aguarde antes de tentar novamente, com atrasos crescentes:

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:            # Backoff exponencial: 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. Distribua as solicitações ao longo do tempo

Distribua as chamadas à API ao longo do tempo, em vez de fazer solicitações em rajadas:

• Programe jobs em lote para serem executados em intervalos diferentes
• Adicione intervalos entre as solicitações ao processar grandes conjuntos de dados
• Use sistemas de filas para suavizar picos de tráfego

3. Aproveite o cache

Para a Analytics API e a API de Rastreamento de Código com IA:

Essas APIs oferecem suporte a cache HTTP com ETags. Consulte a seção Cache acima para saber como usar ETags a fim de reduzir o uso de largura de banda e evitar solicitações desnecessárias.

Principais benefícios:

• Reduz o uso de largura de banda
• Respostas mais rápidas quando os dados não mudaram
• Não é contabilizado nos limites de taxa (para respostas 304)

Use atalhos de data (7d, 30d) em vez de timestamps para melhor suporte a cache na Analytics API.

4. Monitore seu uso

Acompanhe os padrões das suas solicitações para ficar dentro dos limites:

• Registre os timestamps das chamadas de API e os códigos de resposta
• Configure alertas para respostas 429
• Monitore as tendências de uso diárias e semanais
• Ajuste os intervalos de polling conforme as necessidades reais

5. Use operações em lote com sabedoria

Para endpoints com paginação:

• Use tamanhos de página adequados para obter mais dados por solicitação
• Para endpoints por usuário da Analytics API: use o parâmetro users para filtrar usuários específicos
• Para grandes extrações de dados: use endpoints CSV quando disponíveis (eles transmitem dados com eficiência)

6. Faça polling em intervalos adequados

Evite fazer polling excessivo em endpoints atualizados com pouca frequência:

• API de administração /teams/daily-usage-data: Faça polling no máximo uma vez por hora (dados agregados por hora)
• API de administração /teams/filtered-usage-events: Faça polling no máximo uma vez por hora (dados agregados por hora)
• API de administração /organizations/pooled-usage: Faça polling no máximo uma vez por hora (dados agregados por hora)
• API de administração /organizations/filtered-usage-events: Faça polling no máximo uma vez por hora (dados agregados por hora)
• Analytics API: Use atalhos de data (7d, 30d) para melhor suporte a cache
• API de Rastreamento de Código com IA: Os dados são ingeridos quase em tempo real, mas fazer polling a cada poucos minutos é suficiente

7. Lide com os erros de forma adequada

Implemente um tratamento de erros adequado para todas as chamadas de 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 taxa atingido - implementar backoff      throw new Error('Rate limit exceeded');    }        if (response.status === 401) {      // Chave de API inválida      throw new Error('Authentication failed');    }        if (response.status === 403) {      // Permissões 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;  }}

Respostas de erro comuns

Todas as APIs usam códigos de status HTTP padrão:

400 Solicitação inválida

Os parâmetros da solicitação são inválidos ou faltam campos obrigatórios.

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

401 Não autorizado

Chave de API inválida ou ausente.

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

403 Proibido

Chave de API válida, mas sem permissões suficientes (por exemplo, funcionalidades Enterprise em um plano que não é Enterprise).

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

404 Não encontrado

O recurso solicitado não existe.

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

429 Solicitações em Excesso

Limite de taxa excedido. Implemente backoff exponencial.

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

500 Erro interno do servidor

Erro no servidor. Entre em contato com o suporte se o problema persistir.

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