API di utilizzo

GET /v1/usage restituisce i dati aggregati su token e costi relativi alla chiave API nell’intestazione Authorization. Raggruppa per giorno o ora; facoltativamente, suddividi per modello. Non è possibile leggere i dati di un’altra chiave: per farlo, accedi alla dashboard.

Autenticazione

Passa la tua chiave API Kunavo come token Bearer: deve essere la stessa chiave di cui vuoi consultare l’utilizzo. L’endpoint restituisce solo l’utilizzo addebitato a questa specifica chiave; non esiste un parametro per richiedere i dati di un’altra chiave.

Richiesta

Esempi

Totali giornalieri degli ultimi 30 giorni, con tutti i modelli aggregati:

# Daily totals for the last 30 days
curl https://api.kunavo.com/v1/usage \
  -G \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  --data-urlencode "start_date=2026-04-28" \
  --data-urlencode "end_date=2026-05-27"

Una riga per ogni coppia (giorno, modello):

# Per-model daily breakdown — one row per (day, model)
curl https://api.kunavo.com/v1/usage \
  -G \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  --data-urlencode "start_date=2026-05-01" \
  --data-urlencode "end_date=2026-05-27" \
  --data-urlencode "group_by=model"

Python — somma l’intervallo per ottenere un unico valore:

import os, datetime as dt, requests

today = dt.date.today()
start = today - dt.timedelta(days=29)  # last 30 days inclusive

r = requests.get(
    "https://api.kunavo.com/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['KUNAVO_API_KEY']}"},
    params={
        "start_date": start.isoformat(),
        "end_date":   today.isoformat(),
        "group_by":   "model",
    },
    timeout=30,
)
r.raise_for_status()
body = r.json()

# body["data"] is one row per (day, model). Sum cost across the window:
total_usd = sum(float(row["cost_usd"]) for row in body["data"])
print(f"Spent ${total_usd:.4f} on key {body['api_key']['name']}")

Risposta

200 OK — application/json con un elenco di righe. Gli intervalli senza attività, il cui valore è zero, vengono omessi; se serve una serie continua, il client può colmare i vuoti.

{
  "object": "list",
  "api_key": {
    "id": "k_abc123",
    "name": "production",
    "prefix": "sk-kn-aZ8x"
  },
  "start_date": "2026-05-01",
  "end_date":   "2026-05-27",
  "bucket": "day",
  "data": [
    {
      "bucket_start": "2026-05-01T00:00:00.000Z",
      "model": "claude-sonnet-4-6",
      "requests": 1284,
      "errors": 7,
      "input_tokens": 1532890,
      "output_tokens": 245100,
      "cached_input_tokens": 980000,
      "cache_write_tokens": 12000,
      "web_search_requests": 0,
      "cost_usd": "3.452100"
    },
    {
      "bucket_start": "2026-05-01T00:00:00.000Z",
      "model": "gpt-5",
      "requests": 88,
      "errors": 0,
      "input_tokens": 42000,
      "output_tokens": 12300,
      "cached_input_tokens": 0,
      "cache_write_tokens": 0,
      "web_search_requests": 0,
      "cost_usd": "0.210400"
    }
  ]
}

Memorizzazione nella cache lato client

L’endpoint imposta Cache-Control: private, max-age=60. La maggior parte dei client (browser, richieste con una sessione e qualsiasi cache HTTP lato tuo) restituirà la stessa risposta per gli stessi parametri entro un intervallo di 60 secondi: una soluzione adatta alle dashboard che eseguono richieste periodiche. Per forzare una lettura aggiornata, varia la stringa di query (ad es. aggiungi un parametro &_=ts ant cache) oppure imposta Cache-Control: no-cache lato tuo.

Errori

Avvertenze

• Chiavi eliminate. Quando revochi una chiave API, alle relative righe storiche di utilizzo viene rimosso il campo api_key_id (impostato su null), quindi non è più possibile recuperare i totali storici tramite questo endpoint. I dati sono ancora disponibili nella vista aggregata dell’account nella dashboard. Se ti serve uno storico di audit per chiave non modificabile, recupera e salva i dati prima di revocarla.
• Quasi in tempo reale. Le righe vengono aggiunte entro pochi secondi dal completamento della chiamata sottostante. Non è garantito alcun limite di ritardo: se ti serve una corrispondenza esatta con la fattura, richiedi una volta al giorno i dati del giorno precedente invece di interrogarli ogni minuto.
• Il costo è quello fatturato. Il valore cost_usd qui corrisponde all’importo addebitato sul saldo del portafoglio. Include già il minimo max(catalog, upstream × markup) descritto in Fatturazione. Questa risposta non contiene un importo «all’ingrosso» separato.

Prossimi passi

• Fatturazione e registro contabile — come viene calcolato il valore cost_usd di ogni chiamata prima che venga riportato qui.
• Autenticazione — creazione di nuove chiavi API (una per progetto).
• Vista di utilizzo nella dashboard — gli stessi dati con grafici, dettagli per chiamata e aggregazione estesa a tutto l’account e a tutte le chiavi.