Create a spend limit
Caps how much money’s worth of work a scope may consume in a period. With no spend limit there is no cap. action: warn adds a warning and a webhook, and action: block also makes check() deny the work with the reason spend_limit_reached. track() never blocks, because the work already happened. An operator sets limits for the account, a plan, an agent, a member, a team or a pool. Your backend sets one for a customer, often because the customer asked for it (set_by: customer), and a customer-set limit can’t exceed the ceiling of the operator limit it replaces. Buying credits never counts toward a limit; only consumption does. In live mode, a limit for the account, a plan, an agent, a member, a team or a pool is configuration: it is refused with 403 and proposal_required and goes in a config proposal. A limit for one customer is data, like a credit grant, so a key with spend_limits:write may create it. An agent key may create a limit and lower one, but not raise or remove one in live.
Authentication
A secret key (rl_sk_test_..., rl_sk_live_...) or a restricted key with limited scopes (rl_rk_test_..., rl_rk_live_...). A restricted key can carry agent: true and an expires_at, and is what a coding agent should hold. Keys end in a checksum so secret scanners can recognize them. People create, roll and revoke keys in the dashboard; GET /v1/api_keys lists them, masked.
Headers
Send true to see what the write would do without doing it. The response is the normal body with dry_run: true, changes (path, before, after), warnings and errors added, and nothing is stored. Validation runs as it would for a real write. The request is kept in request logs, tagged Dry run. When the same change is then made for real, its audit event has dry_run_preceded: true.
Request
The most a customer may set for themselves. A customer-set limit above the ceiling of the limit it replaces is parameter_invalid.
What counts toward the limit. paid_usage: the money value of consumption drawn from paid credits and overage, so included and promotional usage keeps working. all_usage: the money value of everything. Buying credits never counts.
warn adds warnings and a webhook. block also denies in check().
Decimals from 0 to 1. spend_limit.threshold_reached is sent once per period for each.
Every condition you send must match, and a limit with none applies to the whole account. Limits are grouped by which of agent_id, member_id, team_id and pool they name. Inside a group the most specific one applies to a customer: its own customer, then its plan, then the account. Every group that applies must have room, so the strictest group decides.
operator: you set it as policy. customer: your customer chose it, through your product or the customer view.
Response
Every condition you send must match, and a limit with none applies to the whole account. Limits are grouped by which of agent_id, member_id, team_id and pool they name. Inside a group the most specific one applies to a customer: its own customer, then its plan, then the account. Every group that applies must have room, so the strictest group decides.
What counts toward the limit. paid_usage: the money value of consumption drawn from paid credits and overage, so included and promotional usage keeps working. all_usage: the money value of everything. Buying credits never counts.
warn adds warnings and a webhook. block also denies in check().
operator: you set it as policy. customer: your customer chose it, through your product or the customer view.
What has been spent against the limit this period. Read-only.