Per-user rate limits

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:

{
  "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:

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 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 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.

​Configure limits

​Use a stable subject ID

​What counts

​Rate-limit responses

​API-key ceiling

Configure limits

Use a stable subject ID

What counts

Rate-limit responses

API-key ceiling