Vai al contenuto principale
GET
/
api
/
v2alpha
/
analytics
/
consumption
Recupera l'analisi del consumo
curl --request GET \
  --url https://server.codeium.com/api/v2alpha/analytics/consumption \
  --header 'Authorization: Bearer <token>'
{
  "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"
  }
}
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 di seguito.
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.

​
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 nei Settings del team, alla voce “Service Keys”.

​
Strategia di fatturazione

La struttura della risposta dipende dalla strategia di fatturazione del tuo team:
StrategiaCampi popolatiDescrizione
CREDITSprompt_credits, flex_creditsTeam Enterprise SaaS standard
ACUbilled_acusTeam fatturati in Agent Compute Units
Il campo message_count (all’interno di consumption) è sempre valorizzato, indipendentemente dalla strategia di fatturazione.

​
Raggruppamento e granularità

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

​
Caching

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.

​
Limiti di frequenza

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.

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 dell'ETag da 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 i dati di consumo.

Opzioni disponibili:
agent
​
granularity
enum<string>

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.

Opzioni disponibili:
daily,
monthly
​
group_by
string

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
​
models
string

Elenco separato da virgole degli UID dei modelli a cui limitare i risultati.

​
group_id
string

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

​
user_id
string

Filtra i risultati su 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 di consumo restituiti correttamente.

​
data
object[]
obbligatorio

Array di righe di dati sul consumo.

​
pagination
object
obbligatorio
​
metadata
object
obbligatorio