Check, and optionally hold
Decides whether a customer can start a piece of work and, with hold: true, reserves what it will cost. Describe the work in one of three ways: an event_name and quantity (priced from the customer’s plan), an outcome_definition (one outcome at the plan’s rate), or a raw amount. A denial is a normal 200 response with allowed: false and a reason. A hold counts against the available balance until track() captures it, you release it, or it expires (default 15 minutes, up to 30 days). Two concurrent checks cannot both reserve the same credits: the second sees the first hold and is denied if the balance can’t cover both.
How far the work fits. Every response carries affordability: the balance, pools, every applicable allowance and spend limits before and after the work, what is short, and would_exceed, which is true only when something would block the work. Without hold: true nothing is reserved, so the figures are a point-in-time read of what would be left if the work ran, not a reservation. With hold: true and allowed: true the hold is placed, and the figures are what is left after it.
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.
Request
Units of event_name, as a decimal string. Defaults to “1”.
The outcome definition (ID or key) the work may produce. Reserves one outcome at the plan’s rate.
A raw amount in the customer’s balance unit, as a decimal string. Credits for prepaid plans; minor units for postpaid plans.
How long the hold lasts, as an ISO 8601 duration. Default PT15M, maximum P30D. This one can be in hours or minutes, but extending the hold later takes whole days only (POST /v1/holds/{hold_id}/extend).
Your ID for the person using your product, inside this customer. Spend limits, per-member allowances and usage summaries can use it. Recorded on the hold, event and ledger entries.
The same flat key-value pairs you will send on track(), so a price rule can read the dimensions your customer chose, such as resolution.
What you expect the work to use, priced from the cost catalog to estimate its cost for margin guardrails. Without it, check() falls back to the observed average cost of recent work of this kind.
Response
What the work costs, as a decimal string in the unit of the check. "0" when the check is denied with no_active_subscription or no_rate_for_event, because there is no plan or rate to price the work from.
How far the work fits, in every response, allowed or denied: the balance, pools, allowances and spend limits before and after the work. It is always present. See Affordability for every field.
Why allowed is false. Present only on denials. allowance_exhausted: a plan allowance with on_exhausted: block has no room in its window. spend_limit_reached: a spend limit with action: block has no room left in its period. margin_below_floor is the denial a margin guardrail with action: block produces. The same guardrail adds the warning margin_below_guardrail when its action is warn, and on track().
The credit type the amounts are in (prepaid plans).
The currency the amounts are in, in minor units (postpaid plans).
The hold, if one was placed. Present only with hold: true and allowed: true.
For example margin_below_guardrail or no_cost_estimate.