API Spend Limits

L'API Spend Limits ti consente di impostare uno "spend limit" (limite di spesa) per ciascun membro di Claude Enterprise, vedere da dove viene ereditato il limite di spesa di ciascun membro e rivedere o gestire le richieste dei membri per un limite più alto.

Per il reporting di utilizzo e costi per utente e per intervalli temporali, consulta API Analytics.

Panoramica

L'API espone otto endpoint su due risorse:

Usa gli endpoint dei limiti di spesa per rispondere a "quale limite di spesa si applica a ciascun membro, da dove proviene e quanto ci sono vicini?" e per impostare un override per utente. Usa gli endpoint delle richieste di aumento del limite di spesa per gestire la coda delle richieste inviate dai membri.

Prerequisiti

• La tua organizzazione deve avere un piano Claude Enterprise.
• I crediti di utilizzo devono essere attivati per la tua organizzazione. Il tuo proprietario principale può attivarli nelle impostazioni di fatturazione di claude.ai.

Avvio rapido

Elenca il limite di spesa mensile effettivo e la spesa accumulata nel periodo di ogni membro:

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"

Concetti chiave

La gerarchia dei limiti di spesa

Un limite di spesa effettivo si applica alla spesa di ciascun membro, risolto a partire da una gerarchia di livelli di scope. Quando un membro non ha un override per utente, eredita il limite di spesa configurato per il suo gruppo (se la tua organizzazione usa limiti basati sui gruppi), il suo livello di seat o il valore predefinito a livello di organizzazione. Un limite di spesa di gruppo è un valore predefinito per membro: ogni membro che lo eredita è vincolato rispetto alla propria spesa, non a un budget di gruppo condiviso.

La lettura di GET /v1/organizations/spend_limits/effective restituisce ogni membro attuale con il suo limite di spesa effettivo risolto, da dove quel limite è stato risolto (source) e la sua spesa accumulata nel periodo. Impostare un override per utente con POST /v1/organizations/spend_limits vincola un membro a un limite di spesa specifico indipendentemente da ciò che altrimenti erediterebbe. Eliminare l'override lo riporta al limite di spesa ereditato (o lo lascia illimitato se non ne esiste alcuno).

Il campo source nella riga di ciascun membro ti indica da quale livello è stato risolto il suo limite di spesa: user (un override per utente), seat_tier, rbac_group o organization. Tratta i tipi di scope come un insieme aperto; gestisci i valori sconosciuti con un comportamento di fallback anziché fallire.

Periodo

period è la finestra ricorrente su cui il limite di spesa viene applicato e la spesa si azzera. Un limite di spesa è identificato dalla sua coppia (scope, period). Attualmente monthly è l'unico periodo supportato; la spesa mensile si azzera alle 00:00 UTC del primo giorno di ogni mese di calendario. Tratta period come un insieme aperto.

Importi e valuta

Tutti i valori monetari sono stringhe in unità minori della valuta di fatturazione dell'organizzazione (centesimi, per USD). Ad esempio, "50000" rappresenta 500,00 USD. Analizza il valore come decimale e dividi per 100 per visualizzare i dollari; evita la virgola mobile binaria per valori grandi.

amount è nullable. Nella riga effettiva di un membro, null significa illimitato (nessun limite di spesa) e "0" significa che il membro non può usare Claude oltre l'utilizzo incluso nel suo piano. In una riga di limite di spesa configurato (come restituita da GET /v1/organizations/spend_limits/{id}), null significa solo che non è impostato alcun limite di spesa numerico; leggi la riga effettiva del membro per distinguere tra illimitato e solo utilizzo incluso.

period_to_date_spend è la spesa del membro accumulata dall'inizio del period corrente, nello stesso formato in unità minori; può includere una parte frazionaria (ad esempio, "41280.125"). Può risultare "0" se la lettura della spesa è temporaneamente non disponibile; trattalo come informativo, non transazionale.

Ciclo di vita delle richieste di aumento

Una richiesta di aumento del limite di spesa viene creata quando un membro fa clic su Request more usage in claude.ai. Le richieste non vengono create tramite questa API. Lo status di una richiesta è uno tra:

Sia approved che denied sono stati terminali. Un membro ha al massimo una richiesta pending alla volta.

