From a5235f3fd76742794094b546a52d797aaf57cf72 Mon Sep 17 00:00:00 2001
From: Krrish Dholakia <krrishdholakia@gmail.com>
Date: Tue, 24 Feb 2026 19:40:17 -0800
Subject: [PATCH] docs: add max_iterations (agent loop limits) documentation

Adds documentation for the new max_iterations feature under
Budgets + Rate Limits in the proxy docs sidebar.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 docs/my-website/docs/proxy/max_iterations.md | 72 ++++++++++++++++++++
 docs/my-website/sidebars.js                  |  1 +
 2 files changed, 73 insertions(+)
 create mode 100644 docs/my-website/docs/proxy/max_iterations.md

diff --git a/docs/my-website/docs/proxy/max_iterations.md b/docs/my-website/docs/proxy/max_iterations.md
new file mode 100644
index 00000000000..a8444891ffe
--- /dev/null
+++ b/docs/my-website/docs/proxy/max_iterations.md
@@ -0,0 +1,72 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Max Iterations (Agent Loop Limits)
+
+Limit the number of LLM calls an agentic loop can make per session. Callers send a `session_id` with each request, and LiteLLM returns `429` when `max_iterations` is exceeded.
+
+## Quick Start
+
+### 1. Set `max_iterations` on a key
+
+```bash
+curl -L -X POST 'http://0.0.0.0:4000/key/generate' \
+-H 'Authorization: Bearer sk-1234' \
+-H 'Content-Type: application/json' \
+-d '{"metadata": {"max_iterations": 25}}'
+```
+
+### 2. Send requests with `session_id`
+
+Include the same `session_id` on every call in the agent loop via the `x-litellm-session-id` header or `metadata.session_id`.
+
+<Tabs>
+<TabItem value="python" label="Python">
+
+```python
+from openai import OpenAI
+
+client = OpenAI(api_key="sk-generated-key", base_url="http://0.0.0.0:4000")
+
+session_id = "agent-run-abc123"
+
+for step in range(50):
+    response = client.chat.completions.create(
+        model="gpt-4o",
+        messages=messages,
+        extra_headers={"x-litellm-session-id": session_id},
+    )
+    # ... process response, execute tools ...
+    # Returns 429 after 25 calls
+```
+
+</TabItem>
+<TabItem value="curl" label="curl">
+
+```bash
+curl -L -X POST 'http://0.0.0.0:4000/v1/chat/completions' \
+-H 'Authorization: Bearer sk-generated-key' \
+-H 'x-litellm-session-id: agent-run-abc123' \
+-H 'Content-Type: application/json' \
+-d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'
+```
+
+</TabItem>
+</Tabs>
+
+Works on all proxy endpoints: `/v1/chat/completions`, `/v1/responses`, `/v1/messages`, `/a2a/{agent_id}`.
+
+## Configuration
+
+Set `max_iterations` in key metadata via `/key/generate` or `/key/update`:
+
+```bash
+# Update existing key
+curl -L -X POST 'http://0.0.0.0:4000/key/update' \
+-H 'Authorization: Bearer sk-1234' \
+-d '{"key": "sk-existing-key", "metadata": {"max_iterations": 50}}'
+```
+
+Session counters auto-expire after 1 hour (configurable via `LITELLM_MAX_ITERATIONS_TTL` env var in seconds).
+
+Works across multiple proxy instances via Redis.
diff --git a/docs/my-website/sidebars.js b/docs/my-website/sidebars.js
index 88d740b5188..e34336a63b6 100644
--- a/docs/my-website/sidebars.js
+++ b/docs/my-website/sidebars.js
@@ -421,6 +421,7 @@ const sidebars = {
             "proxy/customers",
             "proxy/dynamic_rate_limit",
             "proxy/rate_limit_tiers",
+            "proxy/max_iterations",
             "proxy/temporary_budget_increase",
             "proxy/budget_reset_and_tz",
           ],