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

# Consumo di ACU

> Recupera il consumo di ACU per team, gruppo e utente in un intervallo storico o nel ciclo di fatturazione corrente.

<Info>
  Questa documentazione è destinata alle distribuzioni federali di Devin. [Torna alla documentazione di Devin](/it/get-started/devin-intro)
</Info>

Recupera il consumo di ACU con una richiesta tipizzata all'endpoint Analytics. La risposta può includere un totale per l'intero team, i totali di un massimo di 100 gruppi selezionati e righe paginate per utente, per l'intero team o per un singolo gruppo.

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

Richiede l'autorizzazione **Analytics Read** e un livello del team con accesso all'API di analisi. Consulta la [panoramica dell'API](/it/federal/api/overview) per informazioni su autenticazione, paginazione ed errori e [Limiti ACU](/it/federal/acu-limits) per capire in che modo il consumo è correlato all'applicazione.

<Note>
  Una richiesta può contenere la query tipizzata `acu_consumption_query` descritta qui oppure la query personalizzata legacy `query_requests`, ma non entrambe.
</Note>

***

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

<ParamField body="service_key" type="string" required>
  La tua chiave di servizio con l'autorizzazione Analytics Read.
</ParamField>

<ParamField body="start_timestamp" type="string">
  Inizio di un intervallo storico in formato RFC 3339 (ad esempio `2025-01-01T00:00:00Z`). Obbligatorio per le query `historical`; deve essere omesso per le query `current_cycle`.
</ParamField>

<ParamField body="end_timestamp" type="string">
  Fine di un intervallo storico in formato RFC 3339. L'intervallo è inclusivo e può coprire al massimo 90 giorni.
</ParamField>

<ParamField body="acu_consumption_query" type="object" required>
  La query tipizzata per il consumo di ACU.

  <Expandable title="Oggetto query per il consumo di ACU">
    <ParamField body="historical" type="object">
      Recupera un intervallo storico definito da `start_timestamp` e `end_timestamp` di primo livello. Passa un oggetto vuoto: `"historical": {}`. È obbligatorio specificare esattamente uno tra `historical` e `current_cycle`.
    </ParamField>

    <ParamField body="current_cycle" type="object">
      Recupera l'utilizzo quasi in tempo reale per il ciclo di fatturazione corrente. Passa un oggetto vuoto: `"current_cycle": {}`. I timestamp di primo livello devono essere omessi.
    </ParamField>

    <ParamField body="include_team_total" type="boolean">
      Include il totale di ACU dell'intero team. Non disponibile per le chiavi con ambito di gruppo.
    </ParamField>

    <ParamField body="group_ids" type="array">
      Fino a 100 ID di gruppo da includere come totali per gruppo. I gruppi sconosciuti, appartenenti a un altro team o esterni all'ambito restituiscono `not_found`. Una chiave di servizio con ambito di gruppo può richiedere solo il gruppo assegnato.
    </ParamField>

    <ParamField body="user_scope" type="object">
      Richiede righe ACU per utente per un ambito.

      <Expandable title="Oggetto ambito utente">
        <ParamField body="team" type="object">
          Righe per utente per l'intero team. Passa un oggetto vuoto: `"team": {}`. Non disponibile per le chiavi con ambito di gruppo.
        </ParamField>

        <ParamField body="group_id" type="string">
          Righe per utente per un gruppo. Il gruppo deve essere elencato anche in `group_ids`.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="page_size" type="integer">
      Righe utente per pagina, da 1 a 1.000. Il valore predefinito è 100.
    </ParamField>

    <ParamField body="page_token" type="string">
      Token dal campo `next_page_token` di una risposta precedente. Tutti gli altri campi della query devono rimanere invariati.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="acu_consumption" type="object">
  <Expandable title="Risultato del consumo di ACU">
    <ResponseField name="team" type="object">
      Risultati per l'intero team. `total_acus` è presente se è stato impostato `include_team_total`; `user_rows` viene popolato se è stato richiesto `user_scope.team`.
    </ResponseField>

    <ResponseField name="groups" type="array">
      Una voce per ogni gruppo richiesto: `group_id`, `group_name`, `total_acus` e `user_rows` (popolato per il gruppo selezionato in `user_scope.group_id`).
    </ResponseField>

    <ResponseField name="next_page_token" type="string">
      Presente quando sono disponibili altre righe utente. Valido per 24 ore.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      `period_start`, `period_end`, `generated_at`, `team_id`, gli `group_ids` richiesti e il `billing_mode` del team.
    </ResponseField>
  </Expandable>
</ResponseField>

Ogni riga utente contiene:

| Campo            | Descrizione                                                                                                                                                                                                      |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_id`        | ID utente stabile e non segreto.                                                                                                                                                                                 |
| `email`          | L'indirizzo email dell'utente, se disponibile.                                                                                                                                                                   |
| `current_member` | Indica se l'utente è attualmente un membro attivo del team. Le righe con ambito di gruppo vengono selezionate in base all'appartenenza attuale al gruppo, ma questo flag indica comunque l'appartenenza al team. |
| `total_acus`     | ACU consumate dall'utente nel periodo.                                                                                                                                                                           |

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

* **L'attribuzione ai gruppi si basa sull'appartenenza attuale.** I totali dei gruppi e le righe degli utenti nei gruppi riflettono chi ne fa parte ora, non chi ne faceva parte durante il periodo. Gli utenti presenti in più gruppi richiesti vengono conteggiati in ciascuno di essi.
* **Le righe del team mantengono gli ex utenti.** Le righe degli utenti nell'ambito del team includono gli utenti che hanno successivamente lasciato il team o che non è stato possibile identificare; il flag `current_member` è impostato su `false`.
* **Vengono visualizzati solo gli utenti con utilizzo di ACU.** Gli utenti senza consumo di ACU nel periodo sono omessi dalle righe degli utenti.
* **Storico e ciclo attuale.** Le finestre storiche coprono fino a 90 giorni inclusi di utilizzo registrato. `current_cycle` restituisce l'utilizzo quasi in tempo reale per il ciclo di fatturazione attivo; se il team non ha limiti attivi per il ciclo, i campi del periodo nei metadati lo indicano.
* **Coerenza.** I totali e la pagina delle righe degli utenti in una singola risposta vengono calcolati a partire da un unico snapshot coerente.

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

<div id="team-total-and-per-user-rows-for-the-current-cycle">
  ### Righe del totale del team e per utente per il ciclo attuale
</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">
  ### Ripartizione storica per gruppo
</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"
    }
  }
}
```