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

# ACU Consumption

> Query team, group, and per-user ACU consumption over a historical window or the current billing cycle.

<Info>
  This documentation is for the federal deployments of Devin. [Back to Devin Docs](/get-started/devin-intro)
</Info>

Query ACU consumption with a typed request on the Analytics endpoint. The response can include a team-wide total, totals for up to 100 selected groups, and paginated per-user rows for either the whole team or one group.

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

Requires the **Analytics Read** permission and a team tier with analytics API access. See the [API overview](/federal/api/overview) for authentication, pagination, and error details, and [ACU Limits](/federal/acu-limits) for how consumption relates to enforcement.

<Note>
  A request may contain either the typed `acu_consumption_query` described here or the legacy custom `query_requests`, but not both.
</Note>

***

## Request

<ParamField body="service_key" type="string" required>
  Your service key with the Analytics Read permission.
</ParamField>

<ParamField body="start_timestamp" type="string">
  Start of a historical window in RFC 3339 format (for example `2025-01-01T00:00:00Z`). Required for `historical` queries; must be omitted for `current_cycle` queries.
</ParamField>

<ParamField body="end_timestamp" type="string">
  End of a historical window in RFC 3339 format. The window is inclusive and may span at most 90 days.
</ParamField>

<ParamField body="acu_consumption_query" type="object" required>
  The typed ACU consumption query.

  <Expandable title="ACU consumption query object">
    <ParamField body="historical" type="object">
      Query a historical window defined by the top-level `start_timestamp` and `end_timestamp`. Pass an empty object: `"historical": {}`. Exactly one of `historical` or `current_cycle` is required.
    </ParamField>

    <ParamField body="current_cycle" type="object">
      Query near-real-time usage for the current billing cycle. Pass an empty object: `"current_cycle": {}`. The top-level timestamps must be omitted.
    </ParamField>

    <ParamField body="include_team_total" type="boolean">
      Include the team-wide ACU total. Not available to group-scoped keys.
    </ParamField>

    <ParamField body="group_ids" type="array">
      Up to 100 group IDs to include as per-group totals. Unknown, cross-team, or out-of-scope groups return `not_found`. A group-scoped service key may request only its assigned group.
    </ParamField>

    <ParamField body="user_scope" type="object">
      Requests per-user ACU rows for one scope.

      <Expandable title="User scope object">
        <ParamField body="team" type="object">
          Per-user rows across the whole team. Pass an empty object: `"team": {}`. Not available to group-scoped keys.
        </ParamField>

        <ParamField body="group_id" type="string">
          Per-user rows for one group. The group must also be listed in `group_ids`.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="page_size" type="integer">
      User rows per page, 1–1,000. Defaults to 100.
    </ParamField>

    <ParamField body="page_token" type="string">
      Token from a previous response's `next_page_token`. All other query fields must be unchanged.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="acu_consumption" type="object">
  <Expandable title="ACU consumption result">
    <ResponseField name="team" type="object">
      Team-wide results. `total_acus` is present when `include_team_total` was set; `user_rows` is populated when `user_scope.team` was requested.
    </ResponseField>

    <ResponseField name="groups" type="array">
      One entry per requested group: `group_id`, `group_name`, `total_acus`, and `user_rows` (populated for the group selected in `user_scope.group_id`).
    </ResponseField>

    <ResponseField name="next_page_token" type="string">
      Present when more user rows exist. Valid for 24 hours.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      `period_start`, `period_end`, `generated_at`, `team_id`, the requested `group_ids`, and the team's `billing_mode`.
    </ResponseField>
  </Expandable>
</ResponseField>

Each user row contains:

| Field            | Description                                                                                                                                                            |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_id`        | Stable, non-secret user ID.                                                                                                                                            |
| `email`          | The user's email, when resolvable.                                                                                                                                     |
| `current_member` | Whether the user is currently an active member of the team. Group-scoped rows are selected from current group membership, but this flag still reports team membership. |
| `total_acus`     | ACUs consumed by the user within the period.                                                                                                                           |

## Behavior

* **Group attribution uses current membership.** Group totals and group user rows reflect who is in the group now, not who was in it during the period. Users in multiple requested groups are counted in each.
* **Team rows retain former users.** Team-scoped user rows include users who have since left the team or could not be resolved; their `current_member` flag is `false`.
* **Only users with ACU usage appear.** Users with no ACU consumption in the period are omitted from user rows.
* **Historical vs. current cycle.** Historical windows cover up to 90 inclusive days of recorded usage. `current_cycle` returns near-real-time usage for the active billing cycle; if the team has no active cycle bounds, the metadata period fields reflect that.
* **Consistency.** Totals and the user-row page in a single response are computed from one consistent snapshot.

## Examples

### Team total and per-user rows for the current cycle

```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"
    }
  }
}
```

### Historical per-group breakdown

```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"
    }
  }
}
```