Límites de gasto
En esta página
Controla los costes de tu API
Los límites de gasto son tu red de seguridad financiera. Establecen un techo más allá del cual se rechazan las solicitudes a la API, evitando cargos inesperados a final de mes. La Management API te permite consultar y configurar estos límites de forma programática.
Consultar los límites actuales
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/spending-limits" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
La respuesta muestra el techo del ciclo actual y tu consumo acumulado; por diferencia, obtienes el margen restante. Este es el único número que importa en el día a día: un techo sin datos de consumo no te indica si estás al 10 % o al 95 % de tu presupuesto.
Establecer límites
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
}'
Comportamiento al superar el límite
Aquí viene la parte tranquilizadora, y merece la pena decirlo explícitamente: alcanzar el límite nunca genera sobrefacturación. Las solicitudes se rechazan, no se facturan por encima del tope. El riesgo pasa de ser financiero a de disponibilidad, que es exactamente lo que buscas, porque una interrupción se diagnostica y soluciona en minutos, mientras que una factura inesperada se descubre demasiado tarde.
Cuando el consumo alcanza el límite establecido:
- Las solicitudes a la API se rechazan con un código de error específico
- Las claves de API siguen activas, pero las llamadas de inferencia fallan
- El límite se restablece al inicio del siguiente ciclo de facturación
Estrategia de límites por entorno
Para un equipo con varios proyectos, el límite debe reflejar el riesgo específico de cada entorno. En desarrollo, el peligro habitual es un bucle accidental de solicitudes (un script de prueba ejecutándose toda la noche); un límite bajo de 50 $ a 100 $ convierte ese error en un incidente de 10 $ en lugar de una sorpresa de 1.000 $. El entorno de staging gestiona pruebas de carga, que consumen legítimamente más: un límite moderado de 200 $ a 500 $ deja margen para campañas de prueba manteniendo una barrera de seguridad. La producción, sin embargo, nunca debe verse limitada hasta el punto de rechazar solicitudes de clientes: un límite más alto (1.000 $ y superiores, según tu tráfico) va acompañado de monitorización activa; la alerta te protege, mientras que el límite es simplemente la red de seguridad de último recurso.
Consultar los cargos actuales
Para saber dónde estás en el ciclo actual:
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/invoice/preview" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Este endpoint devuelve los cargos acumulados desde el inicio del ciclo. Comparado con los días transcurridos, ofrece algo más que una instantánea: una proyección. Consumir el 40 % del presupuesto cuando ha transcurrido un tercio del mes es saludable; ese mismo 40 % al décimo del mes señala un desvío, y aún tienes veintisiete días para actuar.
Automatizar la monitorización de costes
Script de alerta por umbral
import requests
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
ALERT_THRESHOLD = 0.80 # Alertar al alcanzar el 80 % del límite
# Obtener el límite
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)
# Obtener el consumo actual
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)
# Comprobar el umbral
if monthly_limit > 0:
ratio = current_spend / monthly_limit
if ratio >= ALERT_THRESHOLD:
print(f"ALERTA: se ha alcanzado el {ratio*100:.1f}% del límite")
print(f" Gasto: ${current_spend:.2f} / ${monthly_limit:.2f}")
# Enviar notificación
Integración con sistemas de monitorización
Combina la vista previa de cargos con tu solución de monitorización (Grafana, Datadog, etc.) para crear paneles de costes en tiempo real:
# Obtener el importe actual para enviarlo a tu sistema de métricas
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
Ajustar límites dinámicamente
El límite no está grabado en piedra para todo el ciclo de facturación, y eso es positivo, porque el ciclo de vida del producto no sigue el calendario contable. Antes de un pico de tráfico esperado, un lanzamiento de producto o una campaña de marketing, aumenta temporalmente el límite: nada peor que una campaña pagada que envíe usuarios a un servicio cuya API rechaza solicitudes por haber alcanzado el techo. Por el contrario, si el presupuesto del mes se gasta más rápido de lo previsto, reducir el límite para el resto del ciclo convierte la deriva en una restricción controlada. El caso más crítico sigue siendo un incidente de costes (un bucle en producción, un abuso detectado): bajar el límite inmediatamente es tu botón de parada de emergencia, el que detiene la sangría mientras buscas la causa.
# Aumentar temporalmente para un lanzamiento
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}'
# Restablecer el límite normal tras el pico
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}'
Puntos clave
- Usa
GETyPOSTen/v1/billing/teams/{teamId}/postpaid/spending-limitspara consultar y establecer límites - Al superar el límite, las solicitudes a la API se rechazan (sin sobrefacturación)
- La vista previa de cargos (
invoice/preview) te permite seguir el consumo en tiempo real - Automatiza alertas por umbral para anticipar desviaciones
- Adapta los límites según el entorno (dev, staging, production)