---
title: "List limit policies"
method: GET
path: "/api/limit-policies/"
tags: ["Limit Policies"]
---

# List limit policies

`GET /api/limit-policies/`

## Request

- Base URL: `https://api.respan.ai`
- URL: `https://api.respan.ai/api/limit-policies/`
- Auth: HTTP bearer

List policies in your organization with their live `current_state`, including policies with no traffic.

## Query parameters

- `page` integer
- `page_size` integer
- `sort_by` string

## Response `200`

Paginated list of policies.

- object
  - `results` LimitPolicy[]
    - `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, nullable: 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: 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: Accumulated value in this window.
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `count` integer: Number of results on this page, not the total. Request pages until `next` is null to get every result.
  - `next` string, nullable
  - `previous` string, nullable

## Other responses

- `403`: The API key is missing, invalid or expired.

## Changes

- **2026-10-21** `c30bcb383ee8`: 12 breaking, 8 info
  - the response property `next` became nullable for the status `200`
  - the response property `previous` became nullable for the status `200`
  - the response property `results/items/anchor_at` became nullable for the status `200`
  - the response property `results/items/current_state/interval_end` became nullable for the status `200`
  - …16 more
- **2026-10-02** `b830b79cfd52`: 1 breaking, 1 warning, 2 info
  - the response property `results/items/rules/items/description` became nullable for the status `200`
  - deleted the `query` request parameter `ordering`
  - added the new optional `query` request parameter `sort_by`
  - added the non-success response with the status `403`
- **2026-09-17** `6fa8242da8c2`: 1 warning, 1 info
  - deleted the `header` request parameter `Authorization`
  - the endpoint scheme security `RespanApiKey` was added to the API
- **2026-09-12** `22b868ef3f22`: 1 info
  - api operation id `list-limit-policies` removed and replaced with `limitPolicies_list_limit_policies`

[Operation history](https://skmtc.dev/respan/apis/respan-api/changes/api/limit-policies/get.md)

---

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