API des limites de dépenses

L'API des limites de dépenses vous permet de définir une limite de dépenses pour chaque membre de Claude Enterprise, de consulter l'origine de la limite de dépenses héritée par chaque membre, et d'examiner ou de traiter les demandes des membres souhaitant une limite plus élevée.

Pour les rapports d'utilisation et de coûts par utilisateur et par intervalle de temps, consultez les API d'analyse.



Vue d'ensemble

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

Utilisez les points de terminaison des limites de dépenses pour répondre à la question « quelle limite de dépenses s'applique à chaque membre, d'où provient-elle, et dans quelle mesure s'en approchent-ils ? » et pour définir un remplacement par utilisateur. Utilisez les points de terminaison des demandes d'augmentation de limite de dépenses pour traiter la file d'attente 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"



Concepts clés



La hiérarchie des limites de dépenses

Une 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 remplacement 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 à l'échelle 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. La définition d'un remplacement par utilisateur avec POST /v1/organizations/spend_limits fixe un membre à une limite de dépenses spécifique, indépendamment de ce dont il hériterait autrement. La suppression du remplacement le ramène à la limite de dépenses héritée (ou le laisse sans limite si aucune n'existe).

Le champ source sur la ligne de chaque membre vous indique de quel niveau sa limite de dépenses a été résolue : user (un remplacement par utilisateur), seat_tier, rbac_group, ou organization. Traitez les types de portée comme un ensemble ouvert ; passez outre 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



Montants et devise

Toutes les valeurs monétaires sont des chaînes de caractères en unités mineures de la devise de facturation de l'organisation (cents, pour l'USD). Par exemple, "50000" représente 500,00 USD. Analysez la valeur 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 l'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 actuelle, dans le même format d'unités mineures ; elle peut inclure une partie fractionnaire (par exemple, "41280.125"). Elle peut afficher "0" si la lecture des dépenses est temporairement indisponible ; traitez-la comme informative, et non transactionnelle.



Cycle de vie des demandes d'augmentation

Une demande d'augmentation de limite de dépenses est créée lorsqu'un membre clique sur Demander plus d'utilisation dans claude.ai. Les demandes ne sont pas créées via cette API. Le status d'une demande est l'un des suivants :

Les statuts approved et denied sont tous deux terminaux. Un membre a au plus une demande pending à la fois.

L'approbation avec POST /v1/organizations/spend_limit_increase_requests/{id}/approve écrit la même ligne de limite de dépenses par utilisateur que 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).



Limitation de débit

Les huit points de terminaison partagent une seule limite 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 inchangé 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 ». Démarrez 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 de portée, 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"

{
  "data": [
    {
      "scope": { "type": "user", "user_id": "user_01AbCdEfGh" },
      "actor": {
        "type": "user_actor",
        "user_id": "user_01AbCdEfGh",
        "name": "Jane Smith",
        "email_address": "[email protected]",
        "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 limite de dépenses unique

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"



Définir un remplacement par utilisateur

POST /v1/organizations/spend_limits définit un remplacement de limite de dépenses par utilisateur. Il s'agit d'un « upsert » (insertion ou mise à jour) basé sur la clé (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 accepte uniquement scope.type: "user" ; les valeurs par défaut au niveau du 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" \
  --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 un remplacement par utilisateur

DELETE /v1/organizations/spend_limits/{spend_limit_id} supprime un remplacement par utilisateur, après quoi le membre revient à toute valeur par défaut héritée au niveau du siège, du groupe ou de l'organisation. Les lignes au niveau du 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"



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 "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests?status[]=pending&limit=50" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

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



Obtenir une demande d'augmentation unique

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"



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 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" \
  --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 une tentative de refus d'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" \
  --data '{"suppress_notification": true}'



Questions fréquentes



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 le remplacement mais laisse la demande en attente intacte. Utilisez POST /v1/organizations/spend_limit_increase_requests/{id}/approve pour résoudre la demande et écrire le remplacement en un seul appel.



Que se passe-t-il lorsque je supprime un remplacement par utilisateur ?

Le membre revient à ce dont 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 siège ou de l'organisation via cette API ?

Non. Seuls les remplacements par utilisateur peuvent être écrits via cette API. Les valeurs par défaut au niveau du 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