Summarize runs
Total revenue, cost and margin across all the runs that match the filters, not just a page of them. The filters are the ones on GET /v1/runs: customer_id, outcome_definition, from, to and has_margin.
Split for a chart. Send group_by to also get rows, with the same totals broken down. day and week give one row per bucket, oldest first, by the time a run was first seen (UTC; a week starts on Monday). Every bucket from the first to the last one that has a run is returned, an empty one with zeros, so a chart has no gaps. customer gives one row per customer, the highest revenue_confirmed first, up to limit. The totals at the top level always cover every matching run, not just the rows returned. Each row has revenue_confirmed, cost, margin, margin_percent and has_margin, counted as for the totals. A row with no run that has a margin has has_margin: false and a null margin and margin_percent, so a chart can leave it out instead of plotting zero. The filters and the one-currency rule are the same with or without group_by.
Runs without a margin. The money totals add up only the runs that have a margin, which needs a confirmed charge and a traced cost, so margin is always revenue_confirmed minus cost. A run with no confirmed charge (nothing, or only pending or reversed charges) or with no traced cost adds nothing to revenue_confirmed, cost or margin, whichever of the two it is missing. It is counted in runs and in runs_without_margin, so you can see how many were left out. With has_margin=false every matching run is without a margin, so the totals are "0".
One currency per summary: totals are never converted or added across currencies. Send currency, or omit it when every matching run is in one currency. If the matching runs are in more than one, the call returns 400 with parameter_invalid on currency.
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.
Query parameters
Only runs that produced a charge for this outcome definition (ID or key).
As on GET /v1/runs: only runs that have a margin (true), or only runs that don’t (false). Omit it for both.
Summarize runs in this currency (lowercase ISO 4217). Needed when the matching runs are in more than one.
Also return rows: one per day, one per week, or one per customer. Leave it out for the totals alone.
group_by=customer only: the most customer rows to return, from 1 to 500. Default 50.
Response
The totals, and the rows when group_by is sent.
How many runs match the filters. runs_with_margin plus runs_without_margin.
Decimal minor units. The confirmed revenue of the runs with a margin. "0" when there are none.
Decimal minor units. The cost of the runs with a margin. The cost of a run without a margin is not included. "0" when there are none.
Decimal minor units. revenue_confirmed minus cost. "0" when no run has a margin.
margin as a share of revenue_confirmed. null when no run has a margin.
Present when the request sent group_by.
Present when the request sent group_by. The same totals, split by bucket or by customer.
group_by=customer only: true when more customers matched than limit returned.