API d’utilisation

GET /v1/usage renvoie les données agrégées sur les jetons et les coûts de la clé API figurant dans l’en-tête Authorization. Regroupez les données par jour ou par heure ; vous pouvez aussi les ventiler par modèle. Vous ne pouvez pas lire les données d’une autre clé — pour cela, connectez-vous au tableau de bord.

Authentification

Transmettez votre clé API Kunavo en tant que jeton Bearer : il s’agit de la même clé dont vous voulez consulter l’utilisation. Le point de terminaison renvoie uniquement l’utilisation facturée à cette clé précise — aucun paramètre ne permet de demander les données d’une autre clé.

Requête

Exemples

Totaux quotidiens sur les 30 derniers jours, tous modèles confondus :

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

Une ligne par couple (jour, modèle) :

# 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 — additionner les valeurs de la période pour obtenir un seul nombre :

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']}")

Réponse

200 OK — application/json avec une liste de lignes. Les intervalles sans activité sont omis ; le client comble les lacunes s’il a besoin d’une série continue.

{
  "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"
    }
  ]
}

Mise en cache côté client

Le point de terminaison définit Cache-Control: private, max-age=60. La plupart des clients (navigateurs, requêtes avec session, tout cache HTTP de votre côté) renverront la même réponse pour les mêmes paramètres pendant une fenêtre de 60 secondes — ce qui convient aux tableaux de bord qui interrogent l’API à intervalles réguliers. Pour forcer une nouvelle lecture, modifiez la chaîne de requête (par exemple en ajoutant un paramètre &_=ts de contournement du cache) ou transmettez Cache-Control: no-cache de votre côté.

Erreurs

Réserves

• Clés supprimées. Lorsque vous révoquez une clé API, les lignes d’utilisation antérieures perdent leur api_key_id (défini sur null) ; leurs totaux historiques ne peuvent alors plus être récupérés via ce point de terminaison. Les données restent disponibles dans la vue agrégée du compte du tableau de bord. Si vous avez besoin d’une piste d’audit immuable par clé, récupérez et stockez les données avant de la révoquer.
• Quasi temps réel. Les lignes sont disponibles quelques secondes après la fin de l’appel concerné. Aucun délai maximal de mise à jour n’est garanti ; si vous devez faire correspondre les données exactement à votre facture, interrogez les données de la veille une fois par jour plutôt qu’à la minute.
• Le coût correspond au montant facturé. La valeur cost_usd correspond ici au montant débité de votre portefeuille. Elle tient déjà compte du plancher max(catalog, upstream × markup) décrit dans Facturation. Cette réponse ne contient aucun montant « de gros » distinct.

Étapes suivantes

• Facturation et registre — comment le cost_usd de chaque appel est calculé avant d’apparaître ici.
• Authentification — créer de nouvelles clés API (une par projet).
• Vue d’utilisation du tableau de bord — mêmes données avec des graphiques, le détail par appel et une agrégation globale pour toutes vos clés.