API Usage and Cost Analytics

L’API Usage and Cost Analytics rapporte l’historique de l’utilisation des tokens et des coûts de votre organisation, ventilé selon les dimensions de votre choix, telles que le modèle, l’espace de travail, la clé API, ou l’utilisateur ou le compte de service à l’origine de chaque requête. Pour les organisations Claude Console, ces données sont similaires à celles qu’affichent les pages Usage et Cost de la Claude Console.

L’API comporte deux points de terminaison :

• GET /v1/organizations/analytics/usage rapporte le nombre de tokens et le nombre de requêtes.
• GET /v1/organizations/analytics/cost rapporte le coût en USD.

L’API Usage and Cost Analytics est en version bêta. Envoyez l’en-tête anthropic-beta: analytics-usage-cost-2026-08-24 ainsi qu’un en-tête anthropic-version avec chaque requête. Le SDK et la CLI ant envoient les deux en-têtes pour vous et récupèrent les pages restantes au fur et à mesure que vous lisez les résultats, de sorte que limit ne définit que la taille de page.

Utilisez cette API pour :

• Attribuer les dépenses : ventilez le coût et l’utilisation des tokens par espace de travail, clé API, modèle, niveau de service ou identité ayant effectué chaque requête.
• Identifier les principaux consommateurs : classez les résultats par tokens, requêtes ou coût pour répondre à des questions telles que « quelles clés API dépensent le plus ce mois-ci ? ».
• Construire des séries temporelles : répartissez les résultats en intervalles quotidiens, horaires ou par minute pour les tableaux de bord et les rapports financiers.
• Intégrer une seule fois : les mêmes points de terminaison, paramètres et champs de réponse servent les organisations Claude Console et Claude Enterprise.

Démarrage rapide

Obtenez l’utilisation quotidienne des tokens pour la première semaine de septembre, avec une ligne pour chaque modèle et chaque jour :

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=["model"],
    limit=10,
)

for row in rows:
    print(f"{row.starting_at} {row.group.model}: {row.usage.total_tokens}")

La réponse contient une ligne pour chaque modèle et chaque jour présentant une utilisation, en commençant par le total_tokens le plus élevé. Cet exemple montre une seule ligne :

{
  "data": [
    {
      "starting_at": "2026-09-03T00:00:00Z",
      "ending_at": "2026-09-04T00:00:00Z",
      "group": {
        "product": null,
        "model": "claude-sonnet-5",
        "context_window": null,
        "inference_geo": null,
        "speed": null,
        "slack_channel_id": null,
        "claude_tag_category": null,
        "claude_tag_user_id": null,
        "rbac_group_id": null,
        "workspace_id": null,
        "service_tier": null,
        "user_profile_id": null,
        "agent_id": null,
        "environment_id": null,
        "deployment_id": null,
        "session_id": null,
        "actor": null,
        "actor_type": null,
        "api_key_id": null
      },
      "usage": {
        "uncached_input_tokens": 1284500,
        "cache_creation": {
          "ephemeral_1h_input_tokens": 0,
          "ephemeral_5m_input_tokens": 215300
        },
        "cache_read_input_tokens": 3200000,
        "output_tokens": 891000,
        "total_tokens": 5590800,
        "server_tool_use": {
          "web_search_requests": 12
        },
        "requests": 4210
      }
    }
  ],
  "has_more": true,
  "next_page": "page_V2mQ4dkt9HcbX3pLr...",
  "data_refreshed_at": "2026-09-18T16:02:11Z"
}

Structure des résultats

