List Rate Limit Rules
List the rate-limit rules the calling user has defined on their endpoints. Each rule caps the request rate against a single endpoint over a sliding window, gated by an optional list of conditions (post-#172, the same vocabulary as firewall policies). Distinct from traffic-policy rate limits: those attach inside a traffic policy and run inline with the request chain.
Query parameters
endpoint_uuid string (uuid)
Filter to one endpoint (its
uuid from /endpoints).status string
active, inactive, or disabled.page, limit int
Standard pagination.
page defaults to 1; limit (alias page_size) defaults to 15 and is capped at 200.search string
Substring match against rule name (alias
q).Deprecated: endpoint_id (the old name; an endpoint uuid, or an integer) is still accepted until the sunset. Send endpoint_uuid.
Response (200 OK)
rules object[]
The rules on this page (fields below). Always a list;
[] when there are none.pagination object
{page, limit, total, totalPages}: the page returned, the effective page size, the number of matching rules across all pages, and the number of pages.endpoints object[]
Every endpoint in your account, for picking a rule's endpoint:
{uuid, user_uuid, subdomain, is_custom, status, domain_uuid, domain_name, created_at, updated_at}. user_uuid is null for an endpoint no user created (e.g. agent-created); domain_uuid / domain_name are omitted when the endpoint has no domain row. [] when there are none.endpointByUUID object
The same endpoint objects keyed by endpoint uuid.
domainByUUID object
Domain name keyed by domain uuid, for the domains those endpoints use.
defaultDomain string
The platform's default endpoint domain.
posture object?
Rate-limit activity in your account over the last 24 hours:
blocked (int, requests a rate-limit rule blocked or throttled), top_source (string, the client IP limited most often; empty when none) and top_source_n (int, how often it was limited). Omitted when the summary can't be computed.Rule object
uuid string (uuid)
Rule uuid. Used in /firewall/rate-limits/{uuid}.
endpoint_uuid string (uuid)
The endpoint this rule applies to. Rate-limit rules are always per-endpoint.
user_uuid, account_uuid string (uuid)?
The user who created the rule and the owning account. Omitted when unset (e.g. the creator was deleted).
name string
Free-form label.
description string?
Free-form description. Omitted when unset.
conditions array?
Match conditions (post-#172) joined by AND/OR. Each:
{uuid, rule_uuid, condition_type, operator, condition_value, logical_operator, created_at}. Same vocabulary as firewall policies (source_ip, country, asn, browser, user_agent, endpoint, path, method, header, cookie, protocol, port). A rule with zero conditions matches every request to its endpoint; the field is then omitted.source_ip string? Deprecated
Legacy pre-#172 single-IP filter, kept for read-back compat. New rules express IP filters as a
source_ip condition instead. Omitted when unset; empty or * meant "all client IPs".requests_per_window int
Max requests allowed before the action triggers.
window_size_seconds int
Sliding window length in seconds.
action string
What to do once the limit is hit:
block (return 429) or throttle (delay subsequent requests).status string
active, inactive, or disabled. Only active rules are evaluated by the tunnel-server.priority int
Lower numbers evaluated first.
hit_count int
Requests this rule matched over the last 7 days (best-effort;
0 when none or when the stats can't be read).last_matched, hits_daily datetime? / int[]?
The most recent match in that window and a per-day match series (index 0 = oldest day). Both omitted when the rule hasn't matched in the window.
shadowed, shadow_reason boolean? / string?
Present only when an earlier rule on the same endpoint already covers this rule's match scope (
shadowed: true plus a human-readable reason).quota_paused_at datetime?
Set while the rule is paused because the account has more rate-limit rules than its plan allows: it is kept but not enforced, and resumes on its own once the account has room. Omitted otherwise.
created_at, updated_at datetime
RFC 3339 UTC.
Deprecated: until the sunset this response also carries the legacy integer id and *_id fields (on rules, conditions and the endpoints entries). Don't use them; read uuid, the *_uuid fields and the …ByUUID maps.
Errors
401 Unauthorized
Missing auth.
Request
curl "https://api.ngris.com/v1/firewall/rate-limits?endpoint_uuid=019bb1e4-e785-77d2-9966-c3cff31d0a0e&status=active" \
-H "X-API-KEY: <your_api_key>"
Python
from ngris import Ngris
client = Ngris(api_key="<your_api_key>")
page = client._get_raw(
"/firewall/rate-limits",
params={"endpoint_uuid": "019bb1e4-e785-77d2-9966-c3cff31d0a0e"},
)
for rl in page["rules"]:
src = rl.get("source_ip") or "any"
print(f"{rl['name']}: {rl['requests_per_window']}/{rl['window_size_seconds']}s from {src} → {rl['action']}")
Response — 200 OK
{
"rules": [
{
"uuid": "019b344f-6477-7b07-8dac-7d370474eab1",
"endpoint_uuid": "019bb1e4-e785-77d2-9966-c3cff31d0a0e",
"user_uuid": "019a52c2-ca1e-78ba-ab5c-50362cc29134",
"account_uuid": "019a68b9-1a79-7820-a884-41f554aba6bd",
"name": "anti-abuse",
"description": "Cap each client to 1000 req/min",
"requests_per_window": 1000,
"window_size_seconds": 60,
"action": "block",
"status": "active",
"priority": 100,
"hit_count": 12,
"last_matched": "2026-04-29T12:58:10Z",
"hits_daily": [0, 2, 1, 0, 4, 3, 2],
"created_at": "2026-04-01T00:00:00Z",
"updated_at": "2026-04-01T00:00:00Z"
}
],
"pagination": {"page": 1, "limit": 15, "total": 1, "totalPages": 1},
"endpoints": [
{"uuid": "019bb1e4-e785-77d2-9966-c3cff31d0a0e", "user_uuid": "019a52c2-ca1e-78ba-ab5c-50362cc29134", "subdomain": "api",
"is_custom": false, "status": "active", "domain_uuid": "019bd08f-98db-71b2-8e54-f518d319f111",
"domain_name": "ngris.dev", "created_at": "2026-03-30T09:00:00Z", "updated_at": "2026-03-30T09:00:00Z"}
],
"endpointByUUID": {
"019bb1e4-e785-77d2-9966-c3cff31d0a0e": {"uuid": "019bb1e4-e785-77d2-9966-c3cff31d0a0e", "user_uuid": "019a52c2-ca1e-78ba-ab5c-50362cc29134", "subdomain": "api",
"is_custom": false, "status": "active", "domain_uuid": "019bd08f-98db-71b2-8e54-f518d319f111",
"domain_name": "ngris.dev", "created_at": "2026-03-30T09:00:00Z", "updated_at": "2026-03-30T09:00:00Z"}
},
"domainByUUID": {"019bd08f-98db-71b2-8e54-f518d319f111": "ngris.dev"},
"defaultDomain": "ngris.dev",
"posture": {"blocked": 12, "top_source": "203.0.113.77", "top_source_n": 7}
}
Was this helpful?