Cursor API 概览

Cursor 提供多种 API，可用于以编程方式访问你团队的数据、AI 驱动的编码代理和分析功能。

可用 API

Cloud Agents API 和 SDK 用于运行 Cursor agent 工作流 (工作区上下文、工具、命令和编辑) 。它们不是独立的模型推理或聊天补全 API。使用 Auto / auto-smart 时，Cursor Router 会为这些 agent 运行选择模型；请参阅 TypeScript SDK 中的 Router 或 Python SDK。

身份验证

Admin、Analytics、AI Code Tracking 和 Bugbot API 接受 Basic 认证。Cloud Agents API 接受 Basic 或 Bearer 身份验证。Origin API 通过 Origin CLI 或 Origin App 使用 Bearer credentials。

基本身份验证

在基本身份验证中，将你的 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 密钥
2. 点击 新建 API 密钥
3. 为密钥设置一个易于识别的名称 (例如，“用量仪表盘集成”)
4. 请立即复制生成的密钥，之后将无法再次查看

密钥格式：crsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

所需权限范围：admin:*

Analytics API

在Cursor 仪表盘 → API 密钥生成 API 密钥。

Cloud Agents API

在 Cursor 仪表盘 → API Keys 中创建用户 API 密钥，或使用团队设置中的 服务账户 API 密钥。

Origin API

对于需要用户身份验证的请求，请通过 Origin CLI 登录，或为其提供个人用户 API 密钥。CLI 会在调用 Origin 前，用该密钥换取一个短期有效的 access token。具有 admin:* 权限范围的 Team Admin API 密钥无法用于 Origin 的身份验证。应用则使用 app JWT 和安装访问令牌。参见 Origin API 身份验证。

速率限制

所有 API 均实施速率限制，以确保公平使用和系统稳定。限额按已认证用户、团队或组织实施，且大多数仅作用于单个端点。除非某个端点另有说明，默认值为每分钟 20 次请求。

按 API 的速率限制

速率限制响应

当你超出速率限制时，将收到 429 Too Many Requests 响应。Admin API 和组织 API 的响应会包含 Retry-After: 60 以及以下响应体：

{  "code": "error",  "message": "Rate limit exceeded"}

缓存

多个 API 支持使用 ETag 的 HTTP 缓存，以减少带宽占用并提升性能。

支持的 API

• Analytics API：所有端点（团队级和按用户）均支持 HTTP 缓存
• AI Code Tracking API：各端点均支持 HTTP 缓存

缓存机制的工作方式

1. 初始请求：向任一受支持的端点发起请求
2. 响应包含 ETag：API 在响应中返回 ETag 头
3. 后续请求：在 If-None-Match 头中携带该 ETag 值
4. 304 Not Modified：若数据未变化，将返回无响应体的 304 Not Modified

示例

# 初始请求curl -X GET "https://api.cursor.com/analytics/team/dau" \  -H "Authorization: Bearer YOUR_API_KEY" \  -D headers.txt# 响应包含：ETag: "abc123xyz"# 后续请求携带 ETagcurl -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"速率受限。等待 {wait_time} 秒后重试...")            time.sleep(wait_time)            continue                    return response        raise Exception("已超过最大重试次数")

2. 分散请求时间

将 API 调用分布到一段时间内，而非集中突发：

• 将批处理任务安排在不同时间间隔执行
• 处理大型数据集时在请求之间添加延时
• 使用队列系统平滑流量峰值

3. 利用缓存

适用于 Analytics API 和 AI Code Tracking API：

这些 API 支持使用 ETag 的 HTTP 缓存。请参见上方的 Caching 部分，了解如何通过 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) {      // Rate limited - implement backoff      throw new Error('Rate limit exceeded');    }        if (response.status === 401) {      // Invalid API key      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": "请求错误",  "message": "部分用户不在该团队中"}

401 未授权

API 密钥无效或缺失。

{  "error": "未授权",  "message": "API 密钥无效"}

403 禁止访问

API 密钥有效，但权限不足 (例如：在非企业版方案中使用企业版功能) 。

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

404 未找到

请求的资源不存在。

{  "error": "未找到",  "message": "资源不存在"}

429 请求过多

已超出速率限制。请使用指数退避。

{  "error": "请求过多",  "message": "超出速率限制，请稍后再试。"}

500 内部服务器错误

服务器端错误。若问题持续，请联系支持团队。

{  "error": "内部服务器错误",  "message": "发生了意外错误"}