# Usage limits

Canonical: https://docs.flowrelay.app/operate/usage-limits/
Markdown: https://docs.flowrelay.app/operate/usage-limits.md

Usage limits are FlowRelay plan controls, not traffic-shaping or spike-protection features.

## Current plan meters
FlowRelay tracks capacity for accepted events and governed operational work. The embedded Plan page and Agent Operations plan-usage response expose exact enforced meters so humans and authorized agents can self-throttle before work pauses.


- Meter: Accepted events; What it controls: Inbound events accepted by FlowRelay for processing during the plan period.
- Meter: Diagnostics shares; What it controls: Private, support-safe diagnostics bundles created for support, a partner, or an authorized agent.
- Meter: Replay executions; What it controls: Intentional reruns of retained events. Replay can repeat downstream actions.
- Meter: Simple agent reads; What it controls: Compact setup, grant, plan, billing-handoff, and recent-result reads.
- Meter: Rich agent reads; What it controls: Heavier event, endpoint, diagnostics, reliability, or history reads.
- Meter: Action intents; What it controls: Preview or proposal records for governed actions before anything changes.
- Meter: Executed actions; What it controls: Confirmed governed actions such as replay, diagnostics-share creation, endpoint tests, endpoint changes, or secret rotation.

## Common cases
Use the action being taken, not the screen or actor, to predict which meters move.


- Case: An authorized agent checks whether the store is installed, the grant is valid, usage is healthy, or the latest handoff succeeded.; Meters that move: Simple agent reads; Why: FlowRelay is returning compact status so the agent can decide whether deeper investigation is needed.
- Case: A human or agent opens a failed event, endpoint snapshot, diagnostics preview, or event-history view to understand what happened.; Meters that move: Rich agent reads; Why: FlowRelay is returning detailed operational context, not just a summary.
- Case: An agent prepares a replay, diagnostics share, endpoint test, endpoint change, or secret rotation for human approval.; Meters that move: Action intents; Why: The proposal is recorded and auditable, but nothing has changed yet.
- Case: The merchant approves replaying one retained event.; Meters that move: Replay executions and executed actions; Why: FlowRelay reruns the event, which can repeat downstream actions, and records the governed execution.
- Case: The merchant or authorized agent creates a redacted diagnostics share for support or a partner.; Meters that move: Diagnostics shares and executed actions; Why: FlowRelay creates a private support bundle and records the governed execution.
- Case: The merchant approves an endpoint test, endpoint change, or secret rotation.; Meters that move: Executed actions; Why: FlowRelay performs a governed operation. Replay and diagnostics-share meters move only when that operation also creates a replay or share.

## What usage limits do not control
Usage limits are plan controls. They do not create configurable retry schedules, custom rate limits, endpoint-level throttling, user-managed queue buffering, automatic spike protection, or general webhook traffic management.


## Recovery visibility at limits
Diagnostics shares and replay executions are operator tools, not coverage percentages. Existing event history, receipts, error context, and recovery guidance stay visible when a limit is reached. The operator can upgrade, wait for the next period, or reduce limit-consuming work.


## Operating guidance
Apply the concept through the receipt before changing setup, resending, or replaying.
1. Open Plan or Home in FlowRelay to check accepted event, diagnostics share, replay, agent read, action-intent, and executed-action meters.
2. Treat warning states as a capacity planning signal before production senders hit the limit.
3. If the accepted-event cap is reached, new limit-consuming intake can be blocked while existing receipts, diagnostics, replay history, and recovery guidance remain readable.
4. If governed operation caps are reached, reduce unnecessary agent reads or upgrade before asking an agent to continue high-volume work.
5. Use plan meters for capacity planning. Usage limits do not provide configurable traffic shaping, endpoint throttling, or spike buffering.

## Related
- [Error codes](https://docs.flowrelay.app/recover/error-codes.md)
- [API Reference](https://docs.flowrelay.app/reference/api.md)
- [Grants and scopes](https://docs.flowrelay.app/agent-access/grants-and-scopes.md)

## Safety Boundary
Do not include raw payloads, endpoint secrets, auth headers, HMAC values, Shopify tokens, Shopify sessions, database URLs, customer data, merchant incidents, or copied private logs in public examples.