L'approvazione con POST /v1/organizations/spend_limit_increase_requests/{id}/approve scrive la stessa riga di limite di spesa per utente che scrive POST /v1/organizations/spend_limits. Impostare direttamente un limite di spesa non fa transitare una richiesta in sospeso; usa l'endpoint di approvazione per risolvere una richiesta.

Per impostazione predefinita, Anthropic invia un'email al membro quando la sua richiesta viene approvata o rifiutata. Passa suppress_notification: true nell'approvazione o nel rifiuto per sopprimere quell'email (ad esempio, quando il tuo sistema notifica il membro autonomamente).

Controllo delle versioni

Invia l'header anthropic-version in ogni richiesta; consulta Versioni dell'API per le versioni disponibili.

Limitazione della velocità

Tutti gli otto endpoint condividono un unico "rate limit" (limite di velocità) per organizzazione di 60 richieste al minuto. Le richieste oltre il limite restituiscono 429 Too Many Requests.

Paginazione

GET /v1/organizations/spend_limits/effective e GET /v1/organizations/spend_limit_increase_requests sono paginati con un cursore opaco. La prima richiesta restituisce fino a limit righe più un cursore next_page; passa quel cursore invariato come parametro page nella richiesta successiva e ripeti finché next_page non è null.

Non modificare i parametri di query a metà sequenza. I cursori sono legati ai filtri che li hanno emessi. Se modifichi user_ids[], period[], status[] o actor_ids[] e passi un vecchio cursore, otterrai un 400 con "cursor does not match current query parameters". Avvia invece una nuova sequenza dalla prima pagina.

Serializzazione dei parametri lista

I parametri lista usano la notazione con parentesi quadre: ripeti il nome del parametro con [] per ogni valore.

user_ids[]=user_01AbCdEfGh&user_ids[]=user_01JkLmNoPq

Risposte di errore

Le risposte di errore seguono la forma standard documentata in Errori. Cita il request_id dal corpo della risposta quando contatti il supporto.

Limiti di spesa

Elencare il limite di spesa effettivo di ciascun membro

GET /v1/organizations/spend_limits/effective restituisce una riga per ogni membro attuale, che riflette il limite di spesa effettivo di ciascun membro, la sua source nella gerarchia degli scope e il suo period_to_date_spend. Richiede lo scope read:spend_limits.

Per i dettagli completi dei parametri e gli schemi di risposta, consulta Elencare i limiti di spesa effettivi nel riferimento 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_..."
}

Ottenere un singolo limite di spesa

GET /v1/organizations/spend_limits/{spend_limit_id} restituisce un limite di spesa configurato tramite ID. Usalo per ispezionare la riga a cui faceva riferimento un campo spend_limit_id. Richiede lo scope read:spend_limits.

Per i dettagli completi dei parametri e gli schemi di risposta, consulta Recuperare un limite di spesa nel riferimento 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"

Impostare un override per utente

POST /v1/organizations/spend_limits imposta un override del limite di spesa per utente. Si tratta di un upsert con chiave (scope, period): impostare un limite per un utente e un periodo che ne ha già uno lo sovrascrive sul posto. Questo endpoint accetta solo scope.type: "user"; i valori predefiniti a livello di seat, gruppo e organizzazione si configurano nelle impostazioni di claude.ai. Richiede lo scope write:spend_limits.

Per i dettagli completi dei parametri e gli schemi di risposta, consulta Creare un limite di spesa nel riferimento 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"
}

Rimuovere un override per utente

DELETE /v1/organizations/spend_limits/{spend_limit_id} rimuove un override per utente, dopodiché il membro torna a qualsiasi valore predefinito ereditato a livello di seat, gruppo o organizzazione. Le righe a livello di seat, gruppo e organizzazione non possono essere eliminate tramite questo endpoint. Richiede lo scope write:spend_limits.

Per i dettagli completi dei parametri e gli schemi di risposta, consulta Eliminare un limite di spesa nel riferimento 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"

Richieste di aumento del limite di spesa

Elencare le richieste di aumento

GET /v1/organizations/spend_limit_increase_requests elenca le richieste, dalla più recente. Filtra per status[] (pending, approved, denied) e actor_ids[]. L'elenco esclude le richieste il cui richiedente non è più membro dell'organizzazione. Richiede lo scope read:spend_limits.

