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ù elevato.

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 alla domanda "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 riporta il membro 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 autonomamente).



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 cursore precedente, riceverai 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 struttura 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, il suo 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 in base all'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): impostare 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 in base all'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 all'amount fornito dall'amministratore per il richiedente e fa transitare la richiesta allo stato approved. La richiesta non contiene un importo richiesto; sei tu a fornire 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 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 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}'



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 ciò che erediterebbe dalla gerarchia: il valore predefinito del suo gruppo, del suo 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