What the agent does
The agent reads how the API authenticates before it decides what to limit. In a Flask app like miguelgrinberg/microblog, requirements.txt pins Flask 3.0.0, Flask-HTTPAuth 4.8.0, Flask-SQLAlchemy 3.1.1 and redis 5.0.1, with no Flask-Limiter line. app/__init__.py builds the app in create_app, registers the api blueprint at /api, and creates app.redis with Redis.from_url(app.config['REDIS_URL']), where config.py defaults REDIS_URL to redis://. app/api/tokens.py issues a bearer token on POST /tokens behind basic_auth, which checks a username and password on every call, and app/api/users.py creates an account on POST /users with no authentication at all. Those two routes are where a script can guess passwords or register accounts in bulk, so they get the tightest limits.
The agent adds Flask-Limiter to requirements.txt, creates a Limiter in app/__init__.py next to db and login with get_remote_address as the key function and RATELIMIT_STORAGE_URI read from config.py as the existing REDIS_URL, and calls limiter.init_app(app) in create_app. The storage has to be Redis because deployment/supervisor/microblog.conf runs gunicorn with -w 4 and boot.sh runs it in Docker, so an in-memory counter would be per worker. Since that gunicorn sits behind the nginx config in deployment/nginx, the agent wraps app.wsgi_app in Werkzeug's ProxyFix with x_for=1 so the limit keys on the client address in X-Forwarded-For rather than on nginx.
Limits go on the routes, not on the blueprint as a whole: 5 per minute on POST /api/tokens, 3 per hour on POST /api/users, and a shared 100 per minute on the token-authenticated routes in app/api/users.py, keyed on the bearer token when one is present and on the address otherwise. When a limit is hit, Flask-Limiter raises an HTTPException with status 429, and the blueprint's handle_exception in app/api/errors.py already turns any HTTPException into the {'error': 'Too Many Requests'} JSON that the rest of the API uses, so no new error handler is needed. The agent sets RATELIMIT_HEADERS_ENABLED so each answer carries X-RateLimit-Limit, X-RateLimit-Remaining and Retry-After.
Tests follow tests.py, whose TestConfig already points SQLAlchemy at sqlite:// and turns Elasticsearch off. The agent adds RATELIMIT_STORAGE_URI = 'memory://' to that config so the suite needs no Redis, then writes an ApiRateLimitCase with self.app.test_client() that posts wrong credentials to /api/tokens six times and expects five 401 answers and then a 429 with the JSON error and a Retry-After header, and posts four sign-ups to /api/users and expects the fourth to be refused. It runs python -m unittest tests.py and flask run with a local Redis, sends real requests with curl -i, and keeps the headers.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add rate limiting to this Flask API and open a pull request. Read requirements.txt, config.py, app/__init__.py, app/api/__init__.py, app/api/auth.py, app/api/tokens.py, app/api/users.py, app/api/errors.py, tests.py, boot.sh, deployment/supervisor/microblog.conf and the nginx config under deployment/ first. Add Flask-Limiter to requirements.txt. Create a Limiter in app/__init__.py with get_remote_address as the key function, storage read from a RATELIMIT_STORAGE_URI config value that defaults to the existing REDIS_URL, and init it in create_app. Wrap the WSGI app in werkzeug's ProxyFix with x_for=1 because gunicorn runs behind nginx. Limit POST /api/tokens to 5 per minute per address, POST /api/users to 3 per hour per address, and the token-authenticated routes in app/api/users.py to 100 per minute keyed on the bearer token when present. Enable rate limit headers. Confirm the existing HTTPException handler in app/api/errors.py returns the JSON error shape for 429 and do not add a second handler. In tests.py set RATELIMIT_STORAGE_URI to memory:// in TestConfig and add an ApiRateLimitCase that proves the 401-then-429 sequence on /api/tokens and the refusal on the fourth /api/users sign-up, asserting the Retry-After header. Run python -m unittest tests.py, start the app with a local Redis, send requests with curl -i and paste the output in the pull request. Document the two new config values in README.md. Do not change the web routes under app/main or app/auth.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request with Flask-Limiter in requirements.txt, a Limiter created and initialised in app/__init__.py, RATELIMIT_STORAGE_URI and RATELIMIT_HEADERS_ENABLED in config.py, the ProxyFix wrapper, @limiter.limit decorators on the routes in app/api/tokens.py and app/api/users.py, and a new test case in tests.py. The description pastes the unittest run and a curl -i session showing the X-RateLimit-Remaining header counting down and the 429 answer with its Retry-After value.
The web routes under app/main and app/auth are untouched: a browser session that posts a form is not counted, and a logged-in user keeps the same pages. A reviewer checks that the storage is Redis in production and memory only in TestConfig, that ProxyFix trusts exactly one proxy hop, that the limit on /api/tokens applies before basic_auth runs so a guessing script is stopped without a database lookup, and that the token-keyed limit falls back to the address for a request with no token.
The repository has no CI workflow, so the pasted test output and the curl session are the proof a reviewer reads before merging. Then they set RATELIMIT_STORAGE_URI in each environment where REDIS_URL does not point at the Redis they want the counters in.
Run it on every new service added to the fleet
A team with several Flask APIs starts one run per repository with POST /o/{org}/sessions, this prompt and the repository in resources. The agent reads each app's own auth module, so an API that uses sessions instead of tokens gets limits keyed on the address only, and each run opens its own pull request. A key starts at most max_concurrent runs at once, four by default, so a loop over ten repositories sends all ten requests: four start, the other six answer 202 with status: "queued", and each begins, oldest first, when a slot frees.
The key's webhook_url receives run.completed for each run it starts, with data.session_url for the pull request, so a script can post the links to a channel as they land.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Rate limits are easy to add wrong: a memory store that resets per worker, a key function that counts the proxy instead of the client, or a limit on a route that never saw the attack. In a Rush sandbox the agent reads the gunicorn and nginx configuration the app ships, starts Redis, runs the API and sends the requests that hit the limit, and the headers and the 429 body stay in the transcript next to the test output.
The result is a pull request a reviewer can replay: the exact curl lines, the exact config values, and a test that runs without Redis. The same request works across every Flask service the team owns, each run in its own sandbox.
Frequently asked questions
Why Redis and not the default memory storage?
deployment/supervisor/microblog.conf runs gunicorn with four workers, and each worker would keep its own counter, so a client could make four times the limit. Redis is already a dependency and config.py already has REDIS_URL, so the limiter shares the counters across workers and across containers.
Why is ProxyFix part of a rate limiting change?
Behind the nginx config in deployment/nginx, Flask sees nginx's address on every request, so every client would share one bucket. ProxyFix with x_for=1 reads one X-Forwarded-For hop, and the limit keys on the real client. Set it to the number of proxies in front of the app.
Will the tests need a Redis server?
No. TestConfig in tests.py sets RATELIMIT_STORAGE_URI to memory://, the same way it already sets SQLALCHEMY_DATABASE_URI to an in-memory SQLite. The new test case runs with python -m unittest tests.py and nothing else.
Does a rate limited answer look like the other API errors?
Yes. app/api/errors.py registers handle_exception for every HTTPException on the blueprint and answers with {'error': <status text>}. A 429 goes through the same handler, so clients parse it as they parse a 401 or 404, and the Retry-After header says when to try again.