Per i dettagli completi dei parametri e gli schemi di risposta, consulta Elencare le richieste di aumento del limite di spesa nel riferimento 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"

Ogni richiesta in sospeso include uno spend_summary aggiornato in tempo reale che mostra il limite di spesa effettivo corrente del richiedente e la spesa accumulata nel periodo, sufficiente per decidere senza una ricerca separata.

Ottenere una singola richiesta di aumento

GET /v1/organizations/spend_limit_increase_requests/{id} restituisce una richiesta tramite ID. Richiede lo scope read:spend_limits.

Per i dettagli completi dei parametri e gli schemi di risposta, consulta Recuperare una richiesta di aumento del limite di spesa nel riferimento 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"

Approvare una richiesta di aumento

POST /v1/organizations/spend_limit_increase_requests/{id}/approve approva una richiesta in sospeso: scrive un limite di spesa per utente all'amount fornito dall'amministratore per il richiedente e fa transitare la richiesta a approved. La richiesta non include un importo richiesto; fornisci tu il nuovo limite di spesa al momento dell'approvazione. Richiede lo scope write:spend_limits.

Per i dettagli completi dei parametri e gli schemi di risposta, consulta Approvare una richiesta di aumento del limite di spesa nel riferimento 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}'

Rifiutare una richiesta di aumento

POST /v1/organizations/spend_limit_increase_requests/{id}/deny rifiuta una richiesta in sospeso. Idempotente su denied: rifiutare una richiesta già rifiutata restituisce 200 con la risorsa esistente. L'endpoint respinge un tentativo di rifiutare una richiesta già approvata, in modo che l'automazione possa distinguere un nuovo tentativo da una decisione in conflitto. Richiede lo scope write:spend_limits.

Per i dettagli completi dei parametri e gli schemi di risposta, consulta Rifiutare una richiesta di aumento del limite di spesa nel riferimento 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}'

Flussi di lavoro di esempio

Alcuni di questi flussi di lavoro combinano l'API Spend Limits con gli endpoint di costo delle API Analytics. Gli endpoint di costo di Analytics sono progettati per il reporting della spesa a livello di organizzazione su un intervallo di date. GET /spend_limits/effective restituisce il tetto che si applica attualmente a ciascun membro. Avvia una scansione con Analytics per scoprire quali membri esaminare, quindi leggi i loro tetti attuali con /effective.

Gli endpoint Spend Limits richiedono gli scope spend_limits e gli endpoint di costo di Analytics richiedono read:analytics; consulta API Analytics per sapere come fornire l'accesso. Tutti i valori monetari in entrambe sono stringhe decimali in unità minori (centesimi). Entrambe le API paginano con un cursore opaco. Imposta un limit esplicito e scorri le pagine tramite next_page finché non è null per coprire l'intera organizzazione.

Automatizzare il flusso di revisione delle richieste di aumento

Esegui un job pianificato che recupera le richieste in sospeso, applica la policy di approvazione della tua organizzazione e risolve ciascuna di esse.

1. Elenca le richieste in sospeso:

   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"

   Ogni richiesta include l'actor.user_id del richiedente e uno spend_summary aggiornato in tempo reale con il suo amount effettivo corrente e period_to_date_spend, sufficiente per decidere senza una ricerca separata.

2. Applica la tua policy. Ad esempio, approva automaticamente quando l'amount corrente del membro è al di sotto di una soglia e indirizza i tetti più alti alla revisione manuale.

3. Risolvi ciascuna richiesta. Per approvare, fornisci il nuovo tetto:

   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}'

   Per rifiutare, esegui invece un POST a .../{id}/deny. Passa suppress_notification: true quando il tuo sistema notifica il richiedente autonomamente.

Identificare i membri vicini al loro limite di spesa

Trova i membri che si avvicinano al loro tetto in modo da poterlo aumentare prima che vengano bloccati.

1. Recupera la spesa del mese in corso di ciascun membro dall'API Analytics (una riga per membro, per impostazione predefinita dalla spesa più alta):

   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"

   Ogni riga include actor.user_id, actor.email e amount (la spesa del membro in centesimi). Scorri le pagine tramite next_page per coprire l'intera organizzazione.

