> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ACU 用量

> 查询团队、组和各用户在历史时间范围或当前账单周期内的 ACU 用量。

<Info>
  本文档适用于 Devin 的联邦部署。[返回 Devin 文档](/zh/get-started/devin-intro)
</Info>

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

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

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

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

***

<div id="request">
  ## 请求
</div>

<ParamField body="service_key" type="string" required>
  具有 Analytics Read 权限的服务密钥。
</ParamField>

<ParamField body="start_timestamp" type="string">
  RFC 3339 格式的历史时间窗口起始时间 (例如 `2025-01-01T00:00:00Z`) 。`historical` 查询必填；`current_cycle` 查询必须省略。
</ParamField>

<ParamField body="end_timestamp" type="string">
  RFC 3339 格式的历史时间窗口结束时间。该时间窗口包含起止时间，最长不得超过 90 天。
</ParamField>

<ParamField body="acu_consumption_query" type="object" required>
  有类型的 ACU 用量查询。

  <Expandable title="ACU 用量查询对象">
    <ParamField body="historical" type="object">
      查询由顶层 `start_timestamp` 和 `end_timestamp` 定义的历史时间窗口。传入空对象：`"historical": {}`。`historical` 和 `current_cycle` 必须且只能提供其中一个。
    </ParamField>

    <ParamField body="current_cycle" type="object">
      查询当前账单周期的近实时用量。传入空对象：`"current_cycle": {}`。必须省略顶层时间戳。
    </ParamField>

    <ParamField body="include_team_total" type="boolean">
      包含团队级 ACU 总量。组作用域密钥不可用。
    </ParamField>

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

    <ParamField body="user_scope" type="object">
      请求某个作用域内的用户级 ACU 数据行。

      <Expandable title="用户作用域对象">
        <ParamField body="team" type="object">
          整个团队的用户级数据行。传入空对象：`"team": {}`。组作用域密钥不可用。
        </ParamField>

        <ParamField body="group_id" type="string">
          单个组的用户级数据行。该组也必须列在 `group_ids` 中。
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="page_size" type="integer">
      每页的用户级数据行数，范围为 1–1,000。默认为 100。
    </ParamField>

    <ParamField body="page_token" type="string">
      上一个响应中的 `next_page_token` 令牌。所有其他查询字段必须保持不变。
    </ParamField>
  </Expandable>
</ParamField>

<div id="response">
  ## 响应
</div>

<ResponseField name="acu_consumption" type="object">
  <Expandable title="ACU 用量结果">
    <ResponseField name="team" type="object">
      团队级结果。设置 `include_team_total` 时会提供 `total_acus`；请求 `user_scope.team` 时会填充 `user_rows`。
    </ResponseField>

    <ResponseField name="groups" type="array">
      每个请求的组对应一个条目：`group_id`、`group_name`、`total_acus` 和 `user_rows` (仅为 `user_scope.group_id` 中指定的组填充) 。
    </ResponseField>

    <ResponseField name="next_page_token" type="string">
      有更多用户级数据行时提供。有效期为 24 小时。
    </ResponseField>

    <ResponseField name="metadata" type="object">
      `period_start`、`period_end`、`generated_at`、`team_id`、请求的 `group_ids` 以及团队的 `billing_mode`。
    </ResponseField>
  </Expandable>
</ResponseField>

每条用户级数据行包含：

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

<div id="behavior">
  ## 行为
</div>

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

<div id="examples">
  ## 示例
</div>

<div id="team-total-and-per-user-rows-for-the-current-cycle">
  ### 当前周期的团队汇总和用户级数据行
</div>

```bash theme={null}
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": {}}
    }
  }'
```

```json theme={null}
{
  "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"
    }
  }
}
```

<div id="historical-per-group-breakdown">
  ### 按组划分的历史数据明细
</div>

```bash theme={null}
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"}
    }
  }'
```

```json theme={null}
{
  "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"
    }
  }
}
```