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

> Consulta el consumo de ACU del equipo, los grupos y cada usuario durante un período histórico o el ciclo de facturación actual.

<Info>
  Esta documentación corresponde a los despliegues federales de Devin. [Volver a la documentación de Devin](/es/get-started/devin-intro)
</Info>

Consulta el consumo de ACU mediante una solicitud tipada al endpoint de Analytics. La respuesta puede incluir un total para todo el equipo, totales de hasta 100 grupos seleccionados y filas paginadas por usuario para todo el equipo o para un grupo.

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

Requiere el permiso **Analytics Read** y un nivel de equipo con acceso a la API de analytics. Consulta la [descripción general de la API](/es/federal/api/overview) para conocer los detalles sobre autenticación, paginación y errores, y [Límites de ACU](/es/federal/acu-limits) para entender cómo se relaciona el consumo con la aplicación de políticas.

<Note>
  Una solicitud puede contener la `acu_consumption_query` tipada que se describe aquí o la `query_requests` personalizada heredada, pero no ambas.
</Note>

***

<div id="request">
  ## Solicitud
</div>

<ParamField body="service_key" type="string" required>
  Tu clave de servicio con el permiso Analytics Read.
</ParamField>

<ParamField body="start_timestamp" type="string">
  Inicio de un período histórico en formato RFC 3339 (por ejemplo, `2025-01-01T00:00:00Z`). Obligatorio para las consultas `historical`; debe omitirse en las consultas `current_cycle`.
</ParamField>

<ParamField body="end_timestamp" type="string">
  Fin de un período histórico en formato RFC 3339. El período es inclusivo y puede abarcar un máximo de 90 días.
</ParamField>

<ParamField body="acu_consumption_query" type="object" required>
  La consulta tipada de consumo de ACU.

  <Expandable title="Objeto de consulta de consumo de ACU">
    <ParamField body="historical" type="object">
      Consulta un período histórico definido por los campos de nivel superior `start_timestamp` y `end_timestamp`. Pasa un objeto vacío: `"historical": {}`. Se requiere exactamente uno de `historical` o `current_cycle`.
    </ParamField>

    <ParamField body="current_cycle" type="object">
      Consulta el uso casi en tiempo real del ciclo de facturación actual. Pasa un objeto vacío: `"current_cycle": {}`. Deben omitirse las marcas de tiempo de nivel superior.
    </ParamField>

    <ParamField body="include_team_total" type="boolean">
      Incluye el total de ACU de todo el equipo. No está disponible para claves con ámbito de grupo.
    </ParamField>

    <ParamField body="group_ids" type="array">
      Hasta 100 ID de grupo que se incluirán como totales por grupo. Los grupos desconocidos, de otros equipos o fuera del ámbito devuelven `not_found`. Una clave de servicio con ámbito de grupo solo puede solicitar el grupo que tiene asignado.
    </ParamField>

    <ParamField body="user_scope" type="object">
      Solicita filas de ACU por usuario para un ámbito.

      <Expandable title="Objeto de ámbito de usuario">
        <ParamField body="team" type="object">
          Filas por usuario de todo el equipo. Pasa un objeto vacío: `"team": {}`. No está disponible para claves con ámbito de grupo.
        </ParamField>

        <ParamField body="group_id" type="string">
          Filas por usuario de un grupo. El grupo también debe figurar en `group_ids`.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="page_size" type="integer">
      Filas de usuario por página, de 1 a 1.000. El valor predeterminado es 100.
    </ParamField>

    <ParamField body="page_token" type="string">
      Token del `next_page_token` de una respuesta anterior. Todos los demás campos de la consulta deben permanecer sin cambios.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="acu_consumption" type="object">
  <Expandable title="Resultado del consumo de ACU">
    <ResponseField name="team" type="object">
      Resultados para todo el equipo. `total_acus` está presente cuando se estableció `include_team_total`; `user_rows` se rellena cuando se solicitó `user_scope.team`.
    </ResponseField>

    <ResponseField name="groups" type="array">
      Una entrada por cada grupo solicitado: `group_id`, `group_name`, `total_acus` y `user_rows` (se rellena para el grupo seleccionado en `user_scope.group_id`).
    </ResponseField>

    <ResponseField name="next_page_token" type="string">
      Está presente cuando hay más filas de usuarios. Tiene una validez de 24 horas.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      `period_start`, `period_end`, `generated_at`, `team_id`, los `group_ids` solicitados y el `billing_mode` del equipo.
    </ResponseField>
  </Expandable>
</ResponseField>

Cada fila de usuario contiene:

| Campo            | Descripción                                                                                                                                                                                                   |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_id`        | ID de usuario estable y no confidencial.                                                                                                                                                                      |
| `email`          | La dirección de correo electrónico del usuario, si se puede resolver.                                                                                                                                         |
| `current_member` | Indica si el usuario es actualmente miembro activo del equipo. Las filas con ámbito de grupo se seleccionan según la pertenencia actual del grupo, pero esta marca sigue indicando la pertenencia del equipo. |
| `total_acus`     | ACU consumidos por el usuario durante el período.                                                                                                                                                             |

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

* **La atribución por grupo usa la pertenencia actual.** Los totales de los grupos y las filas de usuarios por grupo reflejan quién pertenece al grupo ahora, no quién pertenecía a él durante el período. Los usuarios incluidos en varios grupos solicitados se contabilizan en cada uno de ellos.
* **Las filas de equipo conservan a los usuarios anteriores.** Las filas de usuarios con ámbito de equipo incluyen a los usuarios que abandonaron el equipo o que no se pudieron resolver; su indicador `current_member` es `false`.
* **Solo aparecen los usuarios con uso de ACU.** Los usuarios sin consumo de ACU durante el período se omiten de las filas de usuarios.
* **Ciclo histórico frente al actual.** Las ventanas históricas abarcan hasta 90 días de uso registrado, ambos inclusive. `current_cycle` devuelve el uso casi en tiempo real del ciclo de facturación activo; si el equipo no tiene límites de ciclo activos, los campos de período de los metadatos lo reflejan.
* **Coherencia.** Los totales y la página de filas de usuarios de una misma respuesta se calculan a partir de una única instantánea coherente.

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

<div id="team-total-and-per-user-rows-for-the-current-cycle">
  ### Filas de total del equipo y por usuario del ciclo actual
</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">
  ### Desglose 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"
    }
  }
}
```