Las alertas de gasto, los bloqueos y los informes de gasto se están implantando de forma gradual. Hasta que se activen, las reglas y los ajustes se guardan, pero no se evalúa, bloquea ni envía nada.
Cómo funciona una regla
Una regla combina:- una métrica: qué se mide (consulta los tipos de alerta);
- un ámbito: qué gasto cuenta, como el del espacio de trabajo, el de una clave API o el de un departamento;
- un periodo: un día, una semana o un mes naturales, o una ventana continua de horas;
- umbrales: el importe en dólares o los porcentajes que envían una alerta;
- una acción:
notify, oblockpara rechazar además las solicitudes que superen un límite.
Tipos de alerta y bases
Los porcentajes se miden respecto a una base (
base_kind):
amount: un importe en dólares fijado en la regla, que solo se usa para las alertas.workspace_budget: el presupuesto del espacio de trabajo con el intervalo correspondiente (base_ref:dailypara un periodo de día,weeklypara una semana,monthlypara un mes). Un presupuesto de por vida no puede ser una base.key_limit: el límite de gasto de la clave API de la regla para la ventana correspondiente. Necesita el ámbito de clave.previous_period: el gasto en el mismo punto del periodo anterior, como «ayer a esta hora». En las reglas continuas es la ventana anterior; en las previsiones, todo el periodo anterior.
Ámbitos
El gasto de un departamento se atribuye por solicitud:
- Una clave asignada a un departamento cuenta solo para ese departamento.
- Si no, decide quien creó la clave: sus departamentos o, en las solicitudes OAuth, los departamentos del usuario que inició sesión.
- Quien pertenece a varios departamentos cuenta para todos de forma predeterminada. Elige Solo el departamento principal en lugar de Todos sus departamentos en Ajustes de gasto del espacio de trabajo (API:
spend.department_attribution: "primary") para contar solo su departamento principal. Si ninguno está marcado como principal, va primero un departamento al que se le añadió a mano y después el más antiguo.
Periodos y zonas horarias
El día, la semana y el mes son periodos naturales. Las semanas van de lunes a domingo. Cada regla puede tener su propiatime_zone de IANA, como Europe/London o America/New_York; si no, usa la zona horaria de facturación del espacio de trabajo, que es UTC de forma predeterminada. Cambia la zona horaria de facturación en Ajustes de gasto del espacio de trabajo o con spend.billing_time_zone en la API de ajustes de notificaciones. Los cambios de horario de verano se tienen en cuenta, y los nombres de zona distinguen mayúsculas y minúsculas.
Un periodo rolling abarca las últimas window_hours (de 1 a 720) y avanza de forma continua. Las reglas de pico lo usan como ventana del pico, y las de saldo como el tiempo sobre el que promedian el gasto.
Los límites de clave y los presupuestos del espacio de trabajo siempre se restablecen en los límites de UTC. Una regla con una base
workspace_budget o key_limit en otra zona horaria compara su propio día, semana o mes local con ese límite, así que su gasto puede diferir del que cuenta el límite.Umbrales y alertas repetidas
Según su métrica, una regla tiene de uno a cinco umbrales en porcentaje (de 1 a 1000) o un umbral en dólares.- En los periodos naturales, cada umbral envía como máximo una alerta por periodo. Cuando el gasto cruza varios umbrales a la vez, una sola alerta nombra el más alto y enumera los demás.
- Las reglas continuas, de pico y de saldo usan en su lugar
cooldown_minutes(de 5 a 43.200, 360 de forma predeterminada). Durante el periodo de espera solo un umbral más alto envía una alerta; después, la regla vuelve a avisar si el gasto sigue por encima. - Los umbrales ya enviados en este periodo no se vuelven a enviar al editar la regla.
[TEST], a los destinos de la regla. No se registra nada, y un espacio de trabajo puede enviar cinco pruebas por minuto. El Historial de cada regla enumera las alertas y los bloqueos que ha enviado.
Bloquear solicitudes
Una reglaspend o budget_percent con action: "block" avisa en sus umbrales y bloquea cuando el gasto alcanza el punto de bloqueo: block_at_percent de la base (110 de forma predeterminada, al menos el umbral más alto) o block_at_amount en una regla spend. Las reglas con una base previous_period no pueden bloquear. El espacio entre la última alerta y el punto de bloqueo es el margen de gracia: tu equipo recibe el aviso antes de que se detengan las solicitudes.
Mientras un bloqueo está activo, las solicitudes de su ámbito reciben
429 con el código de error spend_rule_blocked. El cuerpo incluye reason: "spend_rule_block", rule_id, rule_name, block_id, limit_scope, limit_value (USD) y reset_at. Retry-After indica los segundos que faltan para que se restablezca el periodo. Una regla continua no tiene hora de restablecimiento: su bloqueo dura hasta que el gasto de la ventana baja del punto de bloqueo, y la respuesta no incluye Retry-After. Un bloqueo de proveedor quita las rutas de ese proveedor, y la solicitud solo se rechaza cuando no queda otra ruta. Las sesiones en tiempo real todavía no se bloquean.
Mientras el gasto supera el último umbral de la regla pero no llega a su punto de bloqueo, las respuestas a las solicitudes de su ámbito incluyen un encabezado x-phaseo-spend-warning con hasta tres reglas, por ejemplo rule_id=…; scope=workspace; resets_at=2026-11-01T00:00:00.000Z. Los clientes pueden registrarlo o reducir el ritmo antes de que empiece el bloqueo.
Un bloqueo se levanta solo cuando se restablece el periodo, cuando el gasto de una regla continua baja de su punto de bloqueo, o cuando la regla se desactiva, se elimina o se cambia. Los propietarios y administradores pueden levantarlo en Alertas de gasto → Bloqueos activos o con POST /v1/spend-blocks/{id}/lift. Un bloqueo levantado no vuelve a empezar en el mismo periodo (en las reglas continuas, durante una ventana). Se envían notificaciones de bloqueos por gasto cuando un bloqueo empieza y cuando se levanta.
Saldo y autonomía
Una reglabalance vigila el saldo disponible del espacio de trabajo: su saldo de créditos menos los importes retenidos para las solicitudes en curso. Usa el ámbito del espacio de trabajo y un periodo continuo, y avisa cuando se cumple cualquiera de estas condiciones:
threshold_amount: el saldo disponible es igual o inferior a este importe;runway_days: con el gasto diario medio de las últimaswindow_hours, el saldo duraría menos de estos días. Sin gasto reciente no hay alerta de autonomía.
Previsión
Una reglaforecast proyecta en línea recta el gasto hasta el final del día, la semana o el mes actuales: el gasto hasta ahora dividido entre la parte del periodo que ya ha pasado. Espera a que hayan pasado 3 horas de un día, 24 horas de una semana o 72 horas de un mes, y a que se hayan gastado al menos 0,01 $, para que un inicio tranquilo no dispare una alerta. La alerta indica cuándo se alcanzará el límite al ritmo actual.
Fija un threshold_amount en dólares, o una base con porcentajes. Con una base previous_period, la proyección se compara con todo el periodo anterior. Cada umbral avisa una vez por periodo.
Pico
Una reglaspike compara el gasto de las últimas window_hours (de 1 a 56) con el gasto habitual para ese momento:
- En ventanas de menos de 24 horas, el gasto habitual es la mediana de las mismas horas de cada uno de los siete días anteriores. En ventanas más largas, es la mediana de las ventanas anteriores de la misma duración en los siete días anteriores.
- Avisa cuando el gasto es al menos
spike_multiplierveces el habitual (3 de forma predeterminada) y al menosspike_floor(5 $ de forma predeterminada). - Necesita gasto del espacio de trabajo en al menos tres de esas ventanas anteriores. Hasta entonces, el editor indica que todavía está aprendiendo. Cuando el gasto habitual es cero, solo se aplica el mínimo.
- Usa un periodo de espera (6 horas de forma predeterminada) y nunca bloquea.
Informes de gasto
Los propietarios reciben un informe semanal de gasto de forma predeterminada, y los administradores pueden activarlo. También hay informes diarios y mensuales. La guía de notificaciones del espacio de trabajo explica los ajustes y el contenido. Además:- Un informe se envía entre las 09:00 y las 21:00 en la zona horaria de facturación el primer día después de su periodo. Si no se puede enviar ese día, se omite en lugar de enviarse tarde.
- La previsión de un informe corresponde al mes de facturación actual.
- Los totales de miembros y departamentos incluyen los trabajos asíncronos y siguen la regla de departamentos anterior, así que pueden diferir ligeramente del total.
- Cada persona se da de baja de su propia copia del informe de un espacio de trabajo. Los miembros que no son propietarios ni administradores nunca lo reciben.
Enrutamiento y destinos
Las reglas de gasto envían tres tipos de notificación. Elige adónde va cada una en Configuración → Notificaciones:
Una regla puede tener sus propios destinos. Sustituyen las rutas Alertas de gasto y Bloqueos por gasto para esa regla; si están todos en pausa, las alertas de la regla no se envían a las rutas en su lugar. Las alertas y los bloqueos también llegan a la aplicación móvil de los propietarios y administradores, y de quien creó la clave o el miembro al que se refiere la regla.
Los webhooks personalizados reciben la alerta en JSON, con
title, message, rule_id, rule_name, metric, scope, period, value_nanos y, según la métrica, base_nanos, forecast, spike o los campos de saldo. Verifica cada entrega con su firma; consulta la sección sobre cómo verificar las firmas de webhook en las notificaciones del espacio de trabajo.
Gestionar reglas con la API
La API de reglas de gasto usa una clave de gestión conspend_rules:read, spend_rules:write o spend_rules:delete. Los importes se pueden enviar en dólares (threshold_amount_usd) o de forma exacta en nanodólares (threshold_amount_nanos), y las respuestas incluyen ambos.
GET /v1/spend-rules/{id}/preview para ver el valor actual y el siguiente umbral, y POST /v1/spend-rules/{id}/test para enviar una prueba. GET /v1/spend-blocks enumera los bloqueos activos. La zona horaria de facturación, la atribución por departamentos y los ajustes de informes están en el objeto spend de los ajustes de notificaciones.
Gestionar reglas con Terraform
El proveedor de Terraform de Phaseo (phaseoteam/phaseo) tiene los recursos phaseo_spend_rule y phaseo_workspace_budget, y las fuentes de datos phaseo_spend_rules, phaseo_spend_blocks y phaseo_workspace_budgets.