> ## Documentation Index
> Fetch the complete documentation index at: https://docs.herm.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Per-user rate limits

> Configure conversation and user-event limits for each user of an agent.

Each agent limits how many conversations one user can start and how many
`user.*` events they can send. The defaults are:

| Resource      | Default per user |
| ------------- | ---------------- |
| Conversations | 5 per minute     |
| User events   | 100 per minute   |

Both limits use a fixed 60-second window. The window length is not
configurable. Each counter is scoped to the organization, agent, and stable
`subjectId`, so different users and agents have independent allowances.

## Configure limits

Set `rateLimits` when you create an agent:

```json theme={null}
{
  "name": "Support agent",
  "modelName": "openai/gpt-4o-mini",
  "systemPrompt": "Help customers resolve support questions.",
  "skills": [],
  "tools": [],
  "rateLimits": {
    "conversationsPerMinute": 10,
    "messagesPerMinute": 100
  }
}
```

Omit the object or either field to use its default. Conversation limits must be
integers from 1 through 300. User-event limits must be integers from 1 through
1,000.

Update the policy without creating an agent version:

```bash theme={null}
curl -X PATCH "https://api.herm.run/v1/agents/agent_123/rate-limits" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PRISM_API_KEY" \
  -d '{
    "conversationsPerMinute": 10,
    "messagesPerMinute": 200
  }'
```

At least one field is required. Changes apply immediately to all versions and
existing sessions for the agent. The response is the full agent representation,
including its `rateLimits` object.

## Use a stable subject ID

Pass the same `subjectId` whenever the same user creates a session for an
agent. The SDK calls this value `userId`; it maps to `subjectId` in the REST API.
Do not generate a new value per session or request.

Multiple API keys acting for the same organization, agent, and subject share
the same per-user counter. A caller that changes subject IDs can evade this
counter, so only derive subject IDs from authenticated identities you trust.

## What counts

A conversation is counted when `POST /v1/sessions` accepts and durably creates
the session. Later runtime startup failures do not restore that allowance.

A message allowance point is counted for every accepted inbound `user.*` event:

* Every event in a batch counts separately.
* Immediate events count when they are accepted for persistence.
* A `delivery: "when_idle"` prompt counts when it enters the durable queue, not
  again when the queue drains.
* Validation, not-found, archived-session, and prompt-conflict failures rejected
  before persistence do not count. A control event that is persisted but cannot
  reach a live turn does count.
* Steer, approval, clarification, interrupt, custom-tool-result, and other
  control or result events each count like `user.message`.

See [Send Session Events](/api-reference/send-message#rate-limit-counting) for
request details.

## Rate-limit responses

An exceeded operation returns `429 rate_limited` immediately; Herm does not
queue it automatically. The response identifies whether the `conversations` or
`messages` allowance was exceeded and includes the number of seconds until the
fixed window resets.

Successful operations return `RateLimit-Limit`, `RateLimit-Remaining`, and
`RateLimit-Reset`. A `429` also returns `Retry-After` and
`Cache-Control: no-store`.

See [Errors](/errors#rate-limits) for the complete body, headers, and retry
guidance.

## API-key ceiling

Per-user agent limits are separate from the shared API-key rate limit. The
API-key limit is an aggregate organization-key ceiling across users and
endpoints. Per-user limits apply to one stable subject on one agent, including
traffic that reaches Herm without that API key. A request must satisfy both
limits when both apply.