API Spend Limits

L'API Spend Limits (limites de dépenses) vous permet de définir une limite de dépenses pour chaque membre Claude Enterprise, de voir d'où est héritée la limite de dépenses de chaque membre, et d'examiner ou de traiter les demandes des membres pour une limite plus élevée.

Pour les rapports d'utilisation et de coûts par utilisateur et par tranche temporelle, consultez les API Analytics.

Vue d'ensemble

L'API expose huit points de terminaison répartis sur deux ressources :

Utilisez les points de terminaison de limites de dépenses pour répondre à la question « quelle limite de dépenses s'applique à chaque membre, d'où vient-elle, et à quel point en sont-ils proches ? » et pour définir une dérogation par utilisateur. Utilisez les points de terminaison de demandes d'augmentation de limite de dépenses pour traiter la file des demandes soumises par les membres.

Prérequis

• Votre organisation doit disposer d'un forfait Claude Enterprise.
• Les crédits d'utilisation doivent être activés pour votre organisation. Votre propriétaire principal peut les activer dans les paramètres de facturation de claude.ai.

Démarrage rapide

Listez la limite de dépenses mensuelle effective de chaque membre et ses dépenses depuis le début de la période :

curl "https://api.anthropic.com/v1/organizations/spend_limits/effective?limit=20" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --header "anthropic-version: 2023-06-01"

Concepts clés

La hiérarchie des limites de dépenses

Une « effective spend limit » (limite de dépenses effective) s'applique aux dépenses de chaque membre, résolue à partir d'une hiérarchie de niveaux de portée. Lorsqu'un membre n'a pas de dérogation par utilisateur, il hérite de la limite de dépenses configurée pour son groupe (si votre organisation utilise des limites basées sur les groupes), son niveau de siège ou la valeur par défaut de l'organisation. Une limite de dépenses de groupe est une valeur par défaut par membre : chaque membre qui en hérite est contrôlé par rapport à ses propres dépenses, et non par rapport à un budget de groupe mutualisé.

La lecture de GET /v1/organizations/spend_limits/effective renvoie chaque membre actuel avec sa limite de dépenses effective résolue, l'origine de cette limite (source) et ses dépenses depuis le début de la période. Définir une dérogation par utilisateur avec POST /v1/organizations/spend_limits fixe un membre à une limite de dépenses spécifique, indépendamment de ce qu'il hériterait autrement. Supprimer la dérogation le ramène à la limite de dépenses héritée (ou le laisse illimité s'il n'en existe aucune).

Le champ source sur la ligne de chaque membre vous indique à partir de quel niveau sa limite de dépenses a été résolue : user (une dérogation par utilisateur), seat_tier, rbac_group ou organization. Traitez les types de portée comme un ensemble ouvert ; ignorez les valeurs inconnues plutôt que d'échouer.

Période

period est la fenêtre récurrente sur laquelle la limite de dépenses est appliquée et les dépenses sont réinitialisées. Une limite de dépenses est identifiée par sa paire (scope, period). Actuellement, monthly est la seule période prise en charge ; les dépenses mensuelles sont réinitialisées à 00:00 UTC le premier jour de chaque mois calendaire. Traitez period comme un ensemble ouvert.

Montants et devise

Toutes les valeurs monétaires sont des chaînes de caractères exprimées en unités mineures de la devise de facturation de l'organisation (centimes, pour l'USD). Par exemple, "50000" représente 500,00 USD. Analysez-les comme un nombre décimal et divisez par 100 pour afficher des dollars ; évitez la virgule flottante binaire pour les grandes valeurs.

amount est nullable. Dans la ligne effective d'un membre, null signifie illimité (aucune limite de dépenses) et "0" signifie que le membre ne peut pas utiliser Claude au-delà de l'utilisation incluse dans son forfait. Sur une ligne de limite de dépenses configurée (telle que renvoyée par GET /v1/organizations/spend_limits/{id}), null signifie uniquement qu'aucune limite de dépenses numérique n'est définie ; lisez la ligne effective du membre pour distinguer illimité de l'utilisation incluse uniquement.

period_to_date_spend correspond aux dépenses du membre accumulées depuis le début de la period en cours, dans le même format en unités mineures ; il peut inclure une partie fractionnaire (par exemple, "41280.125"). Il peut afficher "0" si la lecture des dépenses est temporairement indisponible ; traitez-le comme informatif, et non transactionnel.

