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

# Consumo de ACU

> Consulte o consumo de ACU da equipe, de grupos e por usuário em um período histórico ou no ciclo de faturamento atual.

<Info>
  Esta documentação é destinada às implantações federais do Devin. [Voltar para a documentação do Devin](/pt-BR/get-started/devin-intro)
</Info>

Consulte o consumo de ACU com uma requisição tipada ao endpoint Analytics. A resposta pode incluir um total da equipe, totais de até 100 grupos selecionados e linhas paginadas por usuário para toda a equipe ou para um grupo.

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

Requer a permissão **Analytics Read** e um nível de equipe com acesso à API de análises. Consulte a [visão geral da API](/pt-BR/federal/api/overview) para obter detalhes sobre autenticação, paginação e erros e [Limites de ACU](/pt-BR/federal/acu-limits) para entender como o consumo se relaciona à aplicação.

<Note>
  Uma requisição pode conter a `acu_consumption_query` tipada descrita aqui ou as `query_requests` personalizadas legadas, mas não ambas.
</Note>

***

<div id="request">
  ## Requisição
</div>

<ParamField body="service_key" type="string" required>
  Sua chave de serviço com a permissão Analytics Read.
</ParamField>

<ParamField body="start_timestamp" type="string">
  Início de um período histórico no formato RFC 3339 (por exemplo, `2025-01-01T00:00:00Z`). Obrigatório para consultas `historical`; deve ser omitido em consultas `current_cycle`.
</ParamField>

<ParamField body="end_timestamp" type="string">
  Fim de um período histórico no formato RFC 3339. O período é inclusivo e pode abranger no máximo 90 dias.
</ParamField>

<ParamField body="acu_consumption_query" type="object" required>
  A consulta tipada de consumo de ACUs.

  <Expandable title="Objeto de consulta de consumo de ACUs">
    <ParamField body="historical" type="object">
      Consulta um período histórico definido pelos campos `start_timestamp` e `end_timestamp` de nível superior. Passe um objeto vazio: `"historical": {}`. Exatamente um dos campos `historical` ou `current_cycle` é obrigatório.
    </ParamField>

    <ParamField body="current_cycle" type="object">
      Consulta o uso quase em tempo real no ciclo de faturamento atual. Passe um objeto vazio: `"current_cycle": {}`. Os timestamps de nível superior devem ser omitidos.
    </ParamField>

    <ParamField body="include_team_total" type="boolean">
      Inclui o total de ACUs de toda a equipe. Não disponível para chaves com escopo de grupo.
    </ParamField>

    <ParamField body="group_ids" type="array">
      Até 100 IDs de grupo a serem incluídos como totais por grupo. Grupos desconhecidos, de outras equipes ou fora do escopo retornam `not_found`. Uma chave de serviço com escopo de grupo pode solicitar apenas o grupo atribuído.
    </ParamField>

    <ParamField body="user_scope" type="object">
      Solicita linhas de ACUs por usuário para um escopo.

      <Expandable title="Objeto de escopo de usuário">
        <ParamField body="team" type="object">
          Linhas por usuário de toda a equipe. Passe um objeto vazio: `"team": {}`. Não disponível para chaves com escopo de grupo.
        </ParamField>

        <ParamField body="group_id" type="string">
          Linhas por usuário para um grupo. O grupo também deve estar listado em `group_ids`.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="page_size" type="integer">
      Linhas de usuários por página, de 1 a 1.000. O padrão é 100.
    </ParamField>

    <ParamField body="page_token" type="string">
      Token do `next_page_token` de uma resposta anterior. Todos os outros campos da consulta devem permanecer inalterados.
    </ParamField>
  </Expandable>
</ParamField>

<div id="response">
  ## Resposta
</div>

<ResponseField name="acu_consumption" type="object">
  <Expandable title="Resultado do consumo de ACUs">
    <ResponseField name="team" type="object">
      Resultados de toda a equipe. `total_acus` é incluído quando `include_team_total` foi definido; `user_rows` é preenchido quando `user_scope.team` foi solicitado.
    </ResponseField>

    <ResponseField name="groups" type="array">
      Uma entrada para cada grupo solicitado: `group_id`, `group_name`, `total_acus` e `user_rows` (preenchido para o grupo selecionado em `user_scope.group_id`).
    </ResponseField>

    <ResponseField name="next_page_token" type="string">
      Incluído quando há mais linhas de usuários. Válido por 24 horas.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      `period_start`, `period_end`, `generated_at`, `team_id`, os `group_ids` solicitados e o `billing_mode` da equipe.
    </ResponseField>
  </Expandable>
</ResponseField>

Cada linha de usuário contém:

| Campo            | Descrição                                                                                                                                                                                            |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_id`        | ID de usuário estável e não confidencial.                                                                                                                                                            |
| `email`          | O e-mail do usuário, quando disponível.                                                                                                                                                              |
| `current_member` | Indica se o usuário é atualmente um membro ativo da equipe. As linhas com escopo de grupo são selecionadas com base na associação atual ao grupo, mas essa flag ainda informa a associação à equipe. |
| `total_acus`     | ACUs consumidas pelo usuário durante o período.                                                                                                                                                      |

<div id="behavior">
  ## Comportamento
</div>

* **A atribuição por grupo usa a associação atual.** Os totais dos grupos e as linhas de usuários por grupo refletem quem faz parte do grupo agora, e não quem fazia parte dele durante o período. Usuários presentes em vários grupos solicitados são contabilizados em cada um deles.
* **As linhas da equipe mantêm ex-usuários.** As linhas de usuários no escopo da equipe incluem usuários que posteriormente saíram da equipe ou que não puderam ser identificados; a flag `current_member` deles é `false`.
* **Apenas usuários com uso de ACU são exibidos.** Usuários sem consumo de ACU no período são omitidos das linhas de usuários.
* **Histórico vs. ciclo atual.** As janelas históricas abrangem até 90 dias, inclusive, de uso registrado. `current_cycle` retorna o uso quase em tempo real do ciclo de faturamento ativo; se a equipe não tiver limites de ciclo ativos, os campos de período nos metadados refletirão isso.
* **Consistência.** Os totais e a página de linhas de usuários em uma única resposta são calculados a partir de um snapshot consistente.

<div id="examples">
  ## Exemplos
</div>

<div id="team-total-and-per-user-rows-for-the-current-cycle">
  ### Linhas de total da equipe e por usuário no ciclo atual
</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">
  ### Detalhamento histórico por grupo
</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"
    }
  }
}
```