Run a simulation
Replays recorded events and costs from a past range against a candidate: a configuration document with cost models, rate cards, price rules or guardrails, and cost adjustments such as “this model costs 20% more”. It returns the margin the range would have had, next to the margin it had. Nothing is written to customer balances, invoices or live configuration. Costs priced from the catalog are priced again from their usage lines, and costs you reported yourself with cost are kept as reported. Outcome charges and their reversals stay as recorded, so the margin still counts reversals. A simulation covers at most 31 days. It may return as pending; fetch it, or wait for simulation.completed. Needs config:read and events:read, and works with sandbox and live keys.
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
End of the range, exclusive. At most 31 days after from.
Only this customer (cus_...).
Only customers on this plan (ID or key).
Response
Present when status is completed.
Present when status is failed.
Who made a change. Runledger fills it in from the credential, so a client can’t claim to be someone else: an API key always acts as itself, the dashboard calls the API as the signed-in person, and the MCP server passes the client’s name and the person it acts for. A request that sends a Runledger-Actor header is refused with 400 parameter_unknown.