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

# Recupera il consumo

> Interroga i dati di analisi del consumo di crediti o ACU con filtri, raggruppamenti e paginazione flessibili.

<Note>
  Questo è un **endpoint v2** che utilizza l'autenticazione tramite token Bearer e parametri di query, a differenza dell'API di analisi v1, che utilizza chiavi di servizio nel corpo della richiesta. Vedi [Autenticazione](#authentication) di seguito.
</Note>

<Warning>
  Questo endpoint **non** è pensato per il monitoraggio dell'utilizzo in tempo reale. I dati vengono aggregati su base oraria e il
  rate limit è basso (10 richieste all'ora per team). Usalo per report periodici ed esportazioni in blocco.
</Warning>

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

Questo endpoint utilizza l'autenticazione con **Bearer token**. Includi la tua chiave di servizio nell'header `Authorization`:

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

La chiave di servizio deve avere l'autorizzazione **Analytics Read**. Creane una nei [Settings del team](https://windsurf.com/team/settings), alla voce "Service Keys".

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

La struttura della risposta dipende dalla strategia di fatturazione del tuo team:

| Strategia | Campi popolati                   | Descrizione                           |
| --------- | -------------------------------- | ------------------------------------- |
| `CREDITS` | `prompt_credits`, `flex_credits` | Team Enterprise SaaS standard         |
| `ACU`     | `billed_acus`                    | Team fatturati in Agent Compute Units |

Il campo `message_count` (all'interno di `consumption`) è sempre valorizzato, indipendentemente dalla strategia di fatturazione.

<div id="grouping-and-granularity">
  ## Raggruppamento e granularità
</div>

Usa `granularity` e `group_by` per controllare la forma dei dati restituiti:

* **Nessuna granularità o raggruppamento** — restituisce una singola riga aggregata per l'intero intervallo di date
* **`granularity=daily`** — ogni riga include un `timestamp` nel formato `YYYY-MM-DD`
* **`granularity=monthly`** — ogni riga include un `timestamp` nel formato `YYYY-MM`
* **`group_by=user`** — ogni riga include un `user_id` e `user_email`
* **`group_by=user,model_uid`** — ogni riga include `user_id`, `user_email` e `model_uid`
* **`group_by=ide`** — ogni riga include un `ide`

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

I risultati sono paginati con una dimensione predefinita della pagina di 1.000 righe (max 10.000). Quando sono disponibili altri risultati,
la risposta include un `next_page_cursor` nell'oggetto `pagination`. Passalo come parametro di query `page_cursor`
per recuperare la pagina successiva.

I cursori di pagina scadono dopo 24 ore. Una richiesta per la pagina successiva non viene conteggiata come una nuova query ai fini del rate limit.

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

Le risposte includono un header `ETag`. Per evitare trasferimenti di dati ridondanti, includi l'header `If-None-Match`
con il precedente valore di `ETag` — il server restituirà `304 Not Modified` se i dati non sono cambiati.

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

Questo endpoint è soggetto a un limite di **10 richieste all'ora** per team. Se questo limite viene superato, il
server restituisce `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 di questo limite —
viene conteggiata solo la query iniziale per ciascun report. Questo limite ridotto riflette il fatto che l'endpoint è pensato per
report periodici, non per il monitoraggio dell'utilizzo in tempo reale.


## OpenAPI

````yaml it/desktop/accounts/api-reference/analytics-v2-openapi.yaml GET /api/v2alpha/analytics/consumption
openapi: 3.1.0
info:
  title: Devin Desktop Analytics API v2
  version: 2.0.0
  description: >
    L'API di analisi v2 fornisce analisi del consumo di crediti e ACU per i team
    Enterprise.

    I dati provengono da eventi di fatturazione aggregati su base oraria e
    supportano filtri flessibili, raggruppamento

    e paginazione basata su cursore.
servers:
  - url: https://server.codeium.com
security:
  - bearerAuth: []
paths:
  /api/v2alpha/analytics/consumption:
    get:
      summary: Recupera l'analisi del consumo
      description: >
        Recupera i dati di consumo di crediti o ACU per il team autenticato. I
        risultati provengono da eventi di fatturazione aggregati su base oraria
        e possono essere filtrati per intervallo di date, prodotto, modello e
        gruppo.


        La struttura della risposta dipende dalla strategia di fatturazione del
        team:

        - I team **basati sui crediti** ricevono `prompt_credits` e
        `flex_credits` in ogni riga.

        - I team **basati sulle ACU** ricevono `billed_acus` in ogni riga.


        Le risposte vengono memorizzate nella cache per 1 ora. Usa
        `If-None-Match` con un `ETag` restituito in precedenza per ricevere un
        `304 Not Modified` se i dati non sono cambiati.


        Questi endpoint sono progettati per report periodici ed esportazioni in
        blocco. **Non** sono destinati al monitoraggio dell'utilizzo in tempo
        reale: i dati sono aggregati su base oraria e il limite di frequenza è
        basso (10 richieste all'ora per team).
      operationId: getConsumption
      parameters:
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: Inizio dell'intervallo di date (incluso) nel formato `YYYY-MM-DD`.
          example: '2026-01-01T00:00:00.000Z'
        - name: end_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: >-
            Fine dell'intervallo di date (incluso) nel formato `YYYY-MM-DD`.
            L'intervallo non deve superare i 90 giorni.
          example: '2026-01-31T00:00:00.000Z'
        - name: product
          in: query
          required: true
          schema:
            type: string
            enum:
              - agent
          description: Prodotto di cui recuperare i dati di consumo.
          example: agent
        - name: granularity
          in: query
          required: false
          schema:
            type: string
            enum:
              - daily
              - monthly
          description: >
            Granularità temporale per il raggruppamento dei risultati. Se
            specificata, ogni riga include un campo `timestamp`.

            Se omessa, i risultati vengono aggregati sull'intero intervallo di
            date.
        - name: group_by
          in: query
          required: false
          schema:
            type: string
          description: >
            Elenco separato da virgole delle dimensioni in base a cui
            raggruppare i risultati. Dimensioni supportate:

            - `user` — include `user_id` e `user_email` in ogni riga

            - `model_uid` — include `model_uid` in ogni riga

            - `ide` — include `ide` in ogni riga
          example: user,model_uid
        - name: models
          in: query
          required: false
          schema:
            type: string
          description: >-
            Elenco separato da virgole degli UID dei modelli a cui limitare i
            risultati.
          example: claude-4-sonnet,gpt-4.1
        - name: group_id
          in: query
          required: false
          schema:
            type: string
          description: >-
            Filtra i risultati sugli utenti di un gruppo specifico. La chiave di
            servizio deve avere accesso a questo gruppo.
        - name: user_id
          in: query
          required: false
          schema:
            type: string
          description: Filtra i risultati su un utente specifico (UID auth).
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 10000
            default: 1000
          description: Numero massimo di righe da restituire per pagina.
        - name: page_cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            Cursore opaco da `pagination.next_page_cursor` di una risposta
            precedente per recuperare la pagina successiva.
        - name: If-None-Match
          in: header
          required: false
          schema:
            type: string
          description: >-
            Valore dell'ETag da una risposta precedente. Se i dati non sono
            cambiati, il server restituisce `304 Not Modified`.
      responses:
        '200':
          description: Dati di consumo restituiti correttamente.
          headers:
            ETag:
              schema:
                type: string
              description: >-
                Tag di entità per la convalida della cache. Passalo come
                `If-None-Match` nelle richieste successive.
            Cache-Control:
              schema:
                type: string
              description: Direttiva della cache (ad es. `private, max-age=3600`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsumptionResponse'
              examples:
                credits:
                  summary: Team basato su crediti con granularità giornaliera
                  value:
                    data:
                      - timestamp: '2026-01-15T00:00:00.000Z'
                        user_id: user_abc123
                        user_email: alice@example.com
                        consumption:
                          prompt_credits: 1250
                          flex_credits: 340
                          message_count: 87
                      - timestamp: '2026-01-15T00:00:00.000Z'
                        user_id: user_def456
                        user_email: bob@example.com
                        consumption:
                          prompt_credits: 980
                          flex_credits: 150
                          message_count: 52
                    pagination:
                      next_page_cursor: null
                    metadata:
                      billing_strategy: CREDITS
                      data_freshness: '2026-01-16T03:00:00.000Z'
                      query_time_ms: 1423
                      team_id: team_abc123
                acu:
                  summary: Team basato su ACU
                  value:
                    data:
                      - consumption:
                          billed_acus: 42.75
                          message_count: 310
                    pagination:
                      next_page_cursor: null
                    metadata:
                      billing_strategy: ACU
                      data_freshness: '2026-01-16T03:00:00.000Z'
                      query_time_ms: 892
                      team_id: team_def456
        '304':
          description: I dati non sono cambiati dall'ETag fornito in `If-None-Match`.
        '400':
          description: Parametri della richiesta non validi.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_param:
                  value:
                    error: start_date is required
                date_range:
                  value:
                    error: date range must not exceed 90 days
                bad_product:
                  value:
                    error: 'unsupported product: foo (supported: agent)'
        '401':
          description: Autenticazione non riuscita o autorizzazioni insufficienti.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_auth:
                  value:
                    error: missing Authorization header
                invalid_key:
                  value:
                    error: invalid service key
                insufficient_permissions:
                  value:
                    error: insufficient permissions
        '403':
          description: >-
            Il cursore di pagina fornito non appartiene al team autenticato o al
            gruppo richiesto.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                cursor_team_mismatch:
                  value:
                    error: page cursor does not belong to this team
        '405':
          description: Metodo HTTP non consentito (è supportato solo `GET`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            Limite di frequenza superato (10 richieste all'ora per team). La
            paginazione di una query precedente non viene conteggiata ai fini di
            questo limite.
          headers:
            Retry-After:
              schema:
                type: string
              description: Tempo di attesa consigliato prima di riprovare.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate_limited:
                  value:
                    error: rate limit exceeded
        '503':
          description: >-
            Il servizio di analisi non è disponibile (ad es. nelle distribuzioni
            self-hosted).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    ConsumptionResponse:
      type: object
      required:
        - data
        - pagination
        - metadata
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ConsumptionRow'
          description: Array di righe di dati sul consumo.
        pagination:
          type: object
          properties:
            next_page_cursor:
              type:
                - string
                - 'null'
              description: >
                Cursore opaco per recuperare la pagina successiva dei risultati.
                Passa questo valore come parametro di query `page_cursor`

                in una richiesta successiva. `null` quando non ci sono altre
                pagine.

                I cursori di pagina scadono dopo 24 ore.
        metadata:
          type: object
          properties:
            billing_strategy:
              type: string
              enum:
                - CREDITS
                - ACU
              description: >
                La strategia di fatturazione per il team autenticato. Determina
                quali campi in `consumption` vengono popolati:

                - `CREDITS` — `prompt_credits` e `flex_credits`

                - `ACU` — `billed_acus`
            data_freshness:
              type: string
              format: date-time
              description: >-
                Timestamp che indica quando i dati sottostanti sono stati
                aggiornati l'ultima volta (troncato all'ora).
            query_time_ms:
              type: integer
              format: int64
              description: Tempo di esecuzione della query sul server in millisecondi.
            team_id:
              type: string
              description: L'ID del team determinato dalla chiave di servizio autenticata.
            group_id:
              type: string
              description: >-
                L'ID del gruppo a cui sono stati limitati i risultati. Presente
                solo quando è stato fornito `group_id`.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Messaggio di errore comprensibile all'utente.
    ConsumptionRow:
      type: object
      required:
        - consumption
      properties:
        timestamp:
          type: string
          description: >
            Intervallo temporale per la riga. Il formato dipende da
            `granularity`: `YYYY-MM-DD` per il giornaliero, `YYYY-MM` per il
            mensile.

            Presente solo quando viene specificato `granularity`.
          examples:
            - '2026-05-01T00:00:00.000Z'
            - 2026-05
        user_id:
          type: string
          description: >-
            Identificatore dell'utente (UID auth). Presente solo quando
            `group_by` include `user`.
        user_email:
          type: string
          description: >-
            Indirizzo email dell'utente. Presente solo quando `group_by` include
            `user`.
          examples:
            - alice@example.com
        model_uid:
          type: string
          description: >-
            Identificatore del modello. Presente solo quando `group_by` include
            `model_uid`.
          examples:
            - claude-4-sonnet
        ide:
          type: string
          description: Nome dell'IDE. Presente solo quando `group_by` include `ide`.
          examples:
            - windsurf
            - jetbrains
        consumption:
          $ref: '#/components/schemas/Consumption'
    Consumption:
      type: object
      description: >-
        Metriche di utilizzo per la riga. I campi vengono popolati in base alla
        strategia di fatturazione del team.
      properties:
        prompt_credits:
          type: integer
          format: int64
          description: Credito prompt consumato (solo con fatturazione basata su crediti).
        flex_credits:
          type: integer
          format: int64
          description: Crediti Flex consumati (solo con fatturazione basata su crediti).
        billed_acus:
          type: number
          format: double
          description: ACU fatturati consumati (solo con fatturazione basata su ACU).
        message_count:
          type: integer
          format: int64
          description: >-
            Numero di messaggi (eventi di fatturazione) in questa riga. Sempre
            valorizzato indipendentemente dalla strategia di fatturazione.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        Una chiave di servizio con autorizzazione **Analisi Read**, passata come
        token Bearer nell'header `Authorization`.


        Crea una chiave di servizio nelle [impostazioni del
        team](https://windsurf.com/team/settings), nella sezione "Service Keys".

````