Quelle clé Claude brûle votre budget ? Le tuto API en 30 min

Votre facture Claude a pris 40 % en octobre et personne ne sait pourquoi. Entre l'agent du support, le script de veille et le stagiaire qui a collé sa clé dans un notebook, impossible de dire qui consomme. Depuis le 29 octobre, Anthropic fournit enfin de quoi répondre : une Usage and Cost Analytics API en bêta. Ce tuto monte une requête, puis un petit script de contrôle hebdomadaire. Il s'adresse aux PME et freelances qui paient l'API Claude">Claude via une organisation Console.

Un point d'honnêteté : les commandes ci-dessous sont construites à partir de la documentation officielle et de la référence d'API, pas d'une exécution sur votre organisation. Lancez-les d'abord sur 2 ou 3 jours, vérifiez un total connu, puis élargissez.

Ce que la nouvelle API fait, et ce que l'ancienne ne faisait pas

Deux endpoints : GET /v1/organizations/analytics/usage pour les tokens et les requêtes, GET /v1/organizations/analytics/cost pour les dollars. Les deux acceptent les mêmes filtres et les mêmes regroupements. L'ancienne Usage and Cost API reste disponible mais Anthropic la classe désormais en « legacy » et recommande la nouvelle pour tout nouveau montage.

Le gain principal pour une PME : le regroupement du coût par api_key_id. L'ancien cost_report n'acceptait que description et workspace_id ; il y avait même une demande ouverte sur GitHub pour obtenir le coût par clé, avec pour contournement de multiplier les tokens par le prix. Fini le bricolage. La documentation liste aussi model, service_tier, speed (fast ou standard), context_window, inference_geo et actor (l'utilisateur, le compte de service ou la clé derrière la requête), jusqu'à cinq dimensions à la fois.

Autre nouveauté : l'espace de travail par défaut remonte avec son vrai identifiant wrkspc_ au lieu de null. Si votre ancien script filtrait sur null, il casse.

Prérequis : la clé Admin, et pourquoi le compte perso ne suffit pas

L'API d'administration n'existe pas pour les comptes individuels. Il faut une organisation créée dans la Console, et un membre avec le rôle admin pour générer une clé Admin (préfixe sk-ant-admin01-) depuis la page des clés Admin. Le secret n'apparaît qu'une fois. Une clé Admin ne porte aucun périmètre sélectionnable : elle ouvre tous les endpoints d'administration. Rangez-la dans un gestionnaire de secrets, jamais dans le dépôt, et donnez-lui une date d'expiration.

Côté Claude Enterprise (claude.ai), le chemin diffère : une clé avec le scope read:analytics suffit, et le regroupement par clé ou par workspace ne s'applique pas, puisque ces notions n'existent que sur la plateforme développeur.

Deux en-têtes sont obligatoires sur chaque appel : anthropic-beta: analytics-usage-cost-2026-08-24 et anthropic-version. Les SDK officiels et la CLI ant les envoient seuls et paginent à votre place.

Étape 1 : le coût par clé API sur un mois

Premier réflexe, le classement des clés les plus chères. Remplacez les dates, restez sous 31 jours par requête.

curl -G "https://api.anthropic.com/v1/organizations/analytics/cost" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: analytics-usage-cost-2026-08-24" \
  -H "Authorization: Bearer $ANTHROPIC_ADMIN_KEY" \
  --data-urlencode "starting_at=2026-10-01T00:00:00Z" \
  --data-urlencode "ending_at=2026-11-01T00:00:00Z" \
  --data-urlencode "group_by[]=api_key_id" \
  --data-urlencode "limit=20"

La réponse arrive classée par dépense décroissante, une ligne par clé. Dans group, seul le champ demandé est rempli, les autres restent null. Une ligne avec api_key_id à null correspond à de l'usage non authentifié par une clé : le Workbench de la Console, typiquement.

Chaque clé s'identifie par un apikey_..., pas par son nom. Gardez à côté un petit tableau de correspondance (clé, projet, responsable). Sans lui, vous saurez que « apikey_01Rj... » coûte 412 $ mais pas à qui poser la question.

Lire les montants sans se tromper d'un facteur 100

C'est le piège numéro un. Le champ amount est une chaîne, exprimée en centimes fractionnaires. L'exemple de la référence officielle affiche "41280.000000" : cela fait 412,80 $, pas 41 280 $. Le champ list_amount donne le tarif catalogue avant remises ; l'écart entre les deux mesure vos remises de volume, utile si vous négociez un contrat.

Précision à connaître : amount est « post-remise, pré-crédits ». Si vous consommez des crédits (par exemple ceux inclus dans un abonnement Max, voir notre tuto sur les 200 $ de crédits API), la ligne ne vous dit pas ce qui sort réellement de votre carte.

Étape 2 : regrouper par modèle et type de token pour trouver la fuite

Savoir quelle clé coûte cher ne suffit pas. Il faut savoir pourquoi. Ajoutez model et token_type :

--data-urlencode "group_by[]=api_key_id" \
--data-urlencode "group_by[]=model" \
--data-urlencode "group_by[]=token_type"

Le token_type éclate chaque ligne en tokens d'entrée non mis en cache, lecture de cache, création de cache (5 min ou 1 h) et tokens de sortie. Trois lectures fréquentes :

• Beaucoup d'uncached_input_tokens et très peu de cache_read_input_tokens : le cache de prompt ne sert pas. Un préfixe stable en tête de prompt corrige souvent l'essentiel, comme détaillé dans notre analyse du coût caché des agents en production.
• Un gros poste output_tokens sur un modèle haut de gamme : la tâche tolère peut-être un modèle plus petit.
• Des lignes speed: fast : le mode rapide se paie plus cher. Anthropic a d'ailleurs annoncé la fin du mode rapide d'Opus 4.8 au 30 novembre, avec migration vers Opus 5.5.

Le regroupement par cost_type sépare enfin les tokens de la recherche web, de l'exécution de code et du temps de session des agents managés, trois postes qu'on oublie dans les budgets.

Étape 3 : un script hebdomadaire d'alerte de 30 lignes

Le but : chaque lundi, un message qui classe les clés par coût sur les 7 derniers jours et signale celles qui dépassent un seuil. Python standard, aucune dépendance :

import json, os, urllib.parse, urllib.request
from datetime import datetime, timedelta, timezone

SEUIL_USD = 50.0
fin = datetime.now(timezone.utc).replace(hour=0, minute=0, second=0, microsecond=0)
debut = fin - timedelta(days=7)

params = [
    ("starting_at", debut.strftime("%Y-%m-%dT%H:%M:%SZ")),
    ("ending_at", fin.strftime("%Y-%m-%dT%H:%M:%SZ")),
    ("group_by[]", "api_key_id"),
    ("limit", "100"),
]
url = "https://api.anthropic.com/v1/organizations/analytics/cost?" + urllib.parse.urlencode(params)
req = urllib.request.Request(url, headers={
    "anthropic-version": "2026-10-21",
    "anthropic-beta": "analytics-usage-cost-2026-08-24",
    "Authorization": "Bearer " + os.environ["ANTHROPIC_ADMIN_KEY"],
})
rep = json.load(urllib.request.urlopen(req))

for ligne in rep["data"]:
    usd = float(ligne["cost"]["amount"]) / 100
    cle = ligne["group"]["api_key_id"] or "(sans clé)"
    drapeau = "  <-- A VERIFIER" if usd > SEUIL_USD else ""
    print(f"{cle}: {usd:.2f} $ ({ligne['cost']['requests']} req){drapeau}")
print("Données à jour jusqu'à :", rep["data_refreshed_at"])
if rep["has_more"]:
    print("Page suivante disponible : repasser avec page=" + rep["next_page"])

Branchez la sortie sur un message Slack ou un e-mail avec un workflow Make">Make ou n8n. La division par 100 est volontaire : c'est la conversion des centimes fractionnaires. Vérifiez-la une première fois contre la page Cost de la Console.

Un détail de plage : on borne ending_at à minuit UTC de ce matin. La documentation précise que les données au-delà du marqueur data_refreshed_at sont incomplètes, et qu'il vaut mieux fixer ending_at à cette valeur ou avant pour des résultats stables.

Les limites qui font perdre une heure

• Pas de temps réel. Les données arrivent en général sous 4 heures, parfois 24. L'ancienne API se rafraîchissait en quelques minutes. Pour un garde-fou en direct contre un agent emballé, gardez une limite de dépense côté workspace ; cette API sert à comprendre, pas à couper.
• Les chiffres bougent encore. Les valeurs peuvent être révisées jusqu'à environ 7 jours après la fin du mois : celles du 1er octobre peuvent changer jusqu'au 7 novembre. Ne figez pas une facture client sur un total du 2 du mois.
• Fenêtre de 31 jours maximum par requête (24 heures avec des seaux à la minute), historique limité à 365 jours et pas avant le 1er janvier 2026. Pour un trimestre, trois appels.
• Un ID faux ne déclenche aucune erreur. Un apikey_ mal recopié ou un nom de modèle fautif renvoie simplement un résultat vide. Si un graphique tombe à zéro, suspectez d'abord la faute de frappe.
• Série temporelle à régler. Sans time_bucket_width (1d, 1h ou 1m), vous obtenez un total sur la plage. Avec lui, ending_at devient obligatoire, et les jours sans usage n'apparaissent pas : complétez les trous à zéro de votre côté.
• Clé contre acteur. Le filtre api_key_ids[] compte toutes les requêtes authentifiées par la clé, tandis que actor_ids[]=apikey_... ne garde que celles attribuées à la clé elle-même, hors utilisateur ou compte de service associé.

Suivre le coût par utilisateur dans Claude Code

Si votre équipe code avec Claude Code, filtrez sur products[]=claude_code et regroupez par actor : vous obtenez le coût par développeur, avec nom et adresse e-mail pour les utilisateurs. Le journal des versions de Claude Code signale d'ailleurs, depuis le 3 novembre, des budgets de groupe mutualisés côté passerelle. C'est le bon outil pour décider si dix licences à usage inégal valent mieux qu'une enveloppe commune. Pour l'étape d'avant, mesurer la qualité plutôt que la dépense, voir notre comparatif des plateformes d'observabilité d'agents.

Combien ça coûte, et pour qui c'est utile

L'API est incluse dans l'organisation : aucune ligne de facture supplémentaire n'est annoncée dans la documentation. Le seul coût est votre temps, environ une demi-heure pour le premier rapport. C'est utile dès que vous avez plus de deux clés ou un client refacturé ; c'est superflu si un seul développeur appelle un seul script. Dans ce cas la page Cost de la Console suffit.

Un outil à ne pas confondre : les message threads, sortis le 2 novembre, accélèrent les conversations longues mais ne changent pas le nombre de tokens facturés. Ils ne feront donc pas baisser les chiffres que vous allez mesurer ici.

Verdict

Pour une PME qui paie l'API Claude, c'est la mise à jour la plus utile du mois, parce qu'elle remplace un tableur bricolé par une réponse à la question que se pose tout dirigeant : qui a dépensé quoi. Installez le script, mettez un seuil honnête, et regardez le premier classement. Dans la plupart des organisations, une ou deux clés expliquent l'essentiel de la facture, et ce sont rarement celles auxquelles on pensait. À éviter : s'en servir comme alarme de sécurité. Quatre heures de retard, c'est trop long pour un agent qui boucle.

Sources : référence de l'endpoint cost, guide Usage and Cost Analytics API, notes de version Anthropic, création d'une clé Admin.