[Go to site: main page, start]

Skip to main content

Command Palette

Search for a command to run...

API

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 中的 RouterPython 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/dashboardAPI 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端点类型速率限制
Admin API大多数端点20 次请求/分钟
Admin API/teams/filtered-usage-events/organizations/filtered-usage-events60 次请求/分钟
Admin API/teams/user-spend-limit250 次请求/分钟
Analytics API大多数团队级端点100 次请求/分钟
Analytics API/analytics/team/conversation-insights20 次请求/分钟
Analytics API按用户划分的端点50 次请求/分钟
AI Code Tracking API所有端点每个端点 20 次请求/分钟
Bugbot API/bugbot/review30 次请求/分钟
Bugbot APIdryRun: true 时的 /bugbot/review10 次请求/分钟 (另加触发限制)
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 缓存

缓存工作原理

  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 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 中,使用日期快捷方式 (7d30d) 代替时间戳,可获得更好的缓存效果。

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:使用日期快捷方式 (7d30d) 以获得更好的缓存效果
  • 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"}