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

# API di analisi v2

> API di analisi di nuova generazione per interrogare i dati di consumo con autenticazione tramite token Bearer, raggruppamento flessibile e paginazione basata su cursore.

<Warning>
  Le API v2 sono in **alpha** e sono soggette a modifiche in qualsiasi momento.
</Warning>

<div id="overview">
  ## Panoramica
</div>

L'API di analisi v2 è la nuova generazione dell'API di analisi di Devin Desktop. Espone i dati di consumo
(crediti e ACU) tramite endpoint REST chiari, con filtri tramite parametri di query, raggruppamento
flessibile, paginazione basata su cursore e cache delle risposte.

<Note>
  Gli endpoint v2 sono attualmente disponibili con il prefisso **`/api/v2alpha`** mentre l'API è in fase di
  definizione finale. L'URL di base è `https://server.codeium.com`.
</Note>

<div id="whats-new-in-v2">
  ## Novità in v2
</div>

La differenza principale rispetto a [v1](/it/desktop/accounts/api-reference/analytics-api-introduction) è l'**autenticazione**.

|                | API di analisi v1                                   | API di analisi v2                                      |
| -------------- | --------------------------------------------------- | ------------------------------------------------------ |
| Trasporto      | `POST` con un corpo della richiesta in formato JSON | `GET` con parametri di query                           |
| Autenticazione | campo `service_key` **nel corpo della richiesta**   | **header `Authorization: Bearer <service_key>`**       |
| Autorizzazione | Varia in base all'endpoint                          | **Analytics Read**                                     |
| Paginazione    | Nessuna                                             | Basata su cursore (`next_page_cursor` / `page_cursor`) |
| Cache          | Nessuna                                             | `ETag` + `If-None-Match` (`304 Not Modified`)          |

<div id="authentication">
  ## Autenticazione
</div>

v2 utilizza l'autenticazione con **token Bearer**. Passa la tua chiave di servizio nell'header `Authorization` anziché
nel corpo della richiesta:

```
Authorization: Bearer <your_service_key>
```

La chiave di servizio deve disporre dell'autorizzazione **Analytics Read**.

<div id="creating-a-service-key">
  ### Creazione di una chiave di servizio
</div>

1. Vai alla [pagina Team Settings del tuo team](https://windsurf.com/team/settings)
2. Vai alla sezione "Service Keys"
3. Crea una nuova chiave di servizio con l'autorizzazione **Analytics Read**
4. Usa la chiave come token Bearer nell'header `Authorization`

<Warning>Tieni al sicuro le tue chiavi di servizio e non esporle mai nel codice lato client o in repository pubblici.</Warning>

Sono supportate chiavi di servizio con ambito di gruppo: quando una chiave è limitata a un gruppo, i risultati vengono automaticamente
limitati a quel gruppo.

<div id="available-endpoints">
  ## Endpoint disponibili
</div>

| Endpoint                                                                                                                      | Descrizione                                                                                |
| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| [Recupera il consumo](/it/desktop/accounts/api-reference/get-consumption) (`GET /api/v2alpha/analytics/consumption`)          | Recupera il consumo di crediti o ACU con filtri, raggruppamento, granularità e paginazione |
| [Recupera gli utenti attivi](/it/desktop/accounts/api-reference/get-active-users) (`GET /api/v2alpha/analytics/active-users`) | Conta gli utenti attivi univoci, facoltativamente per giorno/mese o per singolo utente     |

<div id="billing-strategy">
  ## Strategia di fatturazione
</div>

Le risposte si adattano alla strategia di fatturazione del team, indicata in `metadata.billing_strategy`:

* **`CREDITS`** — le righe includono `prompt_credits` e `flex_credits`
* **`ACU`** — le righe includono `billed_acus`

Il campo `message_count` viene sempre restituito, indipendentemente dalla strategia.

<div id="pagination">
  ## Paginazione
</div>

Le risposte che restituiscono elenchi sono paginate. Quando sono disponibili altri dati, la risposta include un
`pagination.next_page_cursor`; passalo di nuovo come parametro di query `page_cursor` per recuperare la pagina
successiva. I cursori scadono dopo 24 ore.

<div id="caching">
  ## Cache
</div>

Le risposte includono un header `ETag`. Nelle richieste successive, invialo di nuovo nell'header `If-None-Match`
per ricevere un `304 Not Modified` se i dati non sono cambiati.

<div id="rate-limits">
  ## Limiti di frequenza
</div>

<Warning>
  Questi endpoint **non** sono destinati al monitoraggio dell'utilizzo in tempo reale. I dati vengono
  aggregati su base oraria e il limite di frequenza è basso (10 richieste all'ora per team). Usali per report periodici ed esportazioni in blocco,
  non per dashboard in tempo reale o per il tracciamento delle singole richieste.
</Warning>

Gli endpoint v2 sono soggetti a un limite di frequenza di **10 richieste all'ora per team**. Se il limite viene superato, viene restituito
`429 Too Many Requests` con un header `Retry-After`.

La paginazione di una query precedente (seguendo un `next_page_cursor`) **non** viene conteggiata ai fini del
limite di frequenza — viene conteggiata solo la query iniziale per ciascun report. Il limite ridotto riflette il fatto che questi endpoint sono
pensati per report periodici, non per il monitoraggio in tempo reale.