> ## 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 gli utenti attivi
> Recupera il numero di utenti attivi distinti del tuo team, con granularità temporale facoltativa e raggruppamento per utente.
Questo è un **endpoint v2** che usa l'autenticazione tramite token Bearer e parametri di query, a differenza dell'API di analisi v1, che usa chiavi di servizio nel corpo della richiesta. Vedi [Autenticazione](#authentication) di seguito.
Questo endpoint **non** è pensato per monitorare l'utilizzo in tempo reale. I dati sono aggregati su base oraria e il
limite di richieste è basso (10 richieste all'ora per team). Usalo per report periodici ed esportazioni in blocco.
## Autenticazione
Questo endpoint utilizza l'autenticazione con **Bearer token**. Includi la tua chiave di servizio nell'header `Authorization`:
```
Authorization: Bearer
```
La chiave di servizio deve avere l'autorizzazione **Analytics Read**. Creane una nelle [Settings del team](https://windsurf.com/team/settings), nella sezione "Service Keys".
## Cosa si intende per utente attivo
Un utente è conteggiato come **attivo** per un determinato intervallo di tempo se al suo interno è presente un qualsiasi evento di fatturazione. Il
campo `active_users` riporta il numero di utenti distinti.
Il conteggio degli utenti attivi include l'utilizzo di **sia Devin CLI che Devin Desktop**. Un utente che è
attivo in uno dei due (o in entrambi) viene conteggiato, ma solo una volta per ciascun intervallo di tempo.
## Raggruppamento e granularità
Usa `granularity` e `group_by` per controllare la struttura dei dati restituiti:
* **Nessuna granularità o raggruppamento** — restituisce una singola riga con il numero totale di utenti attivi per l'intero intervallo di date
* **`granularity=daily`** — ogni riga include un `timestamp` nel formato `YYYY-MM-DD` (utenti attivi giornalieri)
* **`granularity=monthly`** — ogni riga include un `timestamp` nel formato `YYYY-MM` (utenti attivi mensili)
* **`group_by=user`** — restituisce una riga per ciascun utente attivo con un `user_id`; in ogni riga, `active_users` è `1`
A differenza di [Get Consumption](/it/desktop/accounts/api-reference/get-consumption), l'endpoint degli utenti attivi
supporta solo `user` come valore per `group_by`. Le altre dimensioni (`model_uid`, `ide`) qui non sono valide.
I risultati sono paginati con una dimensione di pagina predefinita 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 richiesta ai fini del tuo limite di richieste.
## Cache
Le risposte includono un header `ETag`. Per evitare trasferimenti di dati non necessari, includi l'header `If-None-Match`
con il valore `ETag` precedente: il server restituirà `304 Not Modified` se i dati non sono cambiati.
## Limiti di frequenza
Questo endpoint è soggetto a un limite di **10 richieste all'ora** per team. Se si supera questo limite, il
server restituisce `429 Too Many Requests` con l'header `Retry-After`.
La paginazione di una query precedente (seguendo un `next_page_cursor`) **non** viene conteggiata ai fini di questo limite —
solo la query iniziale per ciascun report lo è. Il limite ridotto riflette il fatto che questo endpoint è destinato
alla reportistica periodica, non al monitoraggio dell'utilizzo in tempo reale.
## OpenAPI
````yaml it/desktop/accounts/api-reference/analytics-v2-openapi.yaml GET /api/v2alpha/analytics/active-users
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/active-users:
get:
summary: Recupera l'analisi degli utenti attivi
description: >
Recupera il numero di utenti attivi distinti per il team autenticato. Un
utente viene conteggiato come attivo per una determinata finestra
temporale se al suo interno è presente almeno un evento di fatturazione.
I risultati provengono da eventi di fatturazione aggregati su base
oraria e possono essere filtrati per intervallo di date, prodotto,
modello e gruppo.
Usa `granularity` per suddividere il conteggio per giorno o per mese e
`group_by=user` per restituire una riga per utente (il campo
`active_users` di ogni riga sarà `1`).
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: getActiveUsers
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 gli utenti attivi.
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, il conteggio degli utenti attivi viene aggregato
sull'intero intervallo di date.
- name: group_by
in: query
required: false
schema:
type: string
enum:
- user
description: >
Dimensione in base a cui raggruppare i risultati. L'endpoint degli
utenti attivi supporta solo `user`, che restituisce
una riga per ogni utente attivo (ciascuna con `active_users` = `1`).
example: user
- name: models
in: query
required: false
schema:
type: string
description: >-
Elenco separato da virgole degli UID dei modelli in base a cui
filtrare i risultati.
example: claude-4-sonnet,gpt-4.1
- name: group_id
in: query
required: false
schema:
type: string
description: >-
Filtra i risultati per gli 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 per 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 ETag di una risposta precedente. Se i dati non sono cambiati,
il server restituisce `304 Not Modified`.
responses:
'200':
description: Dati sugli utenti attivi 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/ActiveUsersResponse'
examples:
aggregate:
summary: Totale degli utenti attivi nell'intervallo di date
value:
data:
- active_users: 142
pagination:
next_page_cursor: null
metadata:
data_freshness: '2026-01-16T03:00:00.000Z'
query_time_ms: 612
team_id: team_abc123
daily:
summary: Utenti attivi giornalieri
value:
data:
- timestamp: '2026-01-15T00:00:00.000Z'
active_users: 138
- timestamp: '2026-01-16T00:00:00.000Z'
active_users: 145
pagination:
next_page_cursor: null
metadata:
data_freshness: '2026-01-16T03:00:00.000Z'
query_time_ms: 734
team_id: team_abc123
by_user:
summary: Raggruppato per utente
value:
data:
- user_id: user_abc123
active_users: 1
- user_id: user_def456
active_users: 1
pagination:
next_page_cursor: null
metadata:
data_freshness: '2026-01-16T03:00:00.000Z'
query_time_ms: 845
team_id: team_abc123
'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
bad_group_by:
value:
error: 'unsupported group_by dimension for active-users: model_uid'
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).
L'impaginazione di una query precedente non viene conteggiata ai
fini di questo limite.
headers:
Retry-After:
schema:
type: string
description: Tempo di attesa suggerito 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:
ActiveUsersResponse:
type: object
required:
- data
- pagination
- metadata
properties:
data:
type: array
items:
$ref: '#/components/schemas/ActiveUsersRow'
description: Array di righe di dati sugli utenti attivi.
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:
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 si applicano i risultati. Presente solo se
è stato fornito `group_id`.
Error:
type: object
required:
- error
properties:
error:
type: string
description: Messaggio di errore comprensibile all'utente.
ActiveUsersRow:
type: object
required:
- active_users
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`.
active_users:
type: integer
format: int64
description: >
Numero di utenti attivi distinti nella riga. Un utente viene
conteggiato come attivo per un intervallo temporale se
ha almeno un evento di fatturazione al suo interno. Quando il
raggruppamento è per `user`, questo valore è sempre `1`.
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".
````