Cursor API 概览
Cursor 提供多个 API,可让您以编程方式访问团队的数据、AI 驱动的编码 agent 和使用分析数据。
可用 API
| API | 说明 | 可用性 |
|---|---|---|
| Admin API | 管理团队成员、设置、用量数据、支出和模型访问权限。构建自定义仪表板和监控工具。 | 企业版团队 |
| Analytics API | 全面了解团队的 Cursor 用量、AI 指标、活跃用户和模型用量。 | 企业版团队 |
| AI Code Tracking API | 在提交和变更层面跟踪 AI 生成的代码贡献,用于归因和使用分析。 | 企业版团队 |
| Bugbot API | 触发 Bugbot 评审并获取每次评审的使用分析数据。 | 企业版团队 |
| Cloud Agents API | 以编程方式创建和管理 AI 驱动的编码 agent,用于自动化工作流和代码生成。 | Beta (所有套餐) |
| Origin API | 操作 Origin 仓库、提交、检查、PR 和应用安装。 | Alpha |
| TypeScript SDK | 通过统一接口从 TypeScript 运行 Cursor agents,支持本地和云端运行时。 | 所有用户 |
| Python SDK | 通过支持本地和云端运行时的同步和异步客户端,从 Python 运行 Cursor agents。 | 所有用户 |
| SDK Bridge | 基于开放桥接协议和独立二进制文件,使用其他语言构建 agent SDK。 | 所有用户 |
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
- 前往 cursor.com/dashboard → API Keys
- 点击 New API Key
- 为密钥设置一个便于识别的名称 (例如,“用量仪表盘集成”)
- 立即复制生成的密钥,之后将无法再次查看
密钥格式:crsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
所需权限范围:admin:*
Analytics API
在 Cursor 仪表盘 → API Keys 中生成 API 密钥。
Cloud Agents API
在 Cursor 仪表盘 → API 密钥中创建用户 API 密钥,或使用团队设置中的服务账户 API 密钥。
API 密钥归组织所有,所有管理员均可查看。创建者的账户状态不会影响密钥。
速率限制
所有 API 均实施速率限制,以确保使用公平及系统稳定。速率限制按团队执行,每分钟重置。
按 API 划分的速率限制
| API | 端点类型 | 速率限制 |
|---|---|---|
| Admin API | 大多数端点 | 20 次请求/分钟 |
| Admin API | /teams/filtered-usage-events 和 /organizations/filtered-usage-events | 60 次请求/分钟 |
| Admin API | /teams/user-spend-limit | 250 次请求/分钟 |
| Analytics API | 大多数团队级端点 | 100 次请求/分钟 |
| Analytics API | /analytics/team/conversation-insights | 20 次请求/分钟 |
| Analytics API | 按用户划分的端点 | 50 次请求/分钟 |
| AI Code Tracking API | 所有端点 | 每个端点 20 次请求/分钟 |
| Bugbot API | /bugbot/review | 30 次请求/分钟 |
| Bugbot API | dryRun: true 时的 /bugbot/review | 10 次请求/分钟 (另加触发限制) |
| Cloud Agents 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 缓存
缓存工作原理
- 初始请求:向任意受支持的端点发起请求
- 响应包含 ETag:API 会在响应中返回
ETag请求头 - 后续请求:在
If-None-Match请求头中附上ETag值 - 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 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: # 指数退避: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"}