Rate Limiting

The rate_limit block in 10xgraph.json activates 10xGraph’s built-in sliding-window rate limiter. The limiter is disabled by default — remove the block or set it to null to turn it off.

Configuration fields

Invalid values are rejected at config load: by outside ip/user/global, backend outside memory/redis/custom, a non-positive requests or window, trusted_proxy_hops below 1, or an entry in trusted_proxies that is not an IP or CIDR range all raise a ValueError and stop the server from starting.

Bucket keys

by decides which bucket a request is counted against.

"user" is what you want once auth is enabled. Limiting purely by IP gives a single user roaming between addresses an effectively unlimited budget, while a NAT’d office sharing one address gets throttled as though it were one caller.

Proxy hops

X-Forwarded-For is a list that each proxy appends to. Whatever the caller sent arrives at the left of the list; only the entries your own proxies appended, on the right, are trustworthy. Reading the leftmost entry would let a caller send a different value on every request, land in a fresh bucket each time, and never be limited at all.

trusted_proxy_hops is how many entries, counted from the right, your own infrastructure appended. With the default of 1 (one proxy in front of the app) the last entry is the address that proxy actually observed. If the header carries fewer entries than the configured hop count, the header is ignored entirely and the peer address is used, with a warning.

trusted_proxy_hops only has an effect when trusted_proxy_headers is true.

The hop count assumes every request comes through your proxy. A client that can reach the app directly would otherwise be free to send its own X-Forwarded-For. Set trusted_proxies to the networks your proxies connect from, and the header is honoured only for requests whose peer address is in one of them; anyone else is keyed by their peer address.

"rate_limit": {
  "trusted_proxy_headers": true,
  "trusted_proxy_hops": 1,
  "trusted_proxies": ["10.0.0.0/8"]
}

WebSocket handshakes

Rate limiting is HTTP middleware, and Starlette runs middleware for HTTP scopes only, so WebSocket handshakes would otherwise bypass it. WS /v1/graph/ws and WS /v1/graph/live therefore re-apply the check at the handshake, using the same backend and the same bucket as REST requests. Opening a socket counts exactly like any other request; exceeding the limit refuses the handshake with WebSocket close code 1013 (Try Again Later) before accept().

The separate websocket.max_connections cap is enforced at the same point and uses the same close code.

Minimal example

{
  "agent": "graph.react:app",
  "rate_limit": {
    "enabled": true,
    "backend": "memory",
    "requests": 100,
    "window": 60,
    "by": "ip",
    "exclude_paths": ["/ping", "/docs", "/redoc", "/openapi.json"]
  }
}

Full Redis example

{
  "agent": "graph.react:app",
  "rate_limit": {
    "enabled": true,
    "backend": "redis",
    "requests": 1000,
    "window": 60,
    "by": "ip",
    "trusted_proxy_headers": true,
    "exclude_paths": ["/ping", "/metrics", "/docs", "/redoc", "/openapi.json"],
    "redis": {
      "url": "${RATE_LIMIT_REDIS_URL}",
      "prefix": "agentflow:rate-limit"
    },
    "fail_open": true
  }
}

# .env
RATE_LIMIT_REDIS_URL=redis://localhost:6379/0

Install the Redis extra before using "backend": "redis":

pip install "10xscale-agentflow-cli[redis]"

Backend comparison

Response headers

Every response includes rate-limit headers:

429 response body

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Limit: 100 per 60s. Retry after 12s.",
    "limit": 100,
    "window_seconds": 60,
    "retry_after_seconds": 12
  },
  "metadata": {
    "request_id": "request-id",
    "status": "error"
  }
}

Custom backend interface

from agentflow_cli.src.app.core.middleware.rate_limit import (
    BaseRateLimitBackend,
    RateLimitDecision,
)

class MyRateLimitBackend(BaseRateLimitBackend):
    async def check(self, key: str, *, limit: int, window: int) -> RateLimitDecision:
        allowed = True
        remaining = limit - 1
        reset_after = window
        return RateLimitDecision(
            allowed=allowed,
            remaining=remaining,
            reset_after=reset_after,
        )

    async def close(self) -> None:
        return None

Set "backend": "custom" in 10xgraph.json and bind the instance through InjectQ.

See also

• Configure Rate Limiting — step-by-step setup guide
• 10xgraph.json configuration
• Environment variables