---
title: "List spend rules"
method: GET
path: "/spend-rules"
tags: ["Gateway"]
---

# List spend rules

`GET /spend-rules`

## Request

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

Lists the workspace's spend rules. A rule notifies at thresholds in dollars or percent over a scope and a calendar or rolling period. Every workspace member can read them.

## Response `200`

Spend rules

- SpendRuleListResponse
  - `data` SpendRule[], required
    - `id` string, uuid, required
    - `workspace_id` string, uuid, required
    - `name` string, required
    - `enabled` boolean, required
    - `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.
    - `evaluated` boolean, required: Whether the evaluator handles the rule's metric, period and base. Every rule the API accepts is evaluated.
    - `scope_type` 'workspace' | 'key' | 'member' | 'department' | 'model' | 'provider', required
    - `scope_id` string, nullable, required: 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_hours` integer, nullable, required: 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_zone` string, nullable, required: IANA time zone for calendar periods. Null uses the workspace's billing time zone.
    - `base_kind` 'amount' | 'workspace_budget' | 'key_limit' | 'previous_period', nullable, required: 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, required
    - `base_amount_nanos` integer, nullable, required
    - `base_amount_usd` number, nullable, required
    - `threshold_percents` integer[], nullable, required: 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_nanos` integer, nullable, required
    - `threshold_amount_usd` number, nullable, required
    - `runway_days` integer, nullable, required
    - `spike_multiplier` number, nullable, required
    - `spike_floor_nanos` integer, nullable, required
    - `spike_floor_usd` number, nullable, required
    - `action` 'notify' | 'block', required: 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_percent` integer, required
    - `block_at_amount_nanos` integer, nullable, required
    - `block_at_amount_usd` number, nullable, required
    - `block_free_models` boolean, required: Whether a block also stops requests to free models.
    - `cooldown_minutes` integer, required: Minimum minutes between alerts for rolling, spike and balance rules.
    - `destination_ids` string[], required: Notification destinations for this rule's alerts. Empty means the workspace's Spend Alerts route.
    - `created_by` string, uuid, nullable, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `max_rules` integer, required

## Other responses

- `default`: Request failed

## Changes

- **2026-10-27** `58847d40a023`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/phaseo/apis/phaseo-gateway-api/changes/spend-rules/get.md)

---

[API](https://skmtc.dev/phaseo/apis/phaseo-gateway-api.md) - [All operations](https://skmtc.dev/phaseo/apis/phaseo-gateway-api/llms.txt) - [OpenAPI document](https://skmtc.dev/phaseo/apis/phaseo-gateway-api/revisions/5ca9bb220d25?raw)