Get Rate Limit Policy by ID

GET /environments/{env_id}/rate_limits/{rate_limit_id}

Get Rate Limit Policy by ID

Return one rate-limit policy. The policy must belong to the environment in the request path.

Parameters

• env_id (path, string, required): Environment ID that scopes the request.
• rate_limit_id (path, string, required): Rate limit policy ID within the environment.

Responses

• 200: OK
• rate_limit_policy (object, required): A rate limit rule the gateway enforces per request. Requests over the limit are rejected with HTTP 429 at the gateway.

A policy is exactly one of two forms, fixed at creation. The classic form targets one subject via scope + scope_ref with window + max_requests / max_tokens. The conditional form matches requests with a conditions tree, splits counters by group_by, and caps with the 7-field limits; its classic fields read as null. The conditional fields are only present on conditional-form policies.

• rate_limit_policy.id (string, required): Rate limit policy ID.

• rate_limit_policy.env_id (string, required): Environment ID that owns this policy.

• rate_limit_policy.name (string, required): Human-readable policy name.

• rate_limit_policy.scope (object, required):

• allOf variant 1

• rate_limit_policy.scope_ref (string, required): ID of the resource the policy applies to, matching scope: a caller API key ID, model ID, team ID, or member ID. team_member policies reference a team ID. Fixed at creation. null on conditional-form policies.

• rate_limit_policy.window (object, required):

• allOf variant 1

• rate_limit_policy.max_requests (integer, required): Maximum number of requests allowed per window. null when the policy has no request cap.

• rate_limit_policy.max_tokens (integer, required): Maximum total tokens consumed per window. null when the policy has no token cap.

• rate_limit_policy.schedules (array, required): Recurring suspension windows: while the current time falls in any listed window the gateway skips this policy, and enforcement resumes automatically afterwards. Empty when the policy is always enforced. Present on both policy forms.

• rate_limit_policy.schedules[].timezone (string, required): IANA timezone the wall-clock fields are interpreted in (e.g. Asia/Shanghai).

• rate_limit_policy.schedules[].days_of_week (array, optional): Weekly selector: the window opens on each listed day. Mutually exclusive with dates.

• rate_limit_policy.schedules[].dates (array, optional): Explicit calendar dates (YYYY-MM-DD, in timezone) the window opens on — for holidays and other irregular days. Mutually exclusive with days_of_week.

• rate_limit_policy.schedules[].start_time (string, required): Window start, HH:MM wall clock (inclusive).

• rate_limit_policy.schedules[].end_time (string, required): Window end, HH:MM wall clock (exclusive); 24:00 means end of day. Must differ from start_time; an end before the start crosses into the following day.

• oneOf variant 1

• oneOf variant 2

• rate_limit_policy.conditions (array, optional): Condition node tree the request must satisfy (top-level nodes combine as AND; an empty list matches every request in the environment). Conditional form only.

• rate_limit_policy.conditions[].dimension (string, optional): Request dimension a condition leaf matches on. Identity dimensions carry resource UUIDs (team, member, api_key, model) and admit the equality/set operators; the string dimensions model_name (model display name) and provider additionally admit the regex operators.

model and model_name match the dispatched model and — when the caller addressed a routing group, semantic router, or ensemble — the addressed parent as well. Either identity satisfies a positive operator (==/in/regex): a group's own id selects every request routed through it, and a member's id selects that member whether called directly or through a group. ~= is true only when BOTH identities differ (preserving a ~= b = !(a == b)), and negate inverts the combined leaf result — so a negated in excludes a request when either identity is listed, and negate + ~= matches when either identity equals the value.

• rate_limit_policy.conditions[].operator (string, optional): Condition operator, mirroring lua-resty-expr tokens. ==/~= compare equal/not-equal, in tests list membership, ~~/~* are case-sensitive/insensitive regexes (string dimensions only). has, the numeric comparisons and ipmatch are reserved for future dimensions and rejected on every current one.

• rate_limit_policy.conditions[].negate (boolean, optional): Invert the leaf (lua-resty-expr !, e.g. negate + in = "not in") or the group (!AND / !OR). A request missing the leaf's dimension matches neither the condition nor its negation.

• rate_limit_policy.conditions[].value (object, optional): Comparison value: in takes 1–64 strings, every other operator a single string. Identity dimensions take resource UUIDs; model_name takes display-name strings or (for ~~/~*) a regex of at most 256 characters; provider takes provider catalog ids.

• oneOf variant 1

• oneOf variant 2

• rate_limit_policy.conditions[].logic (string, optional): Group combinator — lua-resty-expr AND / OR.

• rate_limit_policy.conditions[].children (array, optional): Nested condition nodes (group shape only).

• rate_limit_policy.group_by (array, optional): Dimensions the counters split on; empty = one shared bucket for every matched request. Conditional form only.

• rate_limit_policy.limits (object, optional): Conditional-form limits — the same 7-field shape as the inline model / API-key rate limits. At least one field must be set.

• rate_limit_policy.limits.rps (integer, optional): Requests per second.

• rate_limit_policy.limits.rpm (integer, optional): Requests per minute.

• rate_limit_policy.limits.rph (integer, optional): Requests per hour.

• rate_limit_policy.limits.rpd (integer, optional): Requests per day.

• rate_limit_policy.limits.tpm (integer, optional): Total tokens per minute.

• rate_limit_policy.limits.tpd (integer, optional): Total tokens per day.

• rate_limit_policy.limits.concurrency (integer, optional): Maximum concurrent in-flight requests. Capped at the data plane's 32-bit counter range.

• rate_limit_policy.action (string, optional): What the policy does past its limits. Only reject (HTTP 429) is available; the field reserves the enum for future actions.

• rate_limit_policy.created_at (string, required): Time when the policy was created.

• rate_limit_policy.updated_at (string, required): Time when the policy was last updated.

• warnings (array, optional): Present on save operations when some data plane nodes in the environment run a gateway version that will not execute part of the saved policy. Never present on reads.

• warnings[].code (string, required): How affected nodes treat the saved resource. field_ignored: the resource stays in service on those nodes but the named field has no effect there — beware when the field is restrictive, since the restriction is silently not enforced. row_rejected: those nodes refuse the whole resource, so it stops serving there entirely (or, if a previously accepted version exists, they keep serving the old values).

• warnings[].field (string, required): Dot-separated path of the field that triggered the warning, as delivered to gateway nodes.

• warnings[].min_dp_version (string, required): Oldest gateway version that fully executes the field. The literal value unreleased means no released gateway version executes it yet.

• warnings[].affected_dp_count (integer, required): Number of currently registered nodes in the environment running an older gateway version than min_dp_version.

• warnings[].affected_dp_versions (array, required): Distinct gateway versions reported by the affected nodes, capped at five entries. Nodes that report no version appear as unknown.

• 400: Request body or parameters failed validation.

• error (object, required): Error details.

• error.code (string, required): Machine-readable identifier. Examples: UNAUTHENTICATED, INVALID_REQUEST, MASTER_KEY_UNSET, INTERNAL.

• error.message (string, required): Human-readable explanation; safe to surface to operators.

• 401: Missing or invalid bearer. Response fields (application/json): identical to GET /environments/{env_id}/rate_limits/{rate_limit_id}, response 400 above.

• 404: Resource not found. Response fields (application/json): identical to GET /environments/{env_id}/rate_limits/{rate_limit_id}, response 400 above.

cURL

curl -X GET '$AISIX_CP/environments/{env_id}/rate_limits/{rate_limit_id}' -H 'Authorization: Bearer $AISIX_TOKEN'