---
title: "Update a limit policy"
method: PATCH
path: "/api/limit-policies/{id}/"
tags: ["limitPolicies"]
---

# Update a limit policy

`PATCH /api/limit-policies/{id}/`

Update mutable fields (`name`, `scope`, `rules`, `priority`, `is_active`). Immutable fields are ignored.

## Path parameters

- `id` string, uuid, required

## Headers

- `Authorization` string, required

## Request body

- LimitPolicyUpdateRequest — Only `name`, `scope`, `rules`, `priority`, and `is_active` are mutable. Other fields would change the policy identity and are ignored.
  - `name` string
  - `scope` string
  - `rules` LimitPolicyRule[]
    - `trigger` object, required — Threshold condition. Common shape: `{"counter": {"operator": "gte", "value": 10000}}`.
    - `severity` 'soft' | 'hard', required — `soft` fires an alert without blocking; `hard` blocks the request with 429.
    - `description` string — Shown in events and alert payloads.
    - `is_active` boolean
    - `notification_method_id` string, nullable — Optional OrganizationNotificationMethod id to ping when this rule trips.
  - `priority` integer
  - `is_active` boolean

## Response `200`

The updated policy.

- LimitPolicy — A stored cap: watch a scope, measure a metric, refill on a cadence, and fire rules at thresholds.
  - `id` string, uuid
  - `name` string — Human label.
  - `scope` string — Display category (e.g. `API Key`, `Model`). Not used for matching.
  - `scope_value` string — Identity to meter. For composites, a JSON list of values in `compose` order.
  - `compose` string[] — Empty for single-dimension policies. Members: `organization_id`, `api_key_id`, `user_id`, `customer_identifier`, `model`, `endpoint`.
  - `metric` 'cost' | 'request_count' | 'token_count' — What the cap counts. `cost` is US dollars, `token_count` is total tokens, `request_count` is calls.
  - `algorithm` 'balance_fixed_window' — `balance_fixed_window` is the shipped algorithm. `token_bucket` is reserved and not yet enforced.
  - `period` string, nullable — Cadence. A named bucket (`minute`, `hour`, `day`, `week`, `month`), a positive integer of seconds as a string, or `null` for a cumulative (lifetime) cap that never resets.
  - `anchor` 'calendar' | 'first_event' | 'explicit_ts' — When a recurring window aligns. `calendar` resets on the boundary (e.g. the 1st of the month).
  - `anchor_at` string, date-time, nullable — Required when `anchor` is not `calendar`.
  - `effective_at` string, date-time, nullable — Active-range start. `null` = live since forever.
  - `expires_at` string, date-time, nullable — Active-range end. `null` = live until deactivated. Must be after `effective_at`.
  - `priority` integer — Higher is checked first.
  - `is_active` boolean
  - `rules` LimitPolicyRule[] — Any number of soft rules and at most one effective hard rule.
    - `trigger` object, required — Threshold condition. Common shape: `{"counter": {"operator": "gte", "value": 10000}}`.
    - `severity` 'soft' | 'hard', required — `soft` fires an alert without blocking; `hard` blocks the request with 429.
    - `description` string — Shown in events and alert payloads.
    - `is_active` boolean
    - `notification_method_id` string, nullable — Optional OrganizationNotificationMethod id to ping when this rule trips.
  - `threshold_value` number, double — First hard-rule threshold; falls back to the largest soft threshold.
  - `meter_definition_id` string — Stable hash of the policy identity. Same identity resolves to the same id across recreations.
  - `current_state` LimitPolicyCurrentState — Live counter for the current window instance.
    - `meter_id` string
    - `interval_start` integer, nullable — Epoch seconds, inclusive.
    - `interval_end` integer, nullable — Epoch seconds, exclusive.
    - `current_value` number, double — Accumulated value in this window.
  - `created_at` string, date-time
  - `updated_at` string, date-time

---

[API](https://skmtc.dev/respan/apis/api-reference.md) · [All operations](https://skmtc.dev/respan/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/respan/api-reference/revisions/764fca4d43e4/schema)