• Chaque ligne comporte trois parties : starting_at et ending_at indiquent la période couverte par la ligne, group contient toutes les dimensions, et usage (ou cost sur le point de terminaison de coût) contient les métriques.
• Les dimensions sont nulles sauf si elles sont regroupées : une dimension dans group vaut null sauf si vous la listez dans group_by[]. Une dimension regroupée vaut également null sur les lignes qui n’ont pas de valeur pour elle, comme model pour l’utilisation de l’exécution de code. group_by[] accepte jusqu’à cinq dimensions.
• Une ligne pour chaque combinaison : chaque ligne correspond à une combinaison des dimensions regroupées, et chaque combinaison présentant une utilisation ou un coût apparaît exactement une fois sur l’ensemble des pages d’une requête. Sans group_by[] ni time_bucket_width, la réponse est une ligne unique qui totalise toute la plage.
• Les intervalles de temps sont facultatifs : définissez time_bucket_width sur 1m, 1h ou 1d pour répartir chaque combinaison par intervalle UTC ; les valeurs starting_at et ending_at de chaque ligne correspondent alors aux bornes de son intervalle. Les intervalles sans utilisation ni coût ne produisent aucune ligne.
• Classées par défaut : Les lignes sont triées selon la métrique order_by sur toute la plage, de la plus grande à la plus petite par défaut (order=asc inverse l’ordre). Pour construire une série temporelle, définissez time_bucket_width et order_by=time. Les lignes sont alors renvoyées intervalle de temps après intervalle de temps, l’intervalle le plus récent en premier par défaut (order=asc place le plus ancien en premier), avec les plus grandes lignes en premier au sein de chaque intervalle. Remplissez les intervalles vides avec des zéros.
• Les filtres fonctionnent en parallèle du regroupement : la plupart des dimensions selon lesquelles vous pouvez regrouper disposent d’un filtre de liste correspondant en notation entre crochets, comme models[]=claude-opus-5-5. Répétez le paramètre pour transmettre plusieurs valeurs, jusqu’à 100. Plusieurs valeurs pour un même filtre sont combinées avec OR, et des filtres différents sont combinés avec AND. Les filtres et group_by[] sont indépendants ; vous pouvez filtrer selon n’importe quelle dimension, avec ou sans regroupement selon celle-ci, ou inversement.

Des dimensions telles que model et actor s’appliquent à toutes les organisations. Certaines, comme api_key_id, ne s’appliquent qu’aux organisations Claude Console, et d’autres, comme slack_channel_id, ne s’appliquent qu’aux organisations Claude Enterprise. Une dimension qui ne s’applique pas à votre organisation vaut null sur chaque ligne et son filtre ne correspond à rien ; l’exception est rbac_group_id, qui renvoie plutôt une erreur lorsque les équipes ne sont pas disponibles pour votre organisation. La référence de l’API pour utilisation et coûts liste chaque dimension, filtre et valeur.

Acteurs

La dimension actor indique à qui une requête est attribuée : un utilisateur, un compte de service, une identité cloud fédérée (un principal AWS ou Google Cloud, pour les organisations qui accèdent à Claude via leur plateforme cloud) ou, lorsqu’aucun de ceux-ci n’est à l’origine de la requête, la clé API elle-même. Lorsque vous groupez par actor, le champ actor de chaque ligne est un objet dont le type indique de quel type il s’agit. L’utilisation qui ne peut être attribuée à aucune identité a actor: null.

Les clés personnelles et clés de compte de service agissent en tant qu’utilisateur ou compte de service auquel elles sont liées, de sorte que leurs requêtes affichent cette identité comme actor et la clé dans api_key_id. Les anciennes clés d’espace de travail ne sont liées à aucune identité, la clé apparaît donc à la fois comme actor et comme api_key_id. L’exception est la clé que Claude Code crée lorsqu’un membre se connecte avec son compte Claude Console : elle se trouve dans l’espace de travail Claude Code, et son utilisation est attribuée à ce membre. Les requêtes effectuées sans clé API, par exemple depuis la Claude Console ou avec un jeton Workload Identity Federation, ont api_key_id: null ; l’actor d’une charge de travail fédérée est son compte de service. Pour inclure l’utilisation sans clé API dans un filtre api_key_ids[], ajoutez une entrée vide : api_key_ids[]=.

Les filtres api_key_ids[] et actor_ids[] répondent à des questions différentes. api_key_ids[]=apikey_... correspond à toutes les requêtes authentifiées par la clé, quelle que soit l’identité à laquelle elles sont attribuées. actor_ids[]=apikey_... ne correspond qu’aux requêtes attribuées à la clé elle-même.

Point de terminaison d’utilisation

GET /v1/organizations/analytics/usage renvoie le nombre de tokens par type. order_by accepte total_tokens (la valeur par défaut), output_tokens, uncached_input_tokens, requests ou time.

Par exemple, pour voir une semaine d’utilisation pour un espace de travail et une clé API, ventilée par niveau de service (une ligne pour chaque niveau, couvrant toute la semaine) :

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    workspace_ids=["wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"],
    api_key_ids=["apikey_01Rj2N8SVvo6BePZj99NhmiT"],
    group_by=["service_tier"],
)

for row in rows:
    print(f"{row.group.service_tier}: {row.usage.total_tokens}")

Pour rechercher les identifiants de clés API et d’espaces de travail, utilisez les points de terminaison List API Keys et List Workspaces ou la Claude Console.

Pour identifier les utilisateurs, comptes de service et clés API ayant effectué le plus de requêtes au cours d’un mois :

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    group_by=["actor"],
    order_by="requests",
    limit=25,
)

