《Cursor文檔》-Cursor API 概覽

Cursor 提供多個 API，可讓您以編程方式訪問團隊的數據、AI 驅動的編碼 agent 和使用分析數據。

可用 API¶

Cloud Agents API 和 SDK 會運行 Cursor agent 工作流 (包括工作區上下文、工具、命令和編輯) 。它們並非獨立的模型推理或聊天補全 API。使用 Auto / auto-smart 時，Cursor Router 會爲這些 agent 運行選擇模型；請參閱 TypeScript SDK 中的 Router 或 Python SDK。

身份驗證¶

所有 Cursor API 均支持 Basic 認證。Cloud Agents API 還支持 Bearer token——請選擇最方便您的 HTTP 客戶端使用的方式。

Basic 認證¶

使用 Basic 認證時，請將您的 API 密鑰作爲用戶名 (密碼留空) ：

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

或者直接設置 Authorization 請求頭：

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

Bearer 身份驗證 (Cloud Agents API)¶

Cloud Agents API 也支持 Authorization: Bearer <key> 請求頭。兩種方式的行爲完全相同——使用 HTTP 客戶端中更方便的一種即可：

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

創建 API 密鑰¶

團隊管理員可在儀表盤的“API 密鑰”頁面創建和管理 API 密鑰。

Admin API 和 AI Code Tracking API¶

1. 前往 cursor.com/dashboard → API Keys
2. 點擊 New API Key
3. 爲密鑰設置一個便於識別的名稱 (例如，“用量儀表盤集成”)
4. 立即複製生成的密鑰，之後將無法再次查看

密鑰格式：crsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

所需權限範圍：admin:*

Analytics API¶

在 Cursor 儀表盤 → API Keys 中生成 API 密鑰。

Cloud Agents API¶

在 Cursor 儀表盤 → API 密鑰中創建用戶 API 密鑰，或使用團隊設置中的服務賬戶 API 密鑰。

API 密鑰歸組織所有，所有管理員均可查看。創建者的賬戶狀態不會影響密鑰。

速率限制¶

所有 API 均實施速率限制，以確保使用公平及系統穩定。速率限制按團隊執行，每分鐘重置。

按 API 劃分的速率限制¶

速率限制響應¶

當請求超過速率限制時，你將收到 429 Too Many Requests 響應：

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

緩存¶

多個 API 支持通過 ETag 實現 HTTP 緩存，以減少帶寬用量並提升性能。

支持的 API¶

• Analytics API：所有端點 (團隊級和按用戶劃分的) 均支持 HTTP 緩存
• AI Code Tracking API：端點支持 HTTP 緩存

緩存工作原理¶

1. 初始請求：向任意受支持的端點發起請求
2. 響應包含 ETag：API 會在響應中返回 ETag 請求頭
3. 後續請求：在 If-None-Match 請求頭中附上 ETag 值
4. 304 未修改：如果數據未發生變化，將收到不含響應體的 304 Not Modified 響應

示例¶

# 初始請求
curl -X GET "https://api.cursor.com/analytics/team/dau" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -D headers.txt

# 響應中包含：ETag: "abc123xyz"

# 攜帶 ETag 的後續請求
curl -X GET "https://api.cursor.com/analytics/team/dau" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "If-None-Match: \"abc123xyz\""

# 如果數據未變化，則返回 304 Not Modified

緩存時長¶

• 緩存時長：15 分鐘 (Cache-Control: public, max-age=900)
• 響應包含 ETag 請求頭
• 在後續請求中添加 If-None-Match 請求頭，數據未變更時將收到 304 Not Modified

優勢¶

• 減少帶寬用量：304 響應不包含響應體
• 響應更快：無需處理未變更的數據
• 更節省速率限制：304 響應不計入速率限制
• 性能更佳：尤其適合頻繁輪詢的端點

最佳實踐¶

1. 實施指數退避¶

收到 429 響應後，請在重試前等待，並逐次延長等待時間：

import time
import requests

def 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:
            # 指數退避：1 秒、2 秒、4 秒、8 秒、16 秒
            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. 將請求分散到不同時間段¶

將 API 調用分散到不同時間段，避免突發請求：

• 將批處理作業安排在不同時間運行
• 處理大型數據集時，在請求之間加入延遲
• 使用隊列系統平滑流量高峯

3. 善用緩存¶

適用於 Analytics API 和 AI Code Tracking API：

這些 API 支持基於 ETag 的 HTTP 緩存。有關如何使用 ETag 減少帶寬用量並避免不必要的請求，請參閱上方的 緩存 部分。

主要優勢：

• 減少帶寬用量
• 數據未變更時響應更快
• 不佔用速率限制 (針對 304 響應)

在 Analytics API 中，使用日期快捷方式 (7d、30d) 代替時間戳，可獲得更好的緩存效果。

4. 監控用量¶

跟蹤請求模式，確保不超出限額：

• 記錄 API 調用的時間戳和響應代碼
• 爲 429 響應設置提醒
• 監控每日/每週用量趨勢
• 根據實際需求調整輪詢間隔

5. 合理進行批量處理¶

對於支持分頁的端點：

• 使用合適的頁面大小，以便單次請求獲取更多數據
• 對於 Analytics API 的按用戶端點：使用 users 參數篩選特定用戶
• 對於大規模數據提取：如可用，請使用 CSV 端點 (可高效地流式傳輸數據)

6. 按合適的間隔輪詢¶

不要過度輪詢更新不頻繁的端點：

• Admin API /teams/daily-usage-data：最多每小時輪詢一次 (數據按小時聚合)
• Admin API /teams/filtered-usage-events：最多每小時輪詢一次 (數據按小時聚合)
• Admin API /organizations/pooled-usage：最多每小時輪詢一次 (數據按小時聚合)
• Admin API /organizations/filtered-usage-events：最多每小時輪詢一次 (數據按小時聚合)
• Analytics API：使用日期快捷方式 (7d、30d) 以獲得更好的緩存效果
• AI Code Tracking API：數據近乎即時採集，但每隔幾分鐘輪詢一次即可

7. 妥善處理錯誤¶

爲所有 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) {
      // 已觸發速率限制——實施退避策略
      throw new Error('Rate limit exceeded');
    }

    if (response.status === 401) {
      // API 密鑰無效
      throw new Error('Authentication failed');
    }

    if (response.status === 403) {
      // 權限不足
      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;
  }
}

常見錯誤響應¶

所有 API 均使用標準 HTTP 狀態碼：

400 錯誤請求¶

請求參數無效或缺少必填字段。

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

401 未授權¶

API 密鑰無效或未提供。

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

403 禁止訪問¶

API 密鑰有效，但權限不足 (例如，在非企業版方案中使用企業版功能) 。

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

404 未找到¶

請求的資源不存在。

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

429 請求過多¶

已超出速率限制。請採用指數退避策略。

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

500 內部服務器錯誤¶

服務器端錯誤。如果問題持續存在，請聯繫支持團隊。

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