Credit Usage Events (Admin)
Returns the raw usage_events rows for a single account over the selected period, sorted by created_at descending. Powers the drilldown view that expands when a row in the /api/admins/credits/rollup table is opened. Each event represents one debit (main agent turn, subagent step, chat completion, or research call), with token counts and credits_deducted_cents matching the wallet drop on credits_usage for that account.
The response also carries a grants array covering the same account and period: the admin credit grants made through POST /api/admins/credits. The two arrays answer different questions — events is what the system spent, grants is what a person set by hand, and only a grant carries an actor and a reason. Requires the authenticated account to be a Recoup admin.
Authorizations
Your Recoup API key. Learn more.
Query Parameters
UUID of the account whose usage_events rows to return.
Window to filter created_at against. Same semantics as the rollup endpoint. Defaults to monthly.
all, daily, weekly, monthly Page size — number of events to return per request, sorted by created_at descending. Defaults to 100; max 500.
1 <= x <= 5001-indexed page number. Server returns rows (page - 1) * limit through page * limit - 1. Defaults to 1. Use total_count in the response to drive a 'load more' control on the drilldown (page * limit < total_count).
x >= 1Response
Usage events retrieved successfully
Status of the request
success, error UUID of the account whose events were returned (echoes the request)
The period the response was filtered to (echoes the request)
all, daily, weekly, monthly 1-indexed page returned (echoes the request, or 1 if omitted)
x >= 1Page size used for this response (echoes the request, or the default if omitted)
x >= 1Total number of usage_events rows for this account in the selected period (i.e. the size of the full result set before pagination). The client derives has_more as page * limit < total_count and shows 'X of Y events'. Computed via a COUNT(*) query alongside the paginated row fetch.
x >= 0Raw usage_events rows, sorted by created_at descending
Admin credit grants made against this account in the selected period, sorted by created_at descending — the write-side counterpart to events. A grant is a staff member setting the balance through POST /api/admins/credits, so unlike an event it carries an actor and a reason. Not paginated by page/limit and not counted in total_count, which describe usage_events only; capped at the 500 most recent grants in the period. Empty for the overwhelming majority of accounts, which have never been granted anything.
Error message (only present if status is 'error')
