ACU 用量 - Devin Docs

本文档适用于 Devin 的联邦部署。返回 Devin 文档

通过 Analytics 端点发送类型化请求，查询 ACU 用量。响应可包含团队级总计、最多 100 个选定组的总计，以及整个团队或单个组中分页返回的用户级数据行。

POST https://<your-server>/api/v1/Analytics

需要具备 Analytics Read 权限，且团队层级已启用分析 API 访问权限。有关身份验证、分页和错误详情，请参阅 API 概述；有关用量与强制执行之间的关系，请参阅 ACU 限制。

一个请求可以包含此处所述的类型化 acu_consumption_query 或旧版自定义 query_requests，但不能同时包含两者。

请求

string

必填

具有 Analytics Read 权限的服务密钥。

string

RFC 3339 格式的历史时间窗口起始时间 (例如 2025-01-01T00:00:00Z) 。historical 查询必填；current_cycle 查询必须省略。

string

RFC 3339 格式的历史时间窗口结束时间。该时间窗口包含起止时间，最长不得超过 90 天。

object

必填

有类型的 ACU 用量查询。

显示 ACU 用量查询对象

object

查询由顶层 start_timestamp 和 end_timestamp 定义的历史时间窗口。传入空对象："historical": {}。historical 和 current_cycle 必须且只能提供其中一个。

object

查询当前账单周期的近实时用量。传入空对象："current_cycle": {}。必须省略顶层时间戳。

boolean

包含团队级 ACU 总量。组作用域密钥不可用。

array

最多可包含 100 个组 ID，并返回各组的总量。未知、跨团队或超出作用域的组会返回 not_found。组作用域服务密钥只能请求分配给它的组。

object

请求某个作用域内的用户级 ACU 数据行。

显示用户作用域对象

object

整个团队的用户级数据行。传入空对象："team": {}。组作用域密钥不可用。

string

单个组的用户级数据行。该组也必须列在 group_ids 中。

integer

每页的用户级数据行数，范围为 1–1,000。默认为 100。

string

上一个响应中的 next_page_token 令牌。所有其他查询字段必须保持不变。

响应

object

显示 ACU 用量结果

object

团队级结果。设置 include_team_total 时会提供 total_acus；请求 user_scope.team 时会填充 user_rows。

array

每个请求的组对应一个条目：group_id、group_name、total_acus 和 user_rows (仅为 user_scope.group_id 中指定的组填充) 。

string

有更多用户级数据行时提供。有效期为 24 小时。

object

period_start、period_end、generated_at、team_id、请求的 group_ids 以及团队的 billing_mode。

每条用户级数据行包含：

字段	描述
`user_id`	稳定的非敏感用户 ID。
`email`	用户的电子邮件地址 (如果可以解析) 。
`current_member`	用户当前是否为团队的活跃成员。组作用域的记录从当前组成员中选取，但此开关仍反映团队成员资格。
`total_acus`	用户在该期间消耗的 ACU 数量。

行为

组归属按当前成员关系计算。 组总计和组用户级数据行反映的是当前属于该组的用户，而非该期间内的成员。属于多个所请求组的用户会在每个组中计入。
团队行保留原成员。 团队作用域内的用户级数据行包括后来离开团队或无法解析的用户；其 current_member 开关为 false。
仅显示有 ACU 用量的用户。 期间内没有 ACU 消耗的用户不会出现在用户级数据行中。
历史周期与当前周期。 历史时间窗口最多涵盖 90 天 (含首尾) 的已记录用量。current_cycle 返回当前账单周期的近实时用量；如果团队没有有效的当前周期边界，元数据中的期间字段会反映这一情况。
一致性。 单个响应中的总计和用户级数据行页面均基于同一快照计算。

示例

当前周期的团队汇总和用户级数据行

curl -X POST https://<your-server>/api/v1/Analytics \
  -H "Content-Type: application/json" \
  -d '{
    "service_key": "your_service_key",
    "acu_consumption_query": {
      "current_cycle": {},
      "include_team_total": true,
      "user_scope": {"team": {}}
    }
  }'

{
  "acuConsumption": {
    "team": {
      "totalAcus": 1240.5,
      "userRows": [
        {"userId": "user_abc", "email": "dev@agency.gov", "currentMember": true, "totalAcus": 310.2}
      ]
    },
    "nextPageToken": "…",
    "metadata": {
      "periodStart": "2025-03-01T00:00:00Z",
      "periodEnd": "2025-03-14T18:22:05Z",
      "generatedAt": "2025-03-14T18:22:05Z",
      "teamId": "team_123",
      "billingMode": "ACU_CREDIT"
    }
  }
}

按组划分的历史数据明细

curl -X POST https://<your-server>/api/v1/Analytics \
  -H "Content-Type: application/json" \
  -d '{
    "service_key": "your_service_key",
    "start_timestamp": "2025-01-01T00:00:00Z",
    "end_timestamp": "2025-03-31T23:59:59Z",
    "acu_consumption_query": {
      "historical": {},
      "group_ids": ["group_a", "group_b"],
      "user_scope": {"group_id": "group_a"}
    }
  }'

{
  "acuConsumption": {
    "groups": [
      {
        "groupId": "group_a",
        "groupName": "Engineering",
        "totalAcus": 512.0,
        "userRows": [
          {"userId": "user_abc", "email": "dev@agency.gov", "currentMember": true, "totalAcus": 96.4}
        ]
      },
      {"groupId": "group_b", "groupName": "Data Science", "totalAcus": 288.7}
    ],
    "metadata": {
      "periodStart": "2025-01-01T00:00:00Z",
      "periodEnd": "2025-03-31T23:59:59Z",
      "generatedAt": "2025-04-02T10:15:00Z",
      "teamId": "team_123",
      "groupIds": ["group_a", "group_b"],
      "billingMode": "ACU_CREDIT"
    }
  }
}

​请求

​响应

​行为

​示例

​当前周期的团队汇总和用户级数据行

​按组划分的历史数据明细

请求

响应

行为

示例

当前周期的团队汇总和用户级数据行

按组划分的历史数据明细