# 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 Agent Operations work. The embedded Plan page and Agent Operations plan-usage response expose exact enforced limits plus paid-plan event grace state 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, redacted diagnostics shares 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 previews; What it controls: Preview or proposal records for approved actions before anything changes. The API key remains actionIntents.
- Meter: Executed actions; What it controls: Confirmed approved actions such as replay, diagnostics-share creation, endpoint tests, endpoint changes, or secret rotation.

## Paid-plan event grace
Starter, Growth, and Scale include a bounded event-intake grace allowance for the current usage period after the included accepted-event cap is reached. Events accepted during grace are still stored, metered, and handed off normally when the rest of the receipt path succeeds. The embedded Plan page and Agent Operations plan-usage response show the exact grace state and remaining allowance when it matters. FlowRelay does not create silent overage charges; more capacity requires an explicit upgrade, approved add-on, or custom-plan approval through Shopify billing or support handoff.


## Published monthly plan limits
These are the plan limits most merchants compare first: event intake, recovery tools, Agent Access posture, and retained event history.


- Plan: Free/Test; Accepted events: 500; Diagnostics shares: 25; Replay executions: 25; Agent Access: Included with published limits; Event history: 30 days
- Plan: Starter; Accepted events: 25,000; Diagnostics shares: 1,000; Replay executions: 500; Agent Access: Included with published limits; Event history: 30 days
- Plan: Growth; Accepted events: 250,000; Diagnostics shares: 10,000; Replay executions: 5,000; Agent Access: Included with published limits; Event history: 30 days
- Plan: Scale; Accepted events: 1,000,000; Diagnostics shares: 50,000; Replay executions: 25,000; Agent Access: Expanded published limits; Event history: 30 days

## Agent Operations limits
Agent Access is included with each plan. Events are normal sender traffic; Agent Operations are controlled operator work, so automated reads, action previews, and executed actions use their own published monthly protective limits.


- Plan: Free/Test; Simple reads: 5,000; Rich reads: 100; Action previews: 200; Executed actions: 100
- Plan: Starter; Simple reads: 250,000; Rich reads: 10,000; Action previews: 4,000; Executed actions: 2,000
- Plan: Growth; Simple reads: 2,500,000; Rich reads: 100,000; Action previews: 40,000; Executed actions: 20,000
- Plan: Scale; Simple reads: 10,000,000; Rich reads: 500,000; Action previews: 200,000; Executed actions: 100,000

## Why Agent Operations limits are lower
Events are normal sender traffic. Agent Operations are operator work: they inspect richer context, create auditable previews, or change something after confirmation. Most stores need many more events than approved recovery interventions, and higher plans include larger Agent Operations allowances for busier recovery work.


## 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 previews; 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 approved 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 approved execution.
- Case: The merchant approves an endpoint test, endpoint change, or secret rotation.; Meters that move: Executed actions; Why: FlowRelay performs an approved 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, diagnostics, replay history, and recovery guidance stay visible when a limit is reached or event intake is in grace. The operator can upgrade, approve an add-on, request a custom plan, 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 from the top navigation or use the Home Plan & usage card in FlowRelay to check accepted event, diagnostics share, replay, agent read, action-preview, and executed-action meters.
2. Treat warning states as a capacity planning signal before production senders hit the limit.
3. If a paid plan reaches its included accepted-event cap, FlowRelay enters a bounded event-intake grace allowance for the current usage period before blocking new intake.
4. Free/Test can block at its included cap, and paid plans block only after event grace is exhausted, abuse or billing failure applies, or the next capacity approval has not happened.
5. If Agent Operations limits are reached, reduce unnecessary agent reads or upgrade before asking an agent to continue high-volume work.
6. Use plan meters for capacity planning. Usage limits do not provide configurable traffic shaping, endpoint throttling, or spike buffering.

## Related
- [Support 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 event bodies, endpoint secrets, authentication headers, HMAC values, Shopify tokens, Shopify sessions, database URLs, customer data, merchant incidents, or copied private logs in public examples.