《Cursor文档》-组织 API

组织 API 允许你执行适用于与某个组织关联的各个团队的操作，例如在这些团队之间移动用户、查看跨团队的共享用量、管理组织群组，以及读取或更新模型访问。它使用 组织 API 密钥 以及与团队 Admin API相同的 HTTP 模式。

组织 API 使用Basic 认证，并将你的 API 密钥作为用户名。
有关创建 API 密钥、身份验证方法、速率限制和最佳实践的详细信息，请参阅 API 概览。

组织 API 密钥与团队 API 密钥¶

组织 API 密钥是组织作用域的凭据，团队 API 密钥是团队作用域的凭据。

调用组织级端点 (如 /organizations/team-memberships/sync、/organizations/pooled-usage 和 /organizations/groups) 时，请使用 组织 API 密钥。

调用 /teams/* 下的团队级端点时，请使用 团队 API 密钥 (例如 /teams/members 和 /teams/spend) 。

主要区别¶

作用域：组织 API 密钥可跨同一组织下关联的多个团队执行操作。团队 API 密钥只能在单个团队内执行操作。
端点兼容性：组织端点需要组织 API 密钥。团队端点需要团队 API 密钥。
密钥作用域：每个路由都要求密钥具备特定作用域。只读成员路由接受 members:read；成员和群组写入路由需要 members:*；用量路由需要 usage:*。具备 admin:* 的密钥可用于所有路由，因为 admin 包含其他作用域。
授权失败：如果密钥作用域与端点作用域不匹配，请求会因身份验证或授权错误而失败 (通常为 401 或 403) 。

作用域¶

每个组织 API 密钥都恰好带有一个作用域。只有当密钥的作用域覆盖该路由时，该路由才能使用。更宽的作用域包含较窄作用域允许的全部权限。

作用域	权限	示例路由
`members:read`	对组织成员资格的只读访问权限。	`GET /organizations/members`
`members:*`	对成员和群组的读写权限。包含 `members:read` 允许的全部权限。	`GET /organizations/members`, `POST /organizations/team-memberships/sync`, 所有 `/organizations/groups` 路由
`usage:*`	对共享用量和报表的读取权限。	`POST /organizations/pooled-usage`, `POST /organizations/filtered-usage-events`, `POST /organizations/daily-usage-data`, `POST /organizations/spend`
`models:read`	对模型访问配置和提供商清单的只读访问权限。	`GET /organizations/teams/model-access/configuration`, `GET /organizations/teams/{teamId}/model-access/configuration`, `GET /organizations/teams/{teamId}/model-access/providers`
`models:*`	对模型访问的读写权限。包含 `models:read` 允许的全部权限。	所有模型访问路由，包括批量切换提供商/模型和批量配置
`admin:*`	对所有组织路由的完全访问权限。	以上所有路由

请根据需要选择权限范围最小的作用域。对于只列出成员、但绝不修改成员关系的只读集成，请使用 members:read。对于无需授予完整管理员权限的模型访问自动化，请使用 models:read 或 models:*。在仪表盘中创建组织 API 密钥时，你可以选择这些作用域。

如何传递组织 API 密钥？¶

方式与其他 Cursor API 密钥相同：使用 Basic 认证，将该密钥作为用户名，密码留空。

curl -X POST https://api.cursor.com/organizations/team-memberships/sync \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_abc123",
    "users": [
      { "userId": 12345, "destinationTeamId": 7 }
    ]
  }'

成员¶

读取组织成员信息，并在与你的组织关联的团队之间移动成员。

可用性：仅限企业版
身份验证：组织 API 密钥 (Basic 认证) 。读取成员信息接受只读 members:read 作用域；移动成员需要 members:*。具有 admin:* 的密钥两者都可使用。
作用域：GET /organizations/members 的作用域为组织级别、支持分页，并在一次响应中返回每个成员的组织角色，以及其在所有关联团队中的分配情况。
分页：GET /organizations/members 接受 page 和 pageSize。pageSize 上限为 200；超过该值会按 200 处理。

列出组织成员¶

/organizations/members

获取与你的 API 密钥关联的组织成员，以及每位成员的组织角色和其在关联团队中的分配信息。结果支持分页。

查询参数¶

page number

页码 (从 1 开始) 。默认值为第 1 页。

pageSize number

每页成员数量。上限为 200；超过 200 的值会被截断为 200。

响应字段¶

members array

组织成员对象数组，每个对象包含：

userId number - 成员的唯一数字标识符，对应团队 GET /teams/members 端点返回的 id
email string - 成员的电子邮件地址
name string - 成员的显示名称
organizationRole string - 组织级角色，可以是 admin 或 member。这与各团队分配中的 teamRole 不同：用户可以在组织中是 admin，同时在某个特定团队中担任 member，反之亦然。
teams array - 成员在组织关联团队中的分配情况。每个对象包含：
teamId number - 该成员所属的某个关联团队的整数 ID
teamRole string - 该团队中的角色 (例如 member、owner)

pagination object

分页元数据：page、pageSize、totalCount、totalPages、hasNextPage 和 hasPreviousPage。

curl -X GET "https://api.cursor.com/organizations/members?page=1&pageSize=50" \
  -u YOUR_ORGANIZATION_API_KEY:

响应：

{
  "members": [
    {
      "userId": 12345,
      "email": "developer@company.com",
      "name": "Alex",
      "organizationRole": "member",
      "teams": [
        { "teamId": 7, "teamRole": "member" },
        { "teamId": 8, "teamRole": "owner" }
      ]
    },
    {
      "userId": 12346,
      "email": "admin@company.com",
      "name": "Sam",
      "organizationRole": "admin",
      "teams": [
        { "teamId": 7, "teamRole": "owner" }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "totalCount": 2,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

同步组织团队成员资格¶

/organizations/team-memberships/sync

设置组织内一个或多个用户所属的团队。此操作与 CSV 导入 API 的批量模式一致：发送一个用户数组，每个用户对应返回一行结果。

每个条目必须且只能使用 teamIds 或 destinationTeamId 之一：

teamIds 是用户应所属团队 ID 的完整集合。该端点会将用户的成员关系精确调整为与该集合一致：把用户尚未加入的已列出团队添加进去，并移除所有未列出的团队。若要在迁移期间为用户新增一个团队的同时保留其当前团队，请同时列出这两个团队 (例如 [oldTeamId, newTeamId]) 。
destinationTeamId 会将用户加入单个团队。用户会被加入指定团队，并从其他所有团队中移除。设置 destinationTeamId: NNN 在功能上等同于 teamIds: [NNN]。

请求体¶

organizationId string 必填

公开组织 ID (例如 org_abc123) 。必须与用于调用该端点的组织 API 密钥所属的组织相匹配。

users array 必填

非空条目列表 (每次请求最多 500 条) 。每个元素都是一个包含用户 ID 并且仅有一个团队字段 (teamIds 或 destinationTeamId) 的对象：

userId number | string：要同步的用户 ID。支持整数 ID (例如 12345) 或 string ID (例如 "user_abc123") 。
teamIds number[]：同步后，用户应所属的全部与组织关联的团队 ID 集合。成员关系会被精确调整为与该集合完全一致。任何未列出的团队都会被移除。若要保留用户当前所在的团队，请将这些团队也包含在内 (例如 [7, 8]) 。每个条目最多 100 个团队。
destinationTeamId number：用于同步到单个团队的字段。将 destinationTeamId: NNN 设为与发送 teamIds: [NNN] 等效。该用户的团队将被精确设为这一个团队。必须是关联到该组织的团队。

每条记录只能提供 teamIds 或 destinationTeamId 中的一个。

成功响应 (HTTP 200)¶

results array

每条同步请求对应一个条目，按顺序排列。每个对象包含 userId、该条目解析后的 teamIds，以及 status: "success" 或 status: "error" (该行失败时包含 errorMessage) 。携带 destinationTeamId 的条目也会回显 destinationTeamId (即 teamIds 中的第一个团队) 。

successCount number

status: "success" 的行数。

errorCount number

status: "error" 的行数。

可用性：仅限企业版
身份验证：组织 API 密钥 (Basic 认证) 。该密钥必须包含此路由所需的 members:* scope；带有 admin:* 的密钥也可使用，因为 admin 隐含 members 权限。
组织匹配：响应体中的 organizationId 必须与 API 密钥所属的组织一致；否则请求会被拒绝。
团队集合：teamIds 表示调用后该用户应属于的完整团队集合。用户会被从任何未列出的团队中移除，因此如果要保留用户当前所在的团队，请将这些团队也包含在该集合中。
每个条目一个团队字段：每个条目必须且只能提供 teamIds 或 destinationTeamId 其中之一。
每个条目的团队数量上限：单个条目的 teamIds 最多可列出 100 个团队。
目标用户必须已是该组织的成员，同步才能成功。
条目中的每个团队都必须已关联到该组织，同步才能成功。
如果 users 中某个条目失败，其他条目仍可能成功；请检查每个 results 条目的 status 和 errorMessage。
批量大小：单个请求最多可包含 500 个条目。如有需要，请通过单独的请求发送额外批次。

curl -X POST https://api.cursor.com/organizations/team-memberships/sync \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_abc123",
    "users": [
      { "userId": 12345, "teamIds": [7, 8] },
      { "userId": "user_abc123", "destinationTeamId": 8 }
    ]
  }'

第一条记录将用户 12345 精确关联到团队 7 和 8 (将用户加入尚未加入的团队，并移除任何其他已关联的团队) 。第二条记录使用 destinationTeamId，其效果等同于发送 teamIds: [8]。

响应：

{
  "results": [
    {
      "userId": 12345,
      "teamIds": [7, 8],
      "status": "success"
    },
    {
      "userId": "user_abc123",
      "teamIds": [8],
      "destinationTeamId": 8,
      "status": "success"
    }
  ],
  "successCount": 2,
  "errorCount": 0
}

错误响应：

大多数 API 错误会使用 HTTP 401、403 或 400，并返回如下结构的 JSON 响应体：

{
  "code": "error",
  "message": "…"
}

404：未找到组织 (此路由的消息字段名不同)：

{
  "error": "Organization not found"
}

401：组织 API 密钥无效 (密钥错误或缺失)：

{
  "code": "error",
  "message": "Invalid Organization API Key"
}

401：缺少所需权限范围 (密钥有效，但未包含 members:* 或 admin:*)：

{
  "code": "error",
  "message": "Organization API key missing required scope: members:*"
}

403：组织与该 API 密钥不匹配 (响应体中的 organizationId 与该 API 密钥所属的组织不一致)：

{
  "code": "error",
  "message": "Not authorized"
}

400：无效的请求体 (示例；每个失败的请求仅适用其中一种情况)：

{
  "code": "error",
  "message": "Request body is required"
}

{
  "code": "error",
  "message": "organizationId is required"
}

{
  "code": "error",
  "message": "users must be a non-empty array"
}

{
  "code": "error",
  "message": "users must not contain more than 500 moves"
}

按行失败 (HTTP 200) ：单条记录的验证错误或业务规则错误会在 results 中返回，并带有 status: "error" 和 errorMessage。下面的示例使用 destinationTeamId，因此这些行会回显 destinationTeamId；使用 teamIds 发送的条目则会回显 teamIds。如果 userId / destinationTeamId 的类型无效，则该行中的对应无效字段会使用 0：

{
  "results": [
    {
      "userId": 0,
      "destinationTeamId": 7,
      "status": "error",
      "errorMessage": "Invalid userId"
    }
  ],
  "successCount": 0,
  "errorCount": 1
}

{
  "results": [
    {
      "userId": 12345,
      "destinationTeamId": 0,
      "status": "error",
      "errorMessage": "Invalid destinationTeamId"
    }
  ],
  "successCount": 0,
  "errorCount": 1
}

{
  "results": [
    {
      "userId": 0,
      "destinationTeamId": 0,
      "status": "error",
      "errorMessage": "Invalid userId. Invalid destinationTeamId"
    }
  ],
  "successCount": 0,
  "errorCount": 1
}

逐行失败 (HTTP 200) ：当输入类型正确但无法应用更改时，由同步逻辑返回：

{
  "results": [
    {
      "userId": 12345,
      "destinationTeamId": 999,
      "status": "error",
      "errorMessage": "Team is not linked to this organization"
    }
  ],
  "successCount": 0,
  "errorCount": 1
}

{
  "results": [
    {
      "userId": 12345,
      "destinationTeamId": 7,
      "status": "error",
      "errorMessage": "User is not a member of this organization"
    }
  ],
  "successCount": 0,
  "errorCount": 1
}

{
  "results": [
    {
      "userId": 12345,
      "destinationTeamId": 7,
      "status": "error",
      "errorMessage": "User not found"
    }
  ],
  "successCount": 0,
  "errorCount": 1
}

用量¶

查看你的组织中所有关联团队的用量情况。这些端点会汇总组织用量池内所有团队的数据，因此你无需为每个团队分别使用团队 API 密钥。若只需统计单个团队，请改用团队 Admin API 的用量端点。

可用性：仅企业版
身份验证：组织 API 密钥 (Basic 认证) 。该密钥必须包含 usage:* 作用域才能访问这些路由；包含 admin:* 的密钥同样可用，因为 admin 权限涵盖 usage。
组织匹配：请求体中的 organizationId 必须与 API 密钥所属的组织一致；否则请求会被拒绝。
团队归属：teamIds 中的每个条目都必须属于该组织。引用组织外团队的请求会被拒绝。
轮询：用量数据按小时粒度汇总。这些端点最多每小时轮询一次。速率限制为每分钟 20 个请求。参见速率限制和最佳实践。

获取共享用量¶

/organizations/pooled-usage

获取组织的共享用量：包括用量池的支出上限、整个组织的总用量，以及按团队划分的明细。这些数据用于仪表盘中的共享用量部分。所有金额字段均以美分为单位。

请求体¶

organizationId string 必填

公开的组织 ID (例如 org_abc123) 。必须与用于调用该端点的组织 API 密钥所属组织一致。

响应字段¶

pool object

当前合同期内用量池层级的汇总数据：

limitCents number - 组织的共享用量支出上限，以美分为单位
usedCents number - 目前已使用的共享总用量，以美分为单位
remainingCents number - 剩余共享预算 (limitCents 减去 usedCents) ，以美分为单位
contractStartDate string | null - 标记当前合同期开始时间的 ISO 8601 时间戳；如果未设置合同日期，则为 null
contractEndDate string | null - 标记当前合同期结束时间的 ISO 8601 时间戳；如果未设置合同日期，则为 null

teams array

按团队划分的用量明细。所有 usedCents 之和等于 pool.usedCents。每个对象包含：

teamId number - 关联到该组织的团队整数 ID
usedCents number - 该团队在当前合同期内消耗的用量，以美分为单位
budgetLimitCents number | undefined - 该团队的预算上限，以美分为单位。仅当该团队已配置预算时才会返回。

curl -X POST https://api.cursor.com/organizations/pooled-usage \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_abc123"
  }'

响应：

{
  "pool": {
    "limitCents": 5000000,
    "usedCents": 1862340,
    "remainingCents": 3137660,
    "contractStartDate": "2026-01-01T00:00:00.000Z",
    "contractEndDate": "2026-12-31T23:59:59.999Z"
  },
  "teams": [
    {
      "teamId": 7,
      "usedCents": 1440100,
      "budgetLimitCents": 2000000
    },
    {
      "teamId": 8,
      "usedCents": 422240
    }
  ]
}

获取使用事件¶

/organizations/filtered-usage-events

检索与贵组织关联的各团队的详细使用事件。这是团队端点 /teams/filtered-usage-events 的组织范围对应版本：它返回相同的事件结构，每个事件均标注其所属的 teamId。

默认会返回组织用量池中所有团队的事件。传入 teamIds 可将返回结果限制为特定团队。

成本计算：对各个事件的 chargedCents 字段求和，以便将事件级成本与 /organizations/pooled-usage 返回的按团队划分的 usedCents 明细进行核对。当请求符合该费率的适用条件时，此字段同时包括模型成本和 Cursor Token 费率。

cursorTokenFee 字段表示 Cursor Token 费率，且仅在该费率适用于第三方模型请求时才会出现。这包括 Auto 路由到第三方模型的情况。Grok 和 Composer 等第一方 Cursor 模型，以及按请求计费的企业版账户，均不收取此费用。请参阅 Cursor Token 费率。

请求体¶

organizationId string 必填

组织公开 ID (例如 org_abc123) 。必须与用于调用该端点的 Organization API 密钥所属的组织一致。

teamIds number[]

可选的一组整数型团队 ID，用于包含指定团队。每个 ID 必须属于该组织。若省略，则包含该组织池中的所有团队。

startDate number

起始日期 (以纪元毫秒为单位) 。此边界为闭合 (包含端点) 。

endDate number

结束日期 (以纪元毫秒为单位) 。此边界为闭合 (包含端点) 。

userId number

按特定用户 ID 筛选。

email string

按用户电子邮件地址筛选。

serviceAccountId string

按服务账号 ID 筛选。

page number

页码 (从 1 开始) 。默认值：1

pageSize number

每页返回的结果数量。默认值：10

响应字段¶

usageEvents 中的每个对象包含与团队 endpoint 相同的字段，并额外附带一个所属团队标签：

teamId number - 拥有此事件的团队 ID (整数)
timestamp string - 事件时间戳，以纪元毫秒为单位 (string 形式)
userEmail string - 发起该请求的用户电子邮件地址
serviceAccountId string | undefined - 发起请求的服务账户 ID。对于人工用户事件，此字段会省略。
serviceAccountName string | undefined - 发起该请求的服务账户的显示名称。对于人工用户事件，此字段将省略。
model string - 该请求使用的 AI 模型
kind string - 计费类型 (例如：Usage-based、Included in Business)
maxMode boolean - 请求是否使用了 Max Mode
requestsCosts number - 以请求单位计的成本
isTokenBasedCall boolean - 该请求是否按 token 使用量计费
isChargeable 布尔值 - 该事件是否会产生费用
isHeadless 布尔值 - 该请求是否在未连接客户端的情况下发起 (例如，后台代理)
tokenUsage object | undefined - 使用量详情 (当 isTokenBasedCall 为 true 时提供) ：
inputTokens number - 消耗的输入 token
outputTokens number - 生成的输出 token
cacheWriteTokens number - 写入缓存的 token
cacheReadTokens number - 从缓存读取的 token
totalCents number - 模型总成本 (以美分计)
discountPercentOff number | undefined - 应用的折扣百分比 (如有)
chargedCents number - 此事件收取的总金额 (单位：美分) 。对于适用 Cursor Token 费率的第三方模型请求，此字段同时包含模型成本和 Cursor Token 费率。
cursorTokenFee number | undefined - 以美分计的 Cursor Token 费率。仅当该费率适用于第三方模型请求时才会提供 (包括 Auto 将请求路由到第三方模型时) 。

# 组织用量池中所有团队的事件
curl -X POST https://api.cursor.com/organizations/filtered-usage-events \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_abc123",
    "startDate": 1748411762359,
    "endDate": 1751003762359,
    "page": 1,
    "pageSize": 25
  }'

# 特定团队的事件
curl -X POST https://api.cursor.com/organizations/filtered-usage-events \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_abc123",
    "teamIds": [7, 8],
    "startDate": 1748411762359,
    "endDate": 1751003762359,
    "page": 1,
    "pageSize": 25
  }'

响应：

{
  "totalUsageEventsCount": 113,
  "pagination": {
    "numPages": 12,
    "currentPage": 1,
    "pageSize": 10,
    "hasNextPage": true,
    "hasPreviousPage": false
  },
  "usageEvents": [
    {
      "teamId": 7,
      "timestamp": "1750979225854",
      "userEmail": "developer@company.com",
      "model": "claude-4.5-sonnet",
      "kind": "Usage-based",
      "maxMode": true,
      "requestsCosts": 5,
      "isTokenBasedCall": true,
      "isChargeable": true,
      "isHeadless": false,
      "tokenUsage": {
        "inputTokens": 126,
        "outputTokens": 450,
        "cacheWriteTokens": 6112,
        "cacheReadTokens": 11964,
        "totalCents": 20.18232
      },
      "chargedCents": 21.36232,
      "cursorTokenFee": 1.18
    },
    {
      "teamId": 8,
      "timestamp": "1750978339901",
      "userEmail": "admin@company.com",
      "model": "claude-4-sonnet-thinking",
      "kind": "Included in Business",
      "maxMode": true,
      "requestsCosts": 1.4,
      "isTokenBasedCall": false,
      "isChargeable": false,
      "isHeadless": false,
      "chargedCents": 8
    }
  ],
  "period": {
    "startDate": 1748411762359,
    "endDate": 1751003762359
  }
}

获取每日用量数据¶

/organizations/daily-usage-data

获取与您组织关联的所有团队中每位成员的每日使用指标。这是团队 /teams/daily-usage-data 端点的组织级对应接口，每行数据都标注了所属的 teamId。结果按用户分页，并返回在所请求日期范围内具有成员身份的所有成员的数据；使用 page 和 pageSize 进行翻页。

请求体¶

organizationId string 必填

组织的公开 ID (例如 org_abc123) 。必须与用于调用此端点的组织 API 密钥所属的组织相匹配。

startDate number

起始日期 (Unix 毫秒时间戳) 。默认为 7 天前。

endDate number

结束日期 (epoch 毫秒时间戳) 。默认为当前时间。

teamIds number[]

需要统计的组织关联团队。若省略，则包含该组织池中的所有团队。每次请求最多 100 个团队。

page number

页码 (从 1 开始) 。默认值：1

pageSize number

每页用户数量 (1-1000) 。默认值：1000

userEmail string

按电子邮件筛选一个或多个用户。接受单个电子邮件或以逗号分隔的列表。userEmails 可作为别名。

日期范围不得超过 30 天。若需更长时间段，请分多次请求。

字段 subscriptionIncludedReqs、usageBasedReqs 和 apiKeyReqs 统计的是原始使用事件，而非较早的基于请求的定价模式中的可计费请求单位。

响应字段¶

data 数组中的每个对象包含与团队每日用量端点相同的字段，并额外包含一个 teamId。关键字段：

userId string - 带有 user_ 前缀的已编码用户 ID (例如 user_abc123)
teamId number - 该行所属的组织关联团队 ID
day string - 该记录对应的日期 (ISO 日期，例如 2024-03-18)
date 数字 - 以纪元毫秒表示的日期
email string - 用户的电子邮件地址
isActive 布尔值 - 用户当天是否活跃
totalLinesAdded number - 新增代码总行数
totalLinesDeleted number - 已删除的代码总行数
acceptedLinesAdded 数字 - 已接受的 AI 建议新增行数
acceptedLinesDeleted number - 已接受的 AI 建议中删除的行数
totalApplies number - AI 代码应用次数总数
totalAccepts 数值 - 已接受的 AI 建议总数
totalRejects number - 被拒绝的 AI 建议总数
totalTabsShown number - 向用户显示的 Tab 补全总数
totalTabsAccepted 数字 - 用户已接受的 Tab 补全总数
composerRequests 数值 - 发起的 Composer 请求数量
chatRequests number - 发起的聊天请求数
agentRequests number - 发起的 Agent 模式请求数
cmdkUsages number - Cmd+K Inline edit 的使用次数
subscriptionIncludedReqs number - 订阅方案包含的请求数
apiKeyReqs number - 通过 API 密钥发起的请求数
usageBasedReqs number - 按用量计费 (超额) 请求数
bugbotUsages number - Bugbot 的用量
mostUsedModel string | null - 当天最常用的 AI 模型
applyMostUsedExtension string | null - apply 操作中最常见的文件扩展名
tabMostUsedExtension string | null - Tab 补全中最常见的文件扩展名
clientVersion string | null - 使用的 Cursor 客户端版本

响应还包含一个 pagination 对象 (page、pageSize、totalUsers、totalPages、hasNextPage、hasPreviousPage) 和一个 period 对象 (startDate、endDate) 。

curl -X POST https://api.cursor.com/organizations/daily-usage-data \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_abc123",
    "startDate": 1710720000000,
    "endDate": 1710892800000,
    "page": 1,
    "pageSize": 1000
  }'

响应：

{
  "data": [
    {
      "userId": "user_abc123",
      "teamId": 101,
      "day": "2024-03-18",
      "date": 1710720000000,
      "isActive": true,
      "totalLinesAdded": 1543,
      "totalLinesDeleted": 892,
      "acceptedLinesAdded": 1102,
      "acceptedLinesDeleted": 645,
      "totalApplies": 87,
      "totalAccepts": 73,
      "totalRejects": 14,
      "totalTabsShown": 342,
      "totalTabsAccepted": 289,
      "composerRequests": 45,
      "chatRequests": 128,
      "agentRequests": 12,
      "cmdkUsages": 67,
      "subscriptionIncludedReqs": 180,
      "apiKeyReqs": 0,
      "usageBasedReqs": 5,
      "bugbotUsages": 3,
      "mostUsedModel": "gpt-5",
      "applyMostUsedExtension": ".tsx",
      "tabMostUsedExtension": ".ts",
      "clientVersion": "0.25.1",
      "email": "developer@company.com"
    }
  ],
  "period": {
    "startDate": 1710720000000,
    "endDate": 1710892800000
  },
  "pagination": {
    "page": 1,
    "pageSize": 1000,
    "totalUsers": 150,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

获取支出数据¶

/organizations/spend

获取你的组织关联的各团队中按成员统计的支出数据。这是团队 /teams/spend 端点在组织范围内的对应版本，并会用所属的 teamId 标记每位成员。与团队端点不同，支出基于与 /organizations/pooled-usage 相同的已包含支出定义，按组织合同窗口统计 (而非各团队各自的计费周期) ，因此这些数字可与用量池对齐。

请求体¶

organizationId string 必填

公开组织 ID (例如 org_abc123) 。必须与调用该端点时所用的 Organization API 密钥对应的组织一致。

teamIds number[]

要纳入报告的组织关联团队。省略时，将包含组织用量池中的所有团队。每次请求最多 100 个团队。

sortBy string

排序字段：email、name、spendCents。默认值：email

sortDirection string

排序方向：asc、desc。默认值：asc

page number

页码 (从 1 开始) 。默认值：1

pageSize number

每页结果数 (1-1000) 。默认值：100

支出数据基于组织用量池中的各团队进行汇总，因此不包含 /teams/spend 中的单团队字段 subscriptionCycleStart、overallSpendCents、fastPremiumRequests、hardLimitOverrideDollars 和 monthlyLimitDollars。统计窗口会在 period 中返回。

响应字段¶

teamMemberSpend 中的每个对象都包含：

userId string - 带 user_ 前缀的编码用户 ID (例如 user_abc123)
teamId number - 该成员所属的组织关联团队 ID
name string - 用户的显示名称
email string - 用户的电子邮件地址
role string - 该成员在团队中的角色 (例如 member、owner)
spendCents number - 在组织合同窗口内归属于该成员的已包含用量池支出，单位为美分

响应还包括 totalMembers (number) 、totalPages (number) ，以及描述组织合同窗口的 period 对象 (startDate、endDate，以 epoch 毫秒表示) 。

curl -X POST https://api.cursor.com/organizations/spend \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_abc123",
    "sortBy": "spendCents",
    "sortDirection": "desc",
    "page": 1,
    "pageSize": 25
  }'

响应：

{
  "teamMemberSpend": [
    {
      "userId": "user_abc123",
      "teamId": 101,
      "name": "Alex",
      "email": "developer@company.com",
      "role": "member",
      "spendCents": 2450
    },
    {
      "userId": "user_def456",
      "teamId": 202,
      "name": "Sam",
      "email": "admin@company.com",
      "role": "owner",
      "spendCents": 1875
    }
  ],
  "totalMembers": 15,
  "totalPages": 1,
  "period": {
    "startDate": 1735689600000,
    "endDate": 1767225600000
  }
}

模型访问¶

模型访问路由目前为预览版，可能会发生变化。路径、响应字段和错误行为可能会在正式发布前调整。

读取和更新组织关联团队的模型访问策略。这些路由与团队模型访问 API 对应，但仅适用于关联团队。

使用列表接口和按团队查询的 GET 接口来发现配置偏差。通过配置 PUT 接口以及提供商/模型开关 (包括每个模型的 parameters) 来对齐团队配置。没有组织级别的复制端点或策略指纹。

数值型 teamId 可通过 GET /organizations/members 等路由获取。

可用性：企业版组织。目标团队必须已启用模型访问控制。
身份验证：组织 API 密钥 (Basic 认证) 。读取需要 models:read。写入需要 models:*。具有 admin:* 权限的密钥两者均可使用。具有 members:*、usage:* 和 read:* 权限的密钥无法调用这些路由。
团队归属：每个 teamId 都必须关联到该组织。在单团队路由中，未知或未关联的团队会返回 404。在批量路由中，未关联的团队会作为 HTTP 200 错误行返回。
先配置：当团队仍处于 unrestricted (或 legacy) 状态时，读取和写入提供商和模型会返回 409。请先通过 PUT /organizations/teams/{teamId}/model-access/configuration (或批量配置路由) 创建自定义策略。首次默认值 PUT 会初始化目录默认值；不会复制其他团队的开关状态映射。
恢复为不受限：在按团队或批量配置 PUT 中发送 { "state": "unrestricted" }。
批量部分成功：批量路由最多接受 100 个 teamIds，批次经过处理后始终返回 HTTP 200，即使部分行失败也是如此。请检查 errorCount 和每个 results[].status。成功的行不会回滚。操作对每个团队都是幂等的，因此仅重试失败的 teamId。4xx 或 5xx 响应会拒绝整个请求，且不会应用任何更改。响应结构与 /organizations/team-memberships/sync 相同。
速率限制：每分钟 20 个请求。写入会以 team_settings 事件的形式出现在团队审计日志中。请参阅速率限制和最佳实践。

列出模型访问配置¶

/organizations/teams/model-access/configuration

列出关联团队的模型访问配置。可用于发现不受限策略与自定义策略之间的偏差。若要发现开关状态偏差，请 GET 每个团队的提供商并进行比较。

如果关联团队未启用模型访问控制，该行仍会返回 HTTP 200，并包含 errorMessage 而非 state / 默认值。该团队的按团队 GET 和写入路由会返回 403。

查询参数¶

page number

页码 (从 1 开始) 。

pageSize number

每页结果数。

teamIds string

可选，以逗号分隔的团队 ID，例如 7,8,9。

curl -X GET "https://api.cursor.com/organizations/teams/model-access/configuration?page=1&pageSize=50" \
  -u YOUR_ORGANIZATION_API_KEY:

响应：

{
  "teams": [
    {
      "teamId": 7,
      "teamName": "Platform",
      "state": "custom",
      "newProviderDefault": "disabled",
      "newModelDefault": "enabled"
    },
    {
      "teamId": 8,
      "teamName": "Mobile",
      "state": "custom",
      "newProviderDefault": "disabled",
      "newModelDefault": "enabled"
    },
    {
      "teamId": 9,
      "teamName": "Data",
      "state": "unrestricted",
      "newProviderDefault": null,
      "newModelDefault": null
    },
    {
      "teamId": 10,
      "teamName": "Research",
      "errorMessage": "Model access control is not available for this team"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "totalCount": 4,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

获取团队模型访问配置¶

/organizations/teams/:teamId/model-access/configuration

获取一个关联团队的配置。

参数¶

teamId number 必填

关联到该组织的团队的整数 ID。

curl -X GET https://api.cursor.com/organizations/teams/7/model-access/configuration \
  -u YOUR_ORGANIZATION_API_KEY:

更新团队模型访问配置¶

/organizations/teams/:teamId/model-access/configuration

为一个关联团队创建或更新配置，或将该团队设为不受限制。请求体和初始化行为与团队路由相同。

参数¶

teamId number 必填

关联到组织的团队的整数 ID。

请求体¶

state string

可选。使用 unrestricted 清除策略。发送默认值时省略此字段。

newProviderDefault string

enabled 或 disabled。创建或更新自定义策略时必填；当 state 为 unrestricted 时省略此字段。

newModelDefault string

enabled 或 disabled。创建或更新自定义策略时必填；当 state 为 unrestricted 时省略此字段。

curl -X PUT https://api.cursor.com/organizations/teams/7/model-access/configuration \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "newProviderDefault": "disabled",
    "newModelDefault": "enabled"
  }'

将一个关联团队设为不受限制：

curl -X PUT https://api.cursor.com/organizations/teams/7/model-access/configuration \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{ "state": "unrestricted" }'

批量更新模型访问配置¶

/organizations/teams/model-access/configuration

为多个关联团队创建或更新配置，或将其恢复为不受限状态。每个请求最多可包含 100 个 teamIds。

HTTP 200 表示该批次已处理完毕，并不代表每一项都成功。请检查 errorCount 和每个 results[].status。成功的团队会保留新配置。此操作对每个团队均具备幂等性，因此仅重试失败的 teamId。4xx 或 5xx 响应会拒绝整个请求且不应用任何更改。

请求体¶

teamIds number[] 必填

要更新的关联团队 ID。每个请求最多 100 个。

state string

可选。使用 unrestricted 清除各团队的策略。发送默认值时省略此项。

newProviderDefault string

enabled 或 disabled。创建或更新自定义策略时必填；当 state 为 unrestricted 时省略。

newModelDefault string

enabled 或 disabled。创建或更新自定义策略时必填；当 state 为 unrestricted 时省略。

为多个团队设置自定义策略的默认值：

curl -X PUT https://api.cursor.com/organizations/teams/model-access/configuration \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "teamIds": [7, 8, 9],
    "newProviderDefault": "disabled",
    "newModelDefault": "enabled"
  }'

将多个团队恢复为不受限状态：

curl -X PUT https://api.cursor.com/organizations/teams/model-access/configuration \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "teamIds": [7, 8, 9],
    "state": "unrestricted"
  }'

响应：

{
  "results": [
    { "teamId": 7, "status": "success" },
    { "teamId": 8, "status": "success" },
    {
      "teamId": 9,
      "status": "error",
      "errorMessage": "Team is not linked to this organization"
    }
  ],
  "successCount": 2,
  "errorCount": 1
}

获取团队模型访问提供商¶

/organizations/teams/:teamId/model-access/providers

列出一个关联团队的提供商和模型，包括各模型的 parameters (结构与团队提供商路由相同) 。如果团队没有自定义策略，则返回 409。

参数¶

teamId number 必填

关联到组织的团队整数 ID。

curl -X GET https://api.cursor.com/organizations/teams/7/model-access/providers \
  -u YOUR_ORGANIZATION_API_KEY:

更新团队模型访问提供商¶

/organizations/teams/:teamId/model-access/providers/:provider

为一个关联团队启用或禁用提供商。如果团队没有自定义策略，则返回 409。

参数¶

teamId number 必填

关联到组织的团队整数 ID。

provider string 必填

目录中的提供商 ID (例如 openai) 。

请求体¶

enabled boolean 必填

curl -X PUT https://api.cursor.com/organizations/teams/7/model-access/providers/openai \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

更新团队模型访问模型¶

/organizations/teams/:teamId/model-access/providers/:provider/models/:model

为一个关联团队启用或禁用模型，并可选择设置每个模型的 parameters (请求体与团队模型路由相同) 。当团队没有自定义策略时，返回 409。

参数¶

teamId number 必填

关联到组织的团队整数 ID。

provider string 必填

目录中的提供商 ID (例如 anthropic) 。

model string 必填

目录中的模型 ID (例如 claude-opus-4-6) 。

请求体¶

enabled boolean 必填

parameters object

参数 ID 到 { allowedValues, defaultValue } 的可选映射。省略的字段保持不变。allowedValues: null 会清除限制。defaultValue: null 会恢复目录默认值。请参阅团队更新模型访问模型文档。

在一个关联团队中禁用 Fast：

curl -X PUT https://api.cursor.com/organizations/teams/7/model-access/providers/anthropic/models/claude-opus-4-6 \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "parameters": {
      "fast": { "allowedValues": ["false"] }
    }
  }'

设置默认推理 effort：

curl -X PUT https://api.cursor.com/organizations/teams/7/model-access/providers/openai/models/gpt-5.4 \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "parameters": {
      "reasoning": {
        "allowedValues": ["low", "medium", "high"],
        "defaultValue": "high"
      }
    }
  }'

批量更新模型访问提供商¶

/organizations/teams/model-access/providers/:provider

在多个关联团队中启用或禁用提供商。每个请求最多可包含 100 个 teamIds。

HTTP 200 表示批处理已完成，并不代表每一行都成功。请检查 errorCount 和每个 results[].status。成功的行不会回滚。该操作对每个团队都是幂等的，因此仅重试失败的 teamId。4xx 或 5xx 响应会拒绝整个请求，且不会应用任何更改。

参数¶

provider string 必填

目录中的提供商 ID (例如 openai) 。

请求体¶

enabled boolean 必填

teamIds number[] 必填

要更新的关联团队 ID。每个请求最多 100 个。

curl -X PUT https://api.cursor.com/organizations/teams/model-access/providers/openai \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "teamIds": [7, 8, 9],
    "enabled": false
  }'

响应：

{
  "results": [
    { "teamId": 7, "status": "success" },
    { "teamId": 8, "status": "success" },
    {
      "teamId": 9,
      "status": "error",
      "errorMessage": "团队没有模型访问策略。请使用 PUT /teams/model-access/configuration 创建一个，或在团队设置 → 模型中启用模型访问。"
    }
  ],
  "successCount": 2,
  "errorCount": 1
}

在此示例中，HTTP 状态仍为 200，因为批处理已完成。团队 7 和 8 的提供商仍处于禁用状态；仅在创建团队 9 的配置后重试该团队。

批量更新模型访问配置中的模型¶

/organizations/teams/model-access/providers/:provider/models/:model

为多个关联团队启用或禁用模型，也可选择使用与单团队模型 PUT 相同的 parameters 映射。每个请求最多可包含 100 个 teamIds。

HTTP 200 表示批处理已完成，并不表示每一行都成功。请检查 errorCount 和每个 results[].status。成功的行不会回滚。该操作对每个团队都是幂等的，因此仅重试失败的 teamId。4xx 或 5xx 响应会拒绝整个请求，且不会应用任何更改。

参数¶

provider string 必填

目录中的提供商 ID (例如 anthropic) 。

model string 必填

目录中的模型 ID (例如 claude-opus-4-6) 。

请求体¶

enabled boolean 必填

teamIds number[] 必填

要更新的关联团队 ID。每个请求最多 100 个。

parameters object

可选。与单团队模型 PUT 使用相同的映射。allowedValues: null 会清除限制。defaultValue: null 会恢复目录默认值。

在关联团队中禁用 Fast：

curl -X PUT https://api.cursor.com/organizations/teams/model-access/providers/anthropic/models/claude-opus-4-6 \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "teamIds": [7, 8, 9],
    "enabled": true,
    "parameters": {
      "fast": { "allowedValues": ["false"] }
    }
  }'

将关联团队的默认推理强度固定为：

curl -X PUT https://api.cursor.com/organizations/teams/model-access/providers/openai/models/gpt-5.4 \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "teamIds": [7, 8, 9],
    "enabled": true,
    "parameters": {
      "reasoning": {
        "allowedValues": ["low", "medium", "high"],
        "defaultValue": "high"
      }
    }
  }'

响应：

{
  "results": [
    { "teamId": 7, "status": "success" },
    { "teamId": 8, "status": "success" },
    {
      "teamId": 9,
      "status": "error",
      "errorMessage": "团队未配置模型访问策略。请使用 PUT /teams/model-access/configuration 创建配置，或在团队设置 → 模型中启用模型访问。"
    }
  ],
  "successCount": 2,
  "errorCount": 1
}

错误¶

错误响应体格式如下：

{ "code": "error", "message": "…" }

状态	情况
`401`	Key 无效，或缺少 `models:read` / `models:` (或 `admin:`) 权限
`403`	该团队不支持模型访问控制 (单团队路由)
`404`	该团队未关联到组织 (单团队路由)
`409`	该团队的 `state` 为 `unrestricted` 或 `legacy` 时读取提供商或模型，或对单个团队执行写入操作
`400`	提供商、模型、参数 ID 或参数值未知；响应体无效；`allowedValues` 为空；默认值不在 `allowedValues` 内；设置无法解析为有效的模型变体；或会阻止 Smart Auto 所需模型

批量组织路由 (带 teamIds 的 PUT .../providers/:provider、PUT .../providers/:provider/models/:model 和 PUT .../configuration) 会在批处理完成后返回 HTTP 200，即使某些行失败也是如此。errorCount 非零仍表示 HTTP 响应成功。未关联的团队以及缺少配置等公开错误会显示为 status: "error" 行。成功的行不会回滚。每个团队的操作都是幂等的，因此仅重试失败的 teamId。任何 4xx 或 5xx 响应均表示整个请求被拒绝，且未应用任何更改。当关联团队无法加载配置时，列表路由也会返回 HTTP 200 和一个包含 errorMessage 的行。

组织群组¶

组织群组用于管理同一组织下各关联团队的成员。有关仪表盘设置和群组级控制，请参阅组织群组。

身份验证：组织 API 密钥 (Basic 认证)。读取路由需要 members:* 作用域。写入路由也需要 members:*。带有 admin:* 的密钥也可用，因为 admin 权限包含 members 权限。
群组 ID：组织群组 ID 使用 g_ 前缀。
分页：列表路由接受 page 和 pageSize。两个值都必须是正整数。

列出组织群组¶

/organizations/groups

获取与你的 API 密钥关联的组织下的组织群组。

查询参数¶

page number

页码。默认为第一页。

pageSize number

每页的群组数量。

curl -X GET "https://api.cursor.com/organizations/groups?page=1&pageSize=50" \
  -u YOUR_ORGANIZATION_API_KEY:

响应：

{
  "groups": [
    {
      "id": "g_PDSPmvukpYgZEDXsoNirw3CFhy",
      "name": "Engineering",
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-20T14:22:00.000Z"
    },
    {
      "id": "g_kljUvI0ASZORvSEXf9hV0ydcso",
      "name": "Design",
      "createdAt": "2026-01-16T09:00:00.000Z",
      "updatedAt": "2026-01-16T09:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "totalCount": 2,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

获取组织群组¶

/organizations/groups/:groupId

获取单个组织群组。

参数¶

groupId string 必填

带有 g_ 前缀的组织群组 ID。

curl -X GET https://api.cursor.com/organizations/groups/g_PDSPmvukpYgZEDXsoNirw3CFhy \
  -u YOUR_ORGANIZATION_API_KEY:

响应：

{
  "group": {
    "id": "g_PDSPmvukpYgZEDXsoNirw3CFhy",
    "name": "Engineering",
    "createdAt": "2026-01-15T10:30:00.000Z",
    "updatedAt": "2026-01-20T14:22:00.000Z"
  }
}

列出组织群组成员¶

/organizations/groups/:groupId/members

获取组织群组中的成员。

参数¶

groupId string 必填

带有 g_ 前缀的组织群组 ID。

查询参数¶

page number

页码。默认值为第一页。

pageSize number

每页的成员数。

curl -X GET "https://api.cursor.com/organizations/groups/g_PDSPmvukpYgZEDXsoNirw3CFhy/members?page=1&pageSize=50" \
  -u YOUR_ORGANIZATION_API_KEY:

响应：

{
  "members": [
    {
      "userId": "user_abc123",
      "name": "Alex Developer",
      "email": "alex@company.com",
      "joinedAt": "2026-01-15T10:30:00.000Z"
    },
    {
      "userId": "user_def456",
      "name": "Sam Engineer",
      "email": "sam@company.com",
      "joinedAt": "2026-01-16T09:15:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "totalCount": 2,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

添加组织群组成员¶

/organizations/groups/:groupId/members/bulk-add

将成员添加到组织群组。

参数¶

groupId string 必填

带有 g_ 前缀的组织群组 ID。

请求体¶

userIds string[] 必填

带有 user_ 前缀的公开用户 ID 数组。单次请求最多可包含 100 个用户。

curl -X POST https://api.cursor.com/organizations/groups/g_PDSPmvukpYgZEDXsoNirw3CFhy/members/bulk-add \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "userIds": ["user_abc123", "user_def456"]
  }'

响应：

{
  "addedCount": 2
}

移除组织群组成员¶

/organizations/groups/:groupId/members/bulk-remove

从组织群组中移除成员。

参数¶

groupId string 必填

带有 g_ 前缀的组织群组 ID。

请求体¶

userIds string[] 必填

带有 user_ 前缀的公开用户 ID 数组。单次请求最多可包含 100 个用户。

curl -X POST https://api.cursor.com/organizations/groups/g_PDSPmvukpYgZEDXsoNirw3CFhy/members/bulk-remove \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "userIds": ["user_def456"]
  }'

响应：

{
  "removedCount": 1
}

《Cursor文档》-组织 API

组织 API 密钥与团队 API 密钥¶

主要区别¶

作用域¶

如何传递组织 API 密钥？¶

成员¶

列出组织成员¶

查询参数¶

响应字段¶

同步组织团队成员资格¶

请求体¶

成功响应 (HTTP 200)¶

用量¶

获取共享用量¶

请求体¶

响应字段¶

获取使用事件¶

请求体¶

响应字段¶

获取每日用量数据¶

请求体¶

响应字段¶

获取支出数据¶

请求体¶

响应字段¶

模型访问¶

列出模型访问配置¶

查询参数¶

获取团队模型访问配置¶

参数¶

更新团队模型访问配置¶

参数¶

请求体¶

批量更新模型访问配置¶

请求体¶

获取团队模型访问提供商¶

参数¶

更新团队模型访问提供商¶

参数¶

请求体¶

更新团队模型访问模型¶

参数¶

请求体¶

批量更新模型访问提供商¶

参数¶

请求体¶

批量更新模型访问配置中的模型¶

参数¶

请求体¶

错误¶

组织群组¶

列出组织群组¶

查询参数¶

获取组织群组¶

参数¶

列出组织群组成员¶

参数¶

查询参数¶

添加组织群组成员¶

参数¶

请求体¶

移除组织群组成员¶

参数¶

请求体¶

精选优惠券

相关文章