Skip to navigation
API ReferenceThe four calls

Track an event

Records one thing that happened. Your configuration decides what it does. An event named in a plan rate is usage and is charged at once. An event matching an outcome definition’s event_name creates a pending outcome charge. An event named in a reversal rule is a signal about an earlier outcome charge with the same reference. Any other event is stored unpriced, with a warning. Pass hold to capture from a hold placed by check(); the rest of the hold is released unless release_remainder is false. Tracking never fails for lack of balance, because the work already happened: a shortfall shows as an overdrawn balance and later checks are denied. Events are deduplicated on idempotency_key for 35 days.

Authentication

AuthorizationBearer

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

This endpoint expects an object.
idempotency_keystringRequired<=255 characters
Your unique ID for this event. A repeat within 35 days returns the original event.
namestringRequired<=128 characters

The event name. Your plans, outcome definitions and reversal rules decide what it does. Once recorded, an event’s name never changes: to fix a mistake, send a correcting event.

customer_idstringOptional
external_customer_idstringOptional
timestampdatetimeOptional
When it happened. Defaults to now. Up to 35 days in the past and 5 minutes in the future. An event dated in a period whose invoice is already finalized is billed on the next invoice.
quantitystringOptional
Units, as a decimal string. Defaults to "1".
referencestringOptional<=255 characters

Your ID for the thing the event is about, such as a conversation or ticket. Signals find their outcome charge by customer and reference.

holdstringOptional

Capture this event’s price from this hold (hold_...).

release_remainderbooleanOptionalDefaults to true
Release what's left of the hold after capture. Set false to capture again from the same hold.
agent_idstringOptional
run_idstringOptional
member_idstringOptional<=128 characters

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.

team_idstringOptional<=128 characters
Your ID for a team inside this customer. A label for limits and reporting. Runledger doesn't model teams.
propertiesmap from strings to anyOptional

Up to 50 flat key-value pairs. Reversal rule conditions read these. Price rules read them too, as the dimension values and quantities that set the price.

evidenceobjectOptional

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.

Response

The recorded event and what it did. A duplicate returns the original event.
idstring
object"event"
idempotency_keystring
namestring
The event name as recorded. It never changes after the event is recorded.
kindenum

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.

Allowed values:
customerstring
timestampdatetime
quantitystring
effectsobject
The IDs of everything the event created or changed.
warningslist of objects
livemodeboolean
created_atdatetime
referencestringOptional
agent_idstringOptional
member_idstringOptional
team_idstringOptional
run_idstringOptional
propertiesmap from strings to anyOptional
evidenceobjectOptional

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.

pricingobjectOptional
How a price rule priced a usage event. Left out for other events.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error