Un tableau de suivi Claude peut afficher un total plausible tout en oubliant une partie des consommations. La nouvelle Usage and Cost Analytics API, annoncée le 29 octobre 2026, renvoie des lignes paginées là où l’ancien collecteur Console parcourait des blocs de temps. Changer seulement l’URL laisserait le contrat de données incomplet.
Anthropic propose désormais les mêmes endpoints d’analyse aux organisations Claude Console et Claude Enterprise. L’API reste en bêta ; les anciens rapports, devenus legacy, restent supportés. Le nom du header analytics-usage-cost-2026-08-24 n’est donc pas sa date d’annonce. Notes officielles du 29 octobre.
Cette analyse vise une équipe qui alimente déjà un tableau de bord depuis l’API Anthropic directe. Elle explique les changements à vérifier avant bascule. Aucune organisation Anthropic n’a été interrogée pour cet article. La requête proposée est documentaire ; seul l’exercice sur des fichiers fictifs a été exécuté localement.
Le choix de migration dépend d’abord du délai accepté
La nouvelle API sert à regrouper les usages et coûts selon des dimensions communes, puis à les intégrer dans vos propres rapports. Elle ajoute notamment la possibilité d’analyser l’identité derrière une requête avec les autres dimensions.
Pour un suivi Console existant, la fraîcheur est un changement décisif : la documentation de migration compare des usages legacy généralement visibles en cinq minutes à une actualisation nouvelle typiquement sous quatre heures, pouvant prendre vingt-quatre heures. Chaque réponse nouvelle fournit data_refreshed_at pour situer les données disponibles. Les valeurs d’un mois peuvent encore être révisées jusqu’à environ sept jours après sa clôture : le watermark ne signifie pas que les totaux sont définitifs. Contrat de migration et fraîcheur.
Cela conduit à deux décisions différentes :
- Un rapport d’attribution quotidien peut accepter un délai, à condition d’afficher sa fraîcheur et de reprendre les périodes encore provisoires.
- Une alerte qui attend une consommation récente doit d’abord vérifier que ce délai lui convient. La migration du tableau financier ne justifie pas de supprimer ses autres signaux.
Le statut legacy ne commande pas une bascule immédiate. Pour une nouvelle intégration, l’ancien guide oriente vers Analytics. Pour un collecteur qui fonctionne, commencer par une collecte parallèle rend les écarts observables. Guide Console legacy.
Les trois changements qui touchent le collecteur
Prenons un tableau quotidien qui suit les tokens générés par modèle. Son ancienne boucle lisait chaque élément de data comme une période, puis parcourait results.
La nouvelle réponse porte directement les périodes sur chaque ligne. Le modèle passe sous group.model ; les tokens de sortie passent sous usage.output_tokens. Un parseur doit donc changer de structure, même quand la métrique métier reste identique.
| Point |
Collecte Console legacy |
Nouvelle collecte Analytics |
| Chemin des usages |
data[].results[] |
data[], avec group et usage |
| Découpage quotidien |
bucket_width=1d |
time_bucket_width=1d explicite |
| Taille de page |
Nombre de périodes |
Nombre de lignes |
| Ordre |
Périodes de la plus ancienne à la plus récente |
Classement par métrique par défaut ; ordre temporel à demander |
Ces paramètres et schémas sont décrits dans les références legacy Messages et Analytics Usage.
Avec dix modèles utilisés sur sept jours, une page de vingt lignes ne couvre pas nécessairement les sept journées. La dernière date visible ne prouve pas que tous les modèles de cette date ont été récupérés. Il faut suivre has_more et next_page jusqu’à la fin, puis trier ou agréger les lignes.
Une autre convention change : les combinaisons sans usage n’ont pas de ligne. Le remplissage des jours vides doit intervenir après une collecte complète et suffisamment fraîche. Un export tronqué et une journée sans consommation ne doivent pas produire le même zéro.
Accès : Console et Enterprise gardent des clés distinctes
Côté Console, la voie de cet exemple utilise une clé Admin API, dans le header x-api-key. Une clé de workspace destinée aux appels de modèle ne convient pas. Les clés Admin relèvent des organisations ; cette fonctionnalité n’est pas disponible aux comptes individuels. Clés Admin et conditions d’accès.
Côté Claude Enterprise, l’accès passe par une clé Analytics avec le scope read:analytics, après activation de l’API. La couverture des coûts dépend du mode de facturation : les plans à l’usage sont couverts ; sur les plans par siège, les données concernent les usage credits. Ce périmètre ne représente donc pas automatiquement le coût complet des abonnements. Accès et couverture Enterprise.
Le nom commun des endpoints ne fusionne ni les organisations, ni les droits. L’exemple ci-dessous vise Console sur api.anthropic.com. Les voies cloud et leur authentification demandent leurs instructions propres.
Les sources consultées ne publient pas de tarif spécifique permettant d’affirmer que cette nouvelle API est gratuite. La tarification des modèles ne suffit pas à répondre à cette question.
Première collecte : figer une période avant de comparer
Choisissez une période historique complète et le même regroupement dans les deux collectes. Notre exemple couvre le 1er et le 2 septembre en UTC : début inclus, fin exclue au 3 septembre. Le début doit être au moins le 1er janvier 2026 et rester dans les 365 derniers jours. Une requête couvre au maximum 31 jours ; découpez un historique plus long en périodes adjacentes. Bornes de la référence Usage.
Le collecteur doit conserver les filtres exacts, la version d’API et les paramètres de regroupement avec son export. Changer de période et de dimensions pendant une migration empêcherait d’expliquer un écart.
La commande suivante montre une première page documentée, pas un client de collecte complet. Injectez votre clé Admin dans ANTHROPIC_ANALYTICS_KEY avec votre gestionnaire de secrets ; ne l’inscrivez pas dans le fichier exporté.
curl --fail-with-body --silent --show-error --globoff --get \
'https://api.anthropic.com/v1/organizations/analytics/usage' \
-H "x-api-key: $ANTHROPIC_ANALYTICS_KEY" \
-H 'anthropic-version: 2023-06-01' \
-H 'anthropic-beta: analytics-usage-cost-2026-08-24' \
--data-urlencode 'starting_at=2026-09-01T00:00:00Z' \
--data-urlencode 'ending_at=2026-09-03T00:00:00Z' \
--data-urlencode 'time_bucket_width=1d' \
--data-urlencode 'group_by[]=model' \
--data-urlencode 'order_by=time' \
--data-urlencode 'order=asc' \
--data-urlencode 'limit=2' \
--output usage-page-1.json
La valeur limit=2 rend le contrôle de pagination visible. Si has_more vaut true, relancez avec les mêmes paramètres et --data-urlencode 'page=VALEUR_DE_NEXT_PAGE', en sauvegardant chaque réponse dans un fichier distinct. Continuez jusqu’à has_more=false. Si un curseur expire avec HTTP 410, recommencez sans curseur depuis la première page et remplacez le lot incomplet ; ne mélangez pas les instantanés. Le schéma et les paramètres de cette collecte viennent de la référence Usage.
Vérifiez ensuite le watermark, data_refreshed_at. Une fin de période postérieure à ce point peut inclure des usages encore manquants. Les buckets sont UTC : un jour du tableau métier en heure de Paris exige une convention de conversion explicite, surtout lors des changements d’heure.
Un exercice local fait apparaître la ligne perdue
Les fichiers de l’exercice représentent le même détail jour/modèle dans deux formes. Leur ordre fictif illustre un classement par métrique, différent du tri temporel demandé dans la commande ci-dessus :
- un export legacy fictif contenant 400 tokens de sortie ;
- deux pages Analytics fictives, avec 350 tokens sur la première et 50 sur la seconde.
Téléchargez le comparateur Python, l’export legacy et les deux pages Analytics dans un même dossier. Python 3.10 ou plus récent et sa bibliothèque standard suffisent.
python3 comparer.py
Le résultat exécuté localement retrouve 400 contre 400, avec égalité de chaque couple jour/modèle. Une addition limitée à la première page donne 350. Le comparateur refuse aussi la dernière page manquante, un curseur incohérent et une période pas encore entièrement rafraîchie.
Ce test contrôle la transformation de output_tokens seulement, sur des données synthétiques aux champs réduits. Il ne valide ni un accès Anthropic, ni tout le schéma officiel, ni un total de facturation. Pour votre migration, répétez le rapprochement avec chaque métrique et chaque dimension que votre tableau utilise.
Pour les coûts, conserver les unités et le périmètre
Le second endpoint, /v1/organizations/analytics/cost, expose cost.amount après remises et avant crédits, et cost.list_amount au tarif catalogue. Les montants sont des chaînes décimales en centimes de dollar, pas des dollars.
Un montant fictif "12345.000000" représente donc 123,45 USD. Gardez une arithmétique décimale et la valeur brute pour pouvoir expliquer la conversion. Les regroupements cost_type et token_type peuvent produire plus de lignes que limit ; dans ce découpage, requests vaut null. Référence Cost.
Pour rapprocher un coût par modèle avec l’ancien rapport Console, le chemin est différent : l’ancien endpoint ne documente pas de filtre models[] ni de regroupement direct par modèle. Demandez le détail group_by[]=description, collectez toutes les pages, puis sélectionnez localement results[].model. Référence Cost legacy.
Un modèle null ne signifie pas une consommation inexistante : certains usages d’outils n’ont pas de modèle attribué. Un filtre de modèle erroné peut également ne rien trouver. Avant de conclure à zéro, comparez une collecte large et la collecte filtrée.
Enfin, le montant API ne constitue pas à lui seul la facture : l’engagement Priority Tier est facturé séparément et ses frais ne sont pas inclus dans ces données. Rapprochez le rapport d’attribution avec votre périmètre de facturation. Limites de lecture des coûts.
Une bascule réussie doit expliquer les écarts
Avant de remplacer le collecteur, rendez quatre contrôles visibles : période et filtres identiques, dernière page atteinte, fraîcheur suffisante, rapprochement au détail des dimensions conservées. Une égalité globale peut masquer deux erreurs qui se compensent.
La nouvelle API devient intéressante si ses regroupements résolvent une question d’attribution que vous ne traitiez pas correctement. La première livraison utile est un collecteur parallèle dont on sait expliquer les écarts, puis une décision de bascule fondée sur ces observations.
Pour replacer ce suivi dans la chaîne complète, notre guide d’observabilité LLM distingue traces, évaluation et coût opérationnel. La méthode d’attribution des coûts data aide à relier une consommation technique à son usage métier.