Cycle de vie d'une demande d'augmentation

Une « spend limit increase request » (demande d'augmentation de limite de dépenses) est créée lorsqu'un membre clique sur Request more usage dans claude.ai. Les demandes ne sont pas créées via cette API. Le status d'une demande est l'un des suivants :

approved et denied sont tous deux des états terminaux. Un membre a au plus une demande pending à la fois.

Approuver avec POST /v1/organizations/spend_limit_increase_requests/{id}/approve écrit la même ligne de limite de dépenses par utilisateur que celle écrite par POST /v1/organizations/spend_limits. Définir directement une limite de dépenses ne fait pas transitionner une demande en attente ; utilisez le point de terminaison d'approbation pour résoudre une demande.

Par défaut, Anthropic envoie un e-mail au membre lorsque sa demande est approuvée ou refusée. Transmettez suppress_notification: true lors de l'approbation ou du refus pour supprimer cet e-mail (par exemple, lorsque votre propre système notifie le membre).

Gestion des versions

Envoyez l'en-tête anthropic-version avec chaque requête ; consultez Versions de l'API pour connaître les versions disponibles.

Limitation de débit

Les huit points de terminaison partagent une seule « rate limit » (limite de débit) par organisation de 60 requêtes par minute. Les requêtes dépassant la limite renvoient 429 Too Many Requests.

Pagination

GET /v1/organizations/spend_limits/effective et GET /v1/organizations/spend_limit_increase_requests sont paginés avec un curseur opaque. La première requête renvoie jusqu'à limit lignes plus un curseur next_page ; transmettez ce curseur tel quel comme paramètre page lors de la requête suivante, et répétez jusqu'à ce que next_page soit null.

Ne modifiez pas les paramètres de requête en cours de séquence. Les curseurs sont liés aux filtres qui les ont émis. Si vous modifiez user_ids[], period[], status[] ou actor_ids[] et transmettez un ancien curseur, vous obtiendrez une erreur 400 avec "cursor does not match current query parameters". Commencez plutôt une nouvelle séquence à partir de la première page.

Sérialisation des paramètres de liste

Les paramètres de liste utilisent la notation entre crochets : répétez le nom du paramètre avec [] pour chaque valeur.

user_ids[]=user_01AbCdEfGh&user_ids[]=user_01JkLmNoPq

Réponses d'erreur

Les réponses d'erreur suivent la forme standard documentée dans Erreurs. Citez le request_id du corps de la réponse lorsque vous contactez le support.

Limites de dépenses

Lister la limite de dépenses effective de chaque membre

GET /v1/organizations/spend_limits/effective renvoie une ligne par membre actuel, reflétant la limite de dépenses effective de chaque membre, sa source dans la hiérarchie des portées et son period_to_date_spend. Nécessite la portée read:spend_limits.

Pour les détails complets des paramètres et les schémas de réponse, consultez Lister les limites de dépenses effectives dans la référence de l'API.

curl "https://api.anthropic.com/v1/organizations/spend_limits/effective?limit=20" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --header "anthropic-version: 2023-06-01"

{
  "data": [
    {
      "scope": { "type": "user", "user_id": "user_01AbCdEfGh" },
      "actor": {
        "type": "user_actor",
        "user_id": "user_01AbCdEfGh",
        "name": "Jane Smith",
        "email_address": "jane@example.com",
        "deleted": false
      },
      "amount": "50000",
      "currency": "USD",
      "period": "monthly",
      "source": { "type": "seat_tier", "seat_tier": "enterprise_standard" },
      "spend_limit_id": "spl_01XyZaBcDeFgHiJkLmNoPq",
      "period_to_date_spend": "31402.5"
    }
  ],
  "next_page": "page_..."
}

Obtenir une seule limite de dépenses

GET /v1/organizations/spend_limits/{spend_limit_id} renvoie une limite de dépenses configurée par ID. Utilisez-le pour inspecter la ligne référencée par un champ spend_limit_id. Nécessite la portée read:spend_limits.

Pour les détails complets des paramètres et les schémas de réponse, consultez Récupérer une limite de dépenses dans la référence de l'API.

curl "https://api.anthropic.com/v1/organizations/spend_limits/spl_01AbCdEfGhIjKlMnOpQrSt" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --header "anthropic-version: 2023-06-01"

Définir une dérogation par utilisateur

POST /v1/organizations/spend_limits définit une dérogation de limite de dépenses par utilisateur. Il s'agit d'un upsert indexé sur (scope, period) : définir une limite pour un utilisateur et une période qui en possède déjà une l'écrase sur place. Ce point de terminaison n'accepte que scope.type: "user" ; les valeurs par défaut au niveau du niveau de siège, du groupe et de l'organisation sont configurées dans les paramètres de claude.ai. Nécessite la portée write:spend_limits.

Pour les détails complets des paramètres et les schémas de réponse, consultez Créer une limite de dépenses dans la référence de l'API.

curl --request POST "https://api.anthropic.com/v1/organizations/spend_limits" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --data '{"scope": {"type": "user", "user_id": "user_01AbCdEfGh"}, "amount": "75000"}'

{
  "type": "spend_limit",
  "id": "spl_01RsTuVwXyZaBcDeFgHiJk",
  "created_at": "2026-05-11T10:02:44Z",
  "updated_at": "2026-05-11T10:02:44Z",
  "scope": { "type": "user", "user_id": "user_01AbCdEfGh" },
  "amount": "75000",
  "currency": "USD",
  "period": "monthly"
}

Supprimer une dérogation par utilisateur

DELETE /v1/organizations/spend_limits/{spend_limit_id} supprime une dérogation par utilisateur, après quoi le membre revient à toute valeur par défaut héritée du niveau de siège, du groupe ou de l'organisation. Les lignes au niveau du niveau de siège, du groupe et de l'organisation ne peuvent pas être supprimées via ce point de terminaison. Nécessite la portée write:spend_limits.

Pour les détails complets des paramètres et les schémas de réponse, consultez Supprimer une limite de dépenses dans la référence de l'API.

curl --request DELETE "https://api.anthropic.com/v1/organizations/spend_limits/spl_01RsTuVwXyZaBcDeFgHiJk" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --header "anthropic-version: 2023-06-01"

Demandes d'augmentation de limite de dépenses

Lister les demandes d'augmentation

GET /v1/organizations/spend_limit_increase_requests liste les demandes, les plus récentes en premier. Filtrez par status[] (pending, approved, denied) et actor_ids[]. La liste exclut les demandes dont le demandeur n'est plus membre de l'organisation. Nécessite la portée read:spend_limits.

Pour les détails complets des paramètres et les schémas de réponse, consultez Lister les demandes d'augmentation de limite de dépenses dans la référence de l'API.

curl --globoff "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests?status[]=pending&limit=50" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --header "anthropic-version: 2023-06-01"

Chaque demande en attente comporte un spend_summary en direct indiquant la limite de dépenses effective actuelle du demandeur et ses dépenses depuis le début de la période, ce qui suffit pour décider sans recherche séparée.

Obtenir une seule demande d'augmentation

GET /v1/organizations/spend_limit_increase_requests/{id} renvoie une demande par ID. Nécessite la portée read:spend_limits.

Pour les détails complets des paramètres et les schémas de réponse, consultez Récupérer une demande d'augmentation de limite de dépenses dans la référence de l'API.

curl "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/slir_01AbCdEfGhIjKlMnOpQrSt" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --header "anthropic-version: 2023-06-01"

Approuver une demande d'augmentation

POST /v1/organizations/spend_limit_increase_requests/{id}/approve approuve une demande en attente : il écrit une limite de dépenses par utilisateur au montant amount fourni par l'administrateur pour le demandeur et fait passer la demande à approved. La demande ne comporte pas de montant demandé ; vous fournissez la nouvelle limite de dépenses lors de l'approbation. Nécessite la portée write:spend_limits.

Pour les détails complets des paramètres et les schémas de réponse, consultez Approuver une demande d'augmentation de limite de dépenses dans la référence de l'API.

curl --request POST "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/slir_01AbCdEfGhIjKlMnOpQrSt/approve" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --data '{"amount": "75000", "suppress_notification": true}'

Refuser une demande d'augmentation

POST /v1/organizations/spend_limit_increase_requests/{id}/deny refuse une demande en attente. Idempotent sur denied : refuser une demande déjà refusée renvoie 200 avec la ressource existante. Le point de terminaison rejette toute tentative de refuser une demande déjà approuvée afin que l'automatisation puisse distinguer une nouvelle tentative d'une décision contradictoire. Nécessite la portée write:spend_limits.

Pour les détails complets des paramètres et les schémas de réponse, consultez Refuser une demande d'augmentation de limite de dépenses dans la référence de l'API.

curl --request POST "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/slir_01AbCdEfGhIjKlMnOpQrSt/deny" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --data '{"suppress_notification": true}'

Exemples de flux de travail

Certains de ces flux de travail combinent l'API Spend Limits avec les points de terminaison de coûts des API Analytics. Les points de terminaison de coûts Analytics sont conçus pour les rapports de dépenses à l'échelle de l'organisation sur une plage de dates. GET /spend_limits/effective renvoie le plafond qui s'applique actuellement à chaque membre. Commencez un balayage avec Analytics pour découvrir quels membres examiner, puis lisez leurs plafonds actuels avec /effective.

Les points de terminaison Spend Limits nécessitent les portées spend_limits et les points de terminaison de coûts Analytics nécessitent read:analytics ; consultez les API Analytics pour savoir comment provisionner l'accès. Toutes les valeurs monétaires des deux API sont des chaînes décimales en unités mineures (centimes). Les deux API paginent avec un curseur opaque. Définissez une limit explicite et parcourez next_page jusqu'à ce qu'il soit null pour couvrir toute l'organisation.

Automatiser le flux d'examen des demandes d'augmentation

Exécutez une tâche planifiée qui récupère les demandes en attente, applique la politique d'approbation de votre organisation et résout chacune d'elles.

1. Listez les demandes en attente :

   cURL

   

   curl --globoff "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests?status[]=pending&limit=100" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
     --header "anthropic-version: 2023-06-01"

   Chaque demande comporte le actor.user_id du demandeur et un spend_summary en direct avec son amount effectif actuel et son period_to_date_spend, ce qui suffit pour décider sans recherche séparée.

2. Appliquez votre politique. Par exemple, approuvez automatiquement lorsque le amount actuel du membre est inférieur à un seuil, et orientez les plafonds plus élevés vers un examen manuel.

3. Résolvez chaque demande. Pour approuver, fournissez le nouveau plafond :

   cURL

   

   curl --request POST "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/{id}/approve" \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --data '{"amount": "75000", "suppress_notification": true}'

   Pour refuser, envoyez plutôt un POST à .../{id}/deny. Transmettez suppress_notification: true lorsque votre propre système notifie le demandeur.

Identifier les membres proches de leur limite de dépenses

Trouvez les membres qui approchent de leur plafond afin de pouvoir l'augmenter avant qu'ils ne soient bloqués.

1. Récupérez les dépenses du mois en cours de chaque membre depuis l'API Analytics (une ligne par membre, dépenses les plus élevées en premier par défaut) :

   cURL

   

   curl "https://api.anthropic.com/v1/organizations/analytics/user_cost_report?starting_at=2026-06-01T00:00:00Z&limit=1000" \
     --header "x-api-key: $ANALYTICS_API_KEY" \
     --header "anthropic-version: 2023-06-01"

   Chaque ligne comporte actor.user_id, actor.email et amount (les dépenses du membre en centimes). Parcourez next_page pour couvrir toute l'organisation.

2. Pour les membres qui dépensent le plus (ou tous ceux au-dessus d'un seuil en dollars), récupérez les plafonds effectifs par lots :

   cURL

   

   curl --globoff "https://api.anthropic.com/v1/organizations/spend_limits/effective?user_ids[]=user_01Ab...&user_ids[]=user_01Cd...&limit=100" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
     --header "anthropic-version: 2023-06-01"

   Chaque ligne renvoie le plafond sous forme de amount (null = illimité, "0" = utilisation incluse uniquement) ainsi que period_to_date_spend.

3. Pour chaque membre ayant un plafond positif, calculez period_to_date_spend / amount et signalez ceux qui atteignent ou dépassent votre seuil (par exemple, 80 pour cent). Traitez un plafond "0" comme déjà à la limite. Il n'existe pas de filtre côté serveur pour ce ratio.

4. Agissez sur les membres signalés : augmentez le plafond avec POST /v1/organizations/spend_limits, approuvez une demande d'augmentation en attente s'il en existe une, ou contactez le membre.

Trouver les membres dont l'utilisation évolue rapidement

Faites ressortir les membres dont les dépenses ont bondi d'une semaine à l'autre.

1. Récupérez le coût quotidien par membre pour les deux dernières semaines depuis l'API Analytics :

   cURL

   

   curl "https://api.anthropic.com/v1/organizations/analytics/user_cost_report?starting_at=2026-06-09T00:00:00Z&ending_at=2026-06-23T00:00:00Z&bucket_width=1d&limit=1000" \
     --header "x-api-key: $ANALYTICS_API_KEY" \
     --header "anthropic-version: 2023-06-01"

   Avec bucket_width défini, chaque membre s'étend sur une ligne par jour d'utilisation ; parcourez next_page pour collecter la série complète de chaque membre.

2. Regroupez les lignes par actor.user_id. Pour chaque membre, additionnez les sept jours les plus récents et les sept jours précédents. Signalez les membres dont la semaine récente dépasse la semaine précédente du multiple de votre choix (par exemple, trois). Le coût des jours récents est provisoire et peut être révisé à la hausse ; pour des comparaisons reproductibles, définissez ending_at à une valeur égale ou antérieure à un data_refreshed_at précédemment renvoyé (consultez Disponibilité et fraîcheur des données).

3. Agissez sur les membres signalés : ajustez le plafond avec POST /v1/organizations/spend_limits, ou contactez-les.

Augmenter temporairement la limite de dépenses d'un membre pendant un incident

Donnez à un intervenant sur incident la marge nécessaire pour travailler pendant qu'un incident est ouvert : augmentez son plafond de dépenses au début de l'incident, et rétablissez-le après la clôture de l'incident. Conditionnez l'augmentation à votre système de gestion des incidents, par exemple en exigeant un ID d'incident actif auquel le membre est affecté.

1. Lisez le plafond actuel du membre et enregistrez-le pour le rétablissement :

   cURL

   

   curl --globoff "https://api.anthropic.com/v1/organizations/spend_limits/effective?user_ids[]=user_01AbCdEfGh&period[]=monthly" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
     --header "anthropic-version: 2023-06-01"

2. Augmentez le plafond :

   cURL

   

   curl --request POST "https://api.anthropic.com/v1/organizations/spend_limits" \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --data '{"scope": {"type": "user", "user_id": "user_01AbCdEfGh"}, "amount": "500000", "period": "monthly"}'

3. Si les intervenants ont besoin d'un accès plus large pendant un incident, pré-provisionnez un groupe d'intervenants sur incident dont le rôle personnalisé l'accorde, et ajoutez-y le membre pour la durée de l'incident :

   cURL

   

   curl --request POST "https://api.anthropic.com/v1/organizations/rbac_groups/rbac_group_01UvWxYzAbCdEfGhIjKlMn/members" \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --data '{"user_id": "user_01AbCdEfGh"}'

   Consultez Gestion des utilisateurs pour les points de terminaison de groupe.

4. Lorsque votre système d'incidents marque l'incident comme clos, annulez les deux modifications : restaurez la limite de dépenses que vous avez enregistrée à l'étape 1 (ou supprimez la dérogation avec DELETE /v1/organizations/spend_limits/{spend_limit_id} si le membre n'en avait pas), et retirez le membre du groupe avec DELETE /v1/organizations/rbac_groups/{rbac_group_id}/members/{user_id}.

Foire aux questions

Définir directement une limite de dépenses résout-il la demande d'augmentation en attente d'un membre ?

Non. POST /v1/organizations/spend_limits écrit la dérogation mais laisse la demande en attente intacte. Utilisez POST /v1/organizations/spend_limit_increase_requests/{id}/approve pour résoudre la demande et écrire la dérogation en un seul appel.

Que se passe-t-il lorsque je supprime une dérogation par utilisateur ?

Le membre revient à ce qu'il hériterait de la hiérarchie : la valeur par défaut de son groupe, de son niveau de siège ou de l'organisation. Si aucune valeur par défaut n'existe à aucun niveau, le membre est illimité.

Puis-je définir une valeur par défaut au niveau du niveau de siège ou de l'organisation via cette API ?

Non. Seules les dérogations par utilisateur peuvent être écrites via cette API. Les valeurs par défaut au niveau du niveau de siège, du groupe et de l'organisation sont configurées dans les paramètres d'organisation de claude.ai.

Pourquoi period_to_date_spend affiche-t-il parfois "0" pour un membre actif ?

La lecture des dépenses peut être temporairement indisponible, auquel cas le champ affiche "0" plutôt que de générer une erreur. Traitez-le comme informatif.

Voir aussi