PHphaseo
Gateway

Create a spend rule

Changed on

Creates a spend rule and sets its notification destinations. Every metric is evaluated. Blocking is best effort and acts minutes after the threshold; use key limits and workspace budgets for exact caps. A workspace can have 50 spend rules.

post/spend-rules

Request

  • Base URL
    https://api.phaseo.app/v1
  • URL
    https://api.phaseo.app/v1/spend-rules
  • Auth
    HTTP bearer

Request body

namestring required
enabledboolean
metric'spend' | 'budget_percent' | 'forecast' | 'spike' | 'balance' required

spend: spend reached threshold_amount. budget_percent: spend reached threshold_percents of the base. forecast: spend projected to the period end reaches the threshold. spike: spend over the last window_hours is at least spike_multiplier times the median of the same window over the previous 7 days, and at least spike_floor. balance: the workspace balance or runway falls below the threshold.

scope_type'workspace' | 'key' | 'member' | 'department' | 'model' | 'provider'
scope_idstring nullable

Null for the workspace scope; otherwise a key id, a member's user id, a department id, a model id or a provider id.

period'day' | 'week' | 'month' | 'rolling' required

day, week (from Monday) or month in the rule's time zone, or rolling over the last window_hours.

window_hoursinteger nullable

Hours in a rolling window: the spike window for spike rules (at most 56, so that 3 windows fit in the previous 7 days) and the burn-rate lookback for balance rules. Null for calendar periods.

time_zonestring nullable

IANA time zone for calendar periods. Null uses the workspace's billing time zone.

base_kind'amount' | 'workspace_budget' | 'key_limit' | 'previous_period' nullable

What threshold_percents are percentages of: amount (base_amount), workspace_budget or key_limit (the base_ref interval, which must match the period), or previous_period.

base_ref'daily' | 'weekly' | 'monthly' nullable
base_amount_usdnumber nullable
base_amount_nanosinteger nullable
threshold_percentsinteger[] nullable

Up to five whole percentages of the base, sorted. Each fires at most once per period; crossing several at once sends one alert naming the highest.

threshold_amount_usdnumber nullable
threshold_amount_nanosinteger nullable
runway_daysinteger nullable
spike_multipliernumber nullable
spike_floor_usdnumber nullable
spike_floor_nanosinteger nullable
action'notify' | 'block'

notify, or notify and then block once spend reaches block_at_percent of the base or block_at_amount. Blocking is best effort and acts minutes after the threshold. While blocking is switched off for the gateway, a rule that would start blocking is refused with a 400, and a rule that already blocks only notifies.

block_at_percentinteger
block_at_amount_usdnumber nullable
block_at_amount_nanosinteger nullable
block_free_modelsboolean

Whether a block also stops requests to free models.

cooldown_minutesinteger

Minimum minutes between alerts for rolling, spike and balance rules.

destination_idsstring[]

Notification destinations for this rule's alerts. Empty means the workspace's Spend Alerts route.

Response

Spend rule created

Changes