for row in rows:
    print(f"{row.group.actor}: {row.usage.requests}")

Point de terminaison de coûts

GET /v1/organizations/analytics/cost accepte les mêmes filtres, dimensions et intervalles de temps que le point de terminaison /usage. L’objet cost de chaque ligne contient amount (le coût après remises et avant l’application de tout crédit), list_amount (le coût aux prix catalogue), currency (toujours "USD") et requests. Les montants sont des chaînes décimales en cents avec six décimales : "41280.000000" correspond à 412,80 $ USD. order_by accepte amount (la valeur par défaut), list_amount ou time.

Deux dimensions supplémentaires n’existent que sur ce point de terminaison et ne sont pas prises en compte dans la limite de cinq dimensions : group_by[]=cost_type divise chaque ligne en une ligne pour chaque type de coût, et group_by[]=token_type divise le coût des tokens en une ligne pour chaque type de token. limit ne s’applique pas non plus à ces deux dimensions, de sorte qu’une page peut contenir plus de limit lignes. Par exemple, le coût par modèle, type de coût et type de token pour un mois :

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    group_by=["model", "cost_type", "token_type"],
)

for row in rows:
    print(
        f"{row.group.model} {row.group.cost_type} {row.group.token_type}: {row.cost.amount}"
    )

Pour chaque modèle, la réponse contient cinq lignes tokens (une pour chaque type de token), plus une ligne pour chacun de web_search, code_execution et session_usage. L’une de ces lignes :

{
  "starting_at": "2026-09-01T00:00:00Z",
  "ending_at": "2026-10-01T00:00:00Z",
  "group": {
    "model": "claude-opus-5",
    ...,
    "cost_type": "tokens",
    "token_type": "cache_read_input_tokens"
  },
  "cost": {
    "currency": "USD",
    "amount": "41280.000000",
    "list_amount": "51600.000000",
    "requests": null
  }
}

L’objet group contient toutes les dimensions et est abrégé ici. Lorsque group_by[]=cost_type ou token_type est spécifié, requests vaut null sur chaque ligne.

Plages de dates et intervalles de temps

• Les horodatages sont au format RFC 3339 avec un décalage UTC, par exemple 2026-09-01T00:00:00Z. starting_at est inclusif et ending_at est exclusif.
• starting_at doit être postérieur ou égal au 1er janvier 2026 et compris dans les 365 derniers jours. Une requête peut couvrir au maximum 31 jours ; ending_at vaut par défaut 31 jours après starting_at ou l’heure actuelle, selon ce qui est le plus tôt.
• ending_at est obligatoire dès que time_bucket_width est défini, et avec time_bucket_width=1m une requête peut couvrir au maximum 24 heures.
• Les deux extrémités de la plage sont arrondies à l’inférieur à une limite d’intervalle UTC, ou à l’heure lorsque time_bucket_width n’est pas défini. Par exemple, avec time_bucket_width=1h, un starting_at de 2026-09-01T10:43:00Z est traité comme 2026-09-01T10:00:00Z et un ending_at de 2026-09-01T15:43:00Z comme 2026-09-01T15:00:00Z, de sorte que la réponse couvre de 10:00 à 15:00 UTC.

Fraîcheur des données

Chaque réponse inclut un horodatage data_refreshed_at, et l’utilisation postérieure à ce moment est manquante ou partielle. Lorsqu’aucune donnée n’est encore disponible pour une partie quelconque de la plage demandée, data_refreshed_at vaut null et data est vide. Les données sont généralement actualisées dans les 4 heures suivant l’utilisation sous-jacente et peuvent prendre jusqu’à 24 heures. Les valeurs peuvent être révisées à mesure que des événements tardifs arrivent et que des rapprochements sont effectués, jusqu’à environ 7 jours après la fin du mois calendaire. Par exemple, les valeurs du 1er octobre peuvent changer jusqu’au 7 novembre environ. Pour obtenir des résultats stables lors d’appels répétés, définissez ending_at à une valeur égale ou antérieure à un data_refreshed_at que vous avez déjà vu ; pour obtenir des totaux définitifs, n’interrogez que les mois terminés depuis au moins 7 jours. Chaque page d’une requête paginée lit le même instantané de données, de sorte que data_refreshed_at est identique d’une page à l’autre.

Migrer depuis l’API Usage and Cost

