KEkeywordsai
Limit Policies

Create a limit policy

Changed on

Create a usage cap. The policy takes effect immediately: alert rules notify, and block rules reject gateway requests with 429 once the cap is reached.

post/api/limit-policies/

Request

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

Request body

namestring required
scopestring

Display category. Not used for matching.

scope_valuestring required

Identity to meter. For composites (compose length >= 2), a JSON list of values in compose order.

composestring[]
metric'cost' | 'request_count' | 'token_count' required

What the cap counts. cost is US dollars, token_count is total tokens, request_count is calls.

algorithm'balance_fixed_window'
periodstring nullable

Named bucket, integer-seconds string, or null for cumulative.

anchor'calendar' | 'first_event' | 'explicit_ts'
anchor_atstring date-time nullable
effective_atstring date-time nullable
expires_atstring date-time nullable
priorityinteger
is_activeboolean

Response

The created policy.

idstring uuid
namestring

Human label.

scopestring

Display category (e.g. API Key, Model). Not used for matching.

scope_valuestring

Identity to meter. For composites, a JSON list of values in compose order.

composestring[]

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.

periodstring 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_atstring date-time nullable

Required when anchor is not calendar.

effective_atstring date-time nullable

Active-range start. null = live since forever.

expires_atstring date-time nullable

Active-range end. null = live until deactivated. Must be after effective_at.

priorityinteger

Higher is checked first.

is_activeboolean
threshold_valuenumber

First hard-rule threshold; falls back to the largest soft threshold.

meter_definition_idstring

Stable hash of the policy identity. Same identity resolves to the same id across recreations.

created_atstring date-time
updated_atstring date-time

Changes

  • c30bcb383ee8Revision changes
    • breaking

      request body became required

    • breaking

      the response property became nullable for the status

    • breaking

      the response property / became nullable for the status

    • breaking

      the response property / became nullable for the status

    • breaking

      the response property became nullable for the status

    • breaking

      the response property became nullable for the status

    • breaking

      the response property became nullable for the status

    • breaking

      the response property // became nullable for the status

    • breaking

      the response property // became nullable for the status

    • breaking

      the / response's property format changed from double to no format for status

    • breaking

      the response's property format changed from double to no format for status

    • info

      api operation id limitPolicies_create_limit_policy removed and replaced with create_limit_policy

    • info

      api tag Limit Policies added

    • info

      api tag limitPolicies removed

    • info

      the request property became nullable

    • info

      the request property became nullable

    • info

      the request property became nullable

    • info

      the request property became nullable

    • info

      the request property // became nullable

    • info

      the request property // became nullable

    • info

      the request property default value was added

    • info

      the response optional property became read-only for the status

    • info

      the response optional property became read-only for the status

    • info

      the response optional property became read-only for the status

    • info

      the response optional property became read-only for the status

    • info

      the response optional property became read-only for the status

  • b830b79cfd52Revision changes
    • breaking

      the response property // became nullable for the status

    • info

      the request property // became nullable

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status