ACU Consumption - Devin Docs

This documentation is for the federal deployments of Devin. Back to Devin Docs

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 for authentication, pagination, and error details, and ACU Limits for how consumption relates to enforcement.

A request may contain either the typed acu_consumption_query described here or the legacy custom query_requests, but not both.

Request

string

required

Your service key with the Analytics Read permission.

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.

string

End of a historical window in RFC 3339 format. The window is inclusive and may span at most 90 days.

object

required

The typed ACU consumption query.

Show ACU consumption query object

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.

object

Query near-real-time usage for the current billing cycle. Pass an empty object: "current_cycle": {}. The top-level timestamps must be omitted.

boolean

Include the team-wide ACU total. Not available to group-scoped keys.

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.

object

Requests per-user ACU rows for one scope.

Show User scope object

object

Per-user rows across the whole team. Pass an empty object: "team": {}. Not available to group-scoped keys.

string

Per-user rows for one group. The group must also be listed in group_ids.

integer

User rows per page, 1–1,000. Defaults to 100.

string

Token from a previous response’s next_page_token. All other query fields must be unchanged.

Response

object

Show ACU consumption result

object

Team-wide results. total_acus is present when include_team_total was set; user_rows is populated when user_scope.team was requested.

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).

string

Present when more user rows exist. Valid for 24 hours.

object

period_start, period_end, generated_at, team_id, the requested group_ids, and the team’s billing_mode.

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

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

Historical per-group breakdown

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

​Request

​Response

​Behavior

​Examples

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

​Historical per-group breakdown

Request

Response

Behavior

Examples

Team total and per-user rows for the current cycle

Historical per-group breakdown