API dei limiti di spesa

L'API dei limiti di spesa ti consente di impostare un limite di spesa per ciascun membro di Claude Enterprise, verificare 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 la reportistica sull'utilizzo e sui costi per utente e suddivisa per intervalli temporali, consulta API di analisi.



Panoramica

L'API espone otto endpoint distribuiti 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 sono vicini a raggiungerlo?" 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 di ogni membro e la spesa accumulata nel periodo corrente:

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



Concetti chiave



La gerarchia dei limiti di spesa

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

La lettura di GET /v1/organizations/spend_limits/effective restituisce ogni membro corrente con il suo limite di spesa effettivo risolto, da dove tale limite è stato risolto (source) e la sua spesa accumulata nel periodo corrente. L'impostazione di un override per utente con POST /v1/organizations/spend_limits fissa un membro a un limite di spesa specifico indipendentemente da ciò che altrimenti erediterebbe. L'eliminazione dell'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 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 ambito come un insieme aperto; gestisci i valori sconosciuti con un fallback anziché generare un errore.



Periodo

period è la finestra ricorrente entro la quale viene applicato il limite di spesa e la spesa viene azzerata. Un limite di spesa è identificato dalla sua coppia (scope, period). Attualmente monthly è l'unico periodo supportato; la spesa mensile viene azzerata alle 00



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. Effettua il parsing come decimale e dividi per 100 per visualizzare i dollari; evita la virgola mobile binaria per valori elevati.

amount è nullable. Nella riga effettiva di un membro, null significa illimitato (nessun limite di spesa) e "0" significa che il membro non può utilizzare Claude oltre l'utilizzo incluso nel suo piano. In una riga di limite di spesa configurata (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 dei seguenti:

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. L'impostazione diretta di 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 su approve o deny per sopprimere quell'email (ad esempio, quando il tuo sistema notifica il membro).



Limitazione della frequenza

Tutti gli otto endpoint condividono un unico limite 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 vincolati ai filtri che li hanno generati. Se modifichi user_ids[], period[], status[] o actor_ids[] e passi un vecchio cursore, otterrai un errore 400 con "cursor does not match current query parameters". Avvia invece una nuova sequenza dalla prima pagina.



Serializzazione dei parametri lista

I parametri lista utilizzano 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 corrente, che riflette il limite di spesa effettivo di ciascun membro, la sua source nella gerarchia degli ambiti e il suo period_to_date_spend. Richiede l'ambito read:spend_limits.

Per i dettagli completi sui 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"

{
  "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_..."
}



Ottenere un singolo limite di spesa

GET /v1/organizations/spend_limits/{spend_limit_id} restituisce un limite di spesa configurato per ID. Usalo per ispezionare la riga a cui fa riferimento un campo spend_limit_id. Richiede l'ambito read:spend_limits.

Per i dettagli completi sui 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"



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): l'impostazione di un limite per un utente e un periodo che ne ha già uno lo sovrascrive in loco. Questo endpoint accetta solo scope.type: "user"; i valori predefiniti a livello di licenza, gruppo e organizzazione sono configurati nelle impostazioni di claude.ai. Richiede l'ambito write:spend_limits.

Per i dettagli completi sui 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" \
  --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 licenza, gruppo o organizzazione. Le righe a livello di licenza, gruppo e organizzazione non possono essere eliminate tramite questo endpoint. Richiede l'ambito write:spend_limits.

Per i dettagli completi sui 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"



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 l'ambito read:spend_limits.

Per i dettagli completi sui parametri e gli schemi di risposta, consulta Elencare le richieste di aumento del limite di spesa nel riferimento API.

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

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 per ID. Richiede l'ambito read:spend_limits.

Per i dettagli completi sui 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"



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 con l'amount fornito dall'amministratore per il richiedente e fa transitare la richiesta a approved. La richiesta non contiene un importo richiesto; fornisci il nuovo limite di spesa al momento dell'approvazione. Richiede l'ambito write:spend_limits.

Per i dettagli completi sui 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" \
  --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 rifiuta un tentativo di negare una richiesta già approvata, così l'automazione può distinguere un nuovo tentativo da una decisione in conflitto. Richiede l'ambito write:spend_limits.

Per i dettagli completi sui 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" \
  --data '{"suppress_notification": true}'



Flussi di lavoro di esempio

Questi flussi di lavoro combinano l'API dei limiti di spesa con gli endpoint dei costi delle API di analisi. Gli endpoint dei costi di Analytics sono progettati per la reportistica della spesa a livello di organizzazione su un intervallo di date. GET /spend_limits/effective restituisce il tetto massimo attualmente applicato a ciascun membro. Inizia una scansione con Analytics per scoprire quali membri esaminare, quindi leggi i loro tetti massimi correnti con /effective.

Gli endpoint dei limiti di spesa richiedono gli ambiti spend_limits e gli endpoint dei costi di Analytics richiedono read:analytics; consulta API di analisi per sapere come configurare l'accesso. Tutti i valori monetari su entrambi 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 "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests?status[]=pending&limit=100" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

   Ogni richiesta contiene 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 instrada i tetti massimi più elevati per la revisione manuale.

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

   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" \
     --data '{"amount": "75000", "suppress_notification": true}'

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



Identificare i membri vicini al loro limite di spesa

Trova i membri che si stanno avvicinando al loro tetto massimo così puoi aumentarlo prima che vengano bloccati.

1. Recupera la spesa mensile accumulata di ciascun membro dall'API di analisi (una riga per membro, spesa più alta per prima per impostazione predefinita):

   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"

   Ogni riga contiene 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 massimi effettivi in batch:

   cURL

   

   curl "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"

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

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

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



Trovare membri con utilizzo in rapida evoluzione

Individua i membri la cui spesa è aumentata notevolmente settimana su settimana.

1. Recupera il costo giornaliero per membro per le ultime due settimane dall'API di analisi:

   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"

   Con bucket_width impostato, ogni membro occupa una riga per 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 scelto (ad esempio, tre). Il costo dei giorni recenti è provvisorio e può essere rivisto al rialzo; per confronti ripetibili, imposta ending_at pari o precedente a un data_refreshed_at restituito in precedenza (consulta Disponibilità e aggiornamento dei dati).

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



Domande frequenti



L'impostazione diretta di 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 ciò che erediterebbe dalla gerarchia: il valore predefinito del suo gruppo, del livello di licenza o dell'organizzazione. Se non esiste alcun valore predefinito a nessun livello, il membro è illimitato.



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

No. Solo gli override per utente possono essere scritti tramite questa API. I valori predefiniti a livello di licenza, gruppo e organizzazione sono configurati 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