Skip to main content
GET
cURL

Authorizations

x-api-key
string
header
required

Your Recoup API key. Learn more.

Query Parameters

account_id
string<uuid>
required

UUID of the account whose usage_events rows to return.

period
enum<string>
default:monthly

Window to filter created_at against. Same semantics as the rollup endpoint. Defaults to monthly.

Available options:
all,
daily,
weekly,
monthly
limit
integer
default:100

Page size — number of events to return per request, sorted by created_at descending. Defaults to 100; max 500.

Required range: 1 <= x <= 500
page
integer
default:1

1-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).

Required range: x >= 1

Response

Usage events retrieved successfully

status
enum<string>
required

Status of the request

Available options:
success,
error
account_id
string<uuid>
required

UUID of the account whose events were returned (echoes the request)

period
enum<string>
required

The period the response was filtered to (echoes the request)

Available options:
all,
daily,
weekly,
monthly
page
integer
required

1-indexed page returned (echoes the request, or 1 if omitted)

Required range: x >= 1
limit
integer
required

Page size used for this response (echoes the request, or the default if omitted)

Required range: x >= 1
total_count
integer
required

Total 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.

Required range: x >= 0
events
object[]
required

Raw usage_events rows, sorted by created_at descending

grants
object[]
required

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
string

Error message (only present if status is 'error')