Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Limiti di spesa

Lezione 7 di 14 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Controlla i costi delle tue API
  2. Visualizza i limiti attuali
  3. Imposta i limiti
  4. Visualizza gli addebiti correnti
  5. Automatizza il monitoraggio dei costi
  6. Regola i limiti dinamicamente
  7. Punti chiave

Controlla i costi delle tue API

I limiti di spesa sono la tua rete di sicurezza finanziaria. Stabiliscono un tetto oltre il quale le richieste API vengono rifiutate, prevenendo addebiti imprevisti a fine mese. L’API di gestione ti consente di visualizzare e impostare questi limiti a livello programmatico.

Visualizza i limiti attuali

curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/spending-limits" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

La risposta mostra il tetto attuale del ciclo e il tuo consumo corrente: per differenza, ottieni il margine residuo. Questo è l’unico numero che conta giorno per giorno: un tetto senza dati di consumo non ti dice se sei al 10% o al 95% del tuo budget.

Imposta i limiti

curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/spending-limits" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "monthlyLimit": 500.00
  }'

Comportamento al superamento del limite

Ecco la parte rassicurante, che vale la pena esplicitare: raggiungere il limite non genera mai un sovraccarico. Le richieste vengono rifiutate, non fatturate oltre il tetto. Il rischio si sposta dall’ambito finanziario a quello della disponibilità, ed è esattamente ciò che desideri: un’interruzione viene diagnosticata e risolta in pochi minuti, mentre una fattura imprevista viene scoperta troppo tardi.

Quando il consumo raggiunge il limite impostato:

  • Le richieste API vengono rifiutate con un codice di errore specifico
  • Le chiavi API restano attive, ma le chiamate di inferenza falliscono
  • Il limite si resetta all’inizio del ciclo di fatturazione successivo

Strategia dei limiti per ambiente

Per un team con più progetti, il limite deve riflettere il rischio specifico di ogni ambiente. In sviluppo, il pericolo tipico è un loop accidentale di richieste, come uno script di test eseguito tutta la notte: un limite basso tra 50 $ e 100 $ trasforma quell’errore in un incidente da 10 $ invece che in una sorpresa da 1.000 $. Lo staging gestisce test di carico, che consumano legittimamente di più: un limite moderato tra 200 $ e 500 $ lascia spazio alle campagne di test mantenendo una guardia. La produzione, invece, non deve mai essere limitata al punto da rifiutare le richieste dei clienti: un limite più alto (1.000 $ e oltre, a seconda del tuo traffico) si accompagna a un monitoraggio attivo; l’avviso ti protegge, mentre il limite è solo la rete di sicurezza dell’ultima istanza.

Visualizza gli addebiti correnti

Per capire a che punto sei nel ciclo corrente:

curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/invoice/preview" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Questo endpoint restituisce gli addebiti accumulati dall’inizio del ciclo. Confrontandolo con i giorni trascorsi, ottieni più di un’istantanea: una proiezione. Consumare il 40% del budget a un terzo del mese è sano; lo stesso 40% a un decimo del mese segnala uno sforamento, e hai ancora ventisette giorni per agire.

Automatizza il monitoraggio dei costi

Script di avviso per soglia

import requests

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
ALERT_THRESHOLD = 0.80  # Avviso all'80% del limite

# Ottieni il limite
limits_resp = requests.get(
    f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/postpaid/spending-limits",
    headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
monthly_limit = limits_resp.json().get("monthlyLimit", 0)

# Ottieni il consumo corrente
preview_resp = requests.get(
    f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/postpaid/invoice/preview",
    headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
current_spend = preview_resp.json().get("totalAmount", 0)

# Controlla la soglia
if monthly_limit > 0:
    ratio = current_spend / monthly_limit
    if ratio >= ALERT_THRESHOLD:
        print(f"ALERT: {ratio*100:.1f}% of limit reached")
        print(f"  Spend: ${current_spend:.2f} / ${monthly_limit:.2f}")
        # Invia notifica

Integrazione con il monitoraggio

Combina l’anteprima degli addebiti con la tua soluzione di monitoraggio (Grafana, Datadog, ecc.) per creare dashboard dei costi in tempo reale:

# Ottieni l'importo corrente da inviare al tuo sistema di metriche
CURRENT_SPEND=$(curl -s "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/invoice/preview" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('totalAmount', 0))")

echo "xai.billing.current_spend:$CURRENT_SPEND|g" | nc -u -w1 localhost 8125

Regola i limiti dinamicamente

Il limite non è scolpito nella pietra per l’intero ciclo di fatturazione, ed è un bene, perché il ciclo di vita del prodotto non segue il calendario contabile. Prima di un picco di traffico previsto, un lancio di prodotto o una campagna marketing, aumenta temporaneamente il limite: niente di peggio di una campagna a pagamento che invia utenti a un servizio la cui API rifiuta le richieste perché ha raggiunto il tetto. Al contrario, se il budget del mese viene speso più velocemente del previsto, abbassare il limite per il resto del ciclo trasforma una deriva in un vincolo controllato. Il caso più critico resta un incidente di costo, come un loop in produzione o un abuso rilevato: abbassare immediatamente il limite è il tuo pulsante di emergenza, quello che ferma l’emorragia mentre ne individui la causa.

# Aumenta temporaneamente per un lancio
curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/spending-limits" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"monthlyLimit": 2000.00}'

# Ripristina il limite normale dopo il picco
curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/spending-limits" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"monthlyLimit": 500.00}'

Punti chiave

  • Usa GET e POST su /v1/billing/teams/{teamId}/postpaid/spending-limits per visualizzare e impostare i limiti
  • Quando il limite viene superato, le richieste API vengono rifiutate (nessun sovraccarico)
  • L’anteprima degli addebiti (invoice/preview) ti permette di tracciare il consumo in tempo reale
  • Automatizza gli avvisi di soglia per anticipare gli sforamenti
  • Adatta i limiti in base all’ambiente (dev, staging, production)