Vai al contenuto principale
GET
/
api
/
v2alpha
/
analytics
/
active-users
Recupera l'analisi degli utenti attivi
curl --request GET \
  --url https://server.codeium.com/api/v2alpha/analytics/active-users \
  --header 'Authorization: Bearer <token>'
{
  "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"
  }
}
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 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 <your_service_key>
La chiave di servizio deve avere l’autorizzazione Analytics Read. Creane una nelle Settings del team, 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.

​
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, 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.

Autorizzazioni

​
Authorization
string
header
obbligatorio

Una chiave di servizio con autorizzazione Analisi Read, passata come token Bearer nell'header Authorization.

Crea una chiave di servizio nelle impostazioni del team, nella sezione "Service Keys".

Intestazioni

​
If-None-Match
string

Valore ETag di una risposta precedente. Se i dati non sono cambiati, il server restituisce 304 Not Modified.

Parametri della query

​
start_date
string<date>
obbligatorio

Inizio dell'intervallo di date (incluso) nel formato YYYY-MM-DD.

​
end_date
string<date>
obbligatorio

Fine dell'intervallo di date (incluso) nel formato YYYY-MM-DD. L'intervallo non deve superare i 90 giorni.

​
product
enum<string>
obbligatorio

Prodotto di cui recuperare gli utenti attivi.

Opzioni disponibili:
agent
​
granularity
enum<string>

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.

Opzioni disponibili:
daily,
monthly
​
group_by
enum<string>

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

Opzioni disponibili:
user
​
models
string

Elenco separato da virgole degli UID dei modelli in base a cui filtrare i risultati.

​
group_id
string

Filtra i risultati per gli utenti di un gruppo specifico. La chiave di servizio deve avere accesso a questo gruppo.

​
user_id
string

Filtra i risultati per un utente specifico (UID auth).

​
page_size
integer
predefinito:1000

Numero massimo di righe da restituire per pagina.

Intervallo richiesto: 1 <= x <= 10000
​
page_cursor
string

Cursore opaco da pagination.next_page_cursor di una risposta precedente per recuperare la pagina successiva.

Risposta

Dati sugli utenti attivi restituiti correttamente.

​
data
object[]
obbligatorio

Array di righe di dati sugli utenti attivi.

​
pagination
object
obbligatorio
​
metadata
object
obbligatorio