Cette section s’adresse aux organisations Claude Console qui appellent l’ancienne API Usage and Cost (/v1/organizations/usage_report/messages et /v1/organizations/cost_report). Votre clé Admin API, l’en-tête anthropic-version, starting_at et ending_at, les valeurs de largeur d’intervalle (1m, 1h, 1d), la notation entre crochets, les noms des champs de pagination et les noms des champs de tokens et de coûts restent inchangés. Ce qui change :

Pour reproduire la version héritée du rapport quotidien, demandez time_bucket_width=1d avec le même group_by[], parcourez les pages avec limit=1000, puis regroupez les lignes par starting_at et remplissez les jours manquants avec des zéros. Ajoutez order_by=time&order=asc pour obtenir les jours dans l’ordre. Utilisation quotidienne par modèle sur 1 semaine, avant :

curl --globoff "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-09-01T00:00:00Z&\
ending_at=2026-09-08T00:00:00Z&\
group_by[]=model&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

et après :

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=["model"],
    limit=1000,
)

for row in rows:
    print(f"{row.starting_at} {row.group.model}: {row.usage.total_tokens}")

Coût quotidien par espace de travail, modèle, niveau de service, fenêtre de contexte et zone géographique d’inférence, réparti par type de coût et type de token :

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=[
        "workspace_id",
        "model",
        "service_tier",
        "context_window",
        "inference_geo",
        "cost_type",
        "token_type",
    ],
    limit=1000,
)

for row in rows:
    group = row.group
    print(
        f"{row.starting_at} {group.workspace_id} {group.model} {group.service_tier} "
        f"{group.context_window} {group.inference_geo} {group.cost_type} {group.token_type}: "
        f"{row.cost.amount}"
    )

Migrer depuis les rapports d’utilisation et de coûts de Claude Enterprise

Cette section s’adresse aux organisations Claude Enterprise qui appellent les points de terminaison de rapport usage_report, cost_report, user_usage_report et user_cost_report de la Claude Enterprise Analytics API sous /v1/organizations/analytics/. Ces points de terminaison sont hérités et restent pris en charge. Passez à /analytics/usage et /analytics/cost lorsque vous souhaitez l’un des éléments suivants :

• Chaque groupe dans chaque intervalle de temps, plutôt que les 100 premiers groupes de chaque intervalle
• Le regroupement par actor ou actor_type conjointement avec d’autres dimensions, à la fois pour l’utilisation et le coût
• Des lignes classées selon la métrique de votre choix sur toute la plage, ou triées par intervalle de temps
• Une seule intégration qui sert également les organisations Claude Console

Votre clé, la date la plus ancienne, la période rétrospective de 365 jours et l’étendue de 31 jours, les noms et valeurs des filtres et des dimensions (à l’exception de user_ids[] et de la valeur de produit Claude Tag), les champs actor des utilisateurs, les champs de métriques et de montants, data_refreshed_at, les règles de curseur et la limite de débit au niveau de l’organisation restent inchangés. Le seul nouvel en-tête est l’en-tête bêta analytics-usage-cost-2026-08-24. Ce qui change :

Coût par utilisateur pour un mois, avant :

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.user_cost_report.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    limit=100,
)

for row in rows:
    print(f"{row.actor.user_id}: {row.amount}")

et après, en ajoutant une ventilation par produit :

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    actor_types=["user_actor"],
    group_by=["actor", "product"],
    limit=100,
)

for row in rows:
    actor = row.group.actor
    if actor is not None and actor.type == "user_actor":
        print(f"{actor.user_id} {row.group.product}: {row.cost.amount}")

Questions fréquentes

Comment l’espace de travail par défaut est-il représenté ?

L’espace de travail par défaut d’une organisation Claude Console possède son propre identifiant wrkspc_, comme tout autre espace de travail. Les lignes de l’espace de travail par défaut contiennent cet identifiant dans workspace_id, et vous pouvez filtrer sur celui-ci avec workspace_ids[]. List Workspaces omet l’espace de travail par défaut, sauf si vous transmettez include_default=true. Pour vérifier si un workspace_id inconnu correspond à l’espace de travail par défaut, transmettez-le à Get Workspace : l’espace de travail par défaut renvoie "name": "Default".

Comment obtenir le coût par utilisateur pour Claude Code ?

Appelez le point de terminaison de coûts avec products[]=claude_code&group_by[]=actor. Les organisations Claude Console peuvent également utiliser l’API Claude Code Analytics, qui rapporte l’activité Claude Code par utilisateur et le coût estimé.

Voir aussi

• API Usage and Cost (ancienne version)
• API Analytics : quelle API d’analytique et quel type de clé votre organisation nécessite
• API Claude Code Analytics
• Référence de l’Admin API
• Tarification