Preview an event
Shows what track() would do with this event, without recording it: the price, the outcome charge and its clocks, the ledger entries, and any rules that would fire. Nothing is written. Use it to test configuration, and from coding agents before they wire up track().
Price with a rule. For a usage event, pricing shows how a price rule priced it, line by line. By default that is the rule the customer’s plan rate uses. Send price_rule, and optionally price_rule_version, to price the event with that rule and version instead, even when no plan rate uses it yet. That tests a rule before a plan points at it. The rule’s currency must match the customer’s plan.
An upfront estimate. price is what the event would cost, in the customer’s balance unit, so a workflow can show “this will use about X credits” before it runs. It is an estimate: track() prices the event it receives.
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
What shows an outcome happened, stamped on the outcome charge. Keep it short and factual; it is shown to people deciding disputes. Free text is sanitized before it reaches dashboards or agent tools.
The key of the price rule to price the event with, such as video_cost_plus. With it, pricing is returned even when no plan rate uses the rule. Without it, the event is priced by the rule its plan rate uses, if any. The rule’s currency must match the customer’s plan. An unknown key returns 404.
The version of price_rule to price with. Without it, the version in force at the event’s timestamp. Needs price_rule.
Response
What the event turned out to be. usage: charged at once. outcome: created a pending outcome charge. signal: evaluated against reversal rules. unpriced: stored with no effect.
Whether track() would accept the event.
What the event would cost, as a decimal string in the customer’s balance unit (a credit type or a currency). Use it as an upfront “about X credits” estimate before the work runs.
How a price rule would price the event, line by line. Present when the event is priced by a rule: the rule its plan rate uses, or the one named by price_rule in the request, whether or not a plan rate uses it.
Why track() would reject the event.