2. Per i membri con la spesa più alta (o tutti quelli al di sopra di una soglia in dollari), recupera i tetti effettivi in batch:

   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"

   Ogni riga restituisce il tetto come amount (null = illimitato, "0" = solo utilizzo incluso) insieme a period_to_date_spend.

3. Per ogni membro con un tetto positivo, calcola period_to_date_spend / amount e segnala quelli pari o superiori alla tua soglia (ad esempio, l'80 percento). Tratta un tetto "0" come già al limite. Non esiste un filtro lato server per questo rapporto.

4. Agisci sui membri segnalati: aumenta il tetto con POST /v1/organizations/spend_limits, approva una richiesta di aumento in sospeso se ne esiste una, oppure contatta il membro.

Trovare i membri con utilizzo in rapido cambiamento

Individua i membri la cui spesa è aumentata bruscamente di settimana in settimana.

1. Recupera il costo giornaliero per membro delle ultime due settimane dall'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"

   Con bucket_width impostato, ogni membro occupa una riga per ogni giorno con utilizzo; scorri le pagine tramite next_page per raccogliere la serie completa di ogni membro.

2. Raggruppa le righe per actor.user_id. Per ogni membro, somma i sette giorni più recenti e i sette giorni precedenti. Segnala i membri la cui settimana recente supera la settimana precedente del multiplo da te scelto (ad esempio, tre). Il costo dei giorni recenti è provvisorio e può essere rivisto al rialzo; per confronti ripetibili, imposta ending_at a un valore pari o precedente a un data_refreshed_at restituito in precedenza (consulta Disponibilità e aggiornamento dei dati).

3. Agisci sui membri segnalati: regola il tetto con POST /v1/organizations/spend_limits, oppure contattali.

Aumentare temporaneamente il limite di spesa di un membro durante un incidente

Dai a chi risponde a un incidente margine per lavorare mentre l'incidente è aperto: aumenta il suo tetto di spesa quando l'incidente inizia e ripristinalo dopo la chiusura dell'incidente. Vincola l'aumento al tuo sistema di gestione degli incidenti, ad esempio richiedendo un ID di incidente attivo con il membro assegnato ad esso.

1. Leggi il tetto attuale del membro e registralo per il ripristino:

   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. Aumenta il tetto:

   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. Se chi risponde agli incidenti necessita di un accesso più ampio durante un incidente, predisponi in anticipo un gruppo incident-responders il cui ruolo personalizzato lo conceda, e aggiungi il membro per la durata dell'incidente:

   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"}'

   Consulta Gestione utenti per gli endpoint dei gruppi.

4. Quando il tuo sistema di gestione degli incidenti contrassegna l'incidente come chiuso, annulla entrambe le modifiche: ripristina il limite di spesa registrato al passaggio 1 (oppure elimina l'override con DELETE /v1/organizations/spend_limits/{spend_limit_id} se il membro non ne aveva uno) e rimuovi il membro dal gruppo con DELETE /v1/organizations/rbac_groups/{rbac_group_id}/members/{user_id}.

Domande frequenti

Impostare direttamente un limite di spesa risolve la richiesta di aumento in sospeso di un membro?

No. POST /v1/organizations/spend_limits scrive l'override ma lascia intatta la richiesta in sospeso. Usa POST /v1/organizations/spend_limit_increase_requests/{id}/approve per risolvere la richiesta e scrivere l'override in un'unica chiamata.

Cosa succede quando elimino un override per utente?

Il membro torna a qualsiasi valore erediterebbe dalla gerarchia: il valore predefinito del suo gruppo, del suo livello di seat o dell'organizzazione. Se non esiste alcun valore predefinito a nessun livello, il membro è illimitato.

Posso impostare un valore predefinito a livello di seat o di organizzazione tramite questa API?

No. Solo gli override per utente possono essere scritti tramite questa API. I valori predefiniti a livello di seat, gruppo e organizzazione si configurano nelle impostazioni dell'organizzazione di claude.ai.

Perché period_to_date_spend a volte risulta "0" per un membro attivo?

La lettura della spesa può essere temporaneamente non disponibile, nel qual caso il campo risulta "0" anziché generare un errore. Trattalo come informativo.

Vedi anche