Skip to main content
GET
Report

Authorizations

Authorization
string
header
required

API key authentication

Query Parameters

merchantId
string

The merchant organization ID. If omitted, defaults to the merchant associated with the authenticated API key.

from
string<date-time>
required

Start of the query window (ISO 8601).

to
string<date-time>
required

End of the query window (ISO 8601).

groupBy
string
required

Dimension to group results by. Valid values: 'cost' (group by cost ID), 'customer' (group by customer ID), or any dimension key from a filtered cost's groupBy schema for dynamic dimension grouping. Dynamic dimension values require exactly one costId filter.

costId
string[]

Filter to specific cost(s). Enables dynamic dimension grouping.

subject
string

Filter to a specific subject (customer/event subject ID).

filterGroupBy
string

JSON-encoded dimension filters (e.g. {"region":"us-east-1"}). Max 4KB, max 5 keys.

Maximum string length: 4096
topN
integer
default:9

Number of top groups to return. An 'Other' bucket aggregates remaining groups.

Required range: 1 <= x <= 25
comparePriorPeriod
boolean
default:false

When true, include prior-period comparison data in each group.

excludeEmpty
boolean
default:false

When true, leave out groups with neither cost nor usage in the period. They are dropped before ranking, so they take no top-N slot, do not appear in the 'Other' bucket and are not counted in pagination.total. emptyGroupCount says how many were left out.

windowSize
enum<string>

Time window granularity for the time-series breakdown.

Available options:
HOUR,
DAY,
MONTH
sort
enum<string>
default:totalCost

Field to sort groups by.

Available options:
totalCost,
totalQuantity
sortDir
enum<string>
default:desc

Sort direction.

Available options:
asc,
desc
offset
integer
default:0

Number of groups to skip for pagination.

Required range: x >= 0
limit
integer
default:25

Maximum number of groups to return.

Required range: 1 <= x <= 100
currency
string

Filter costs to a single ISO 4217 currency code (e.g. 'USD'). When omitted, defaults to the merchant's primary currency.

Response

Aggregated cost report

object
enum<string>
default:cost_report
required
Available options:
cost_report
currency
string
required

ISO 4217 currency code for all monetary values in this response.

period
object
required
groupBy
string
required

The active grouping dimension (e.g. 'cost', 'customer', or a dynamic dimension key).

totalCost
number
required

Sum of cost across all groups (not just top N).

totalQuantity
number
required

Sum of quantity across all groups.

groups
object[]
required

Top N groups plus an 'Other' bucket aggregating the remainder.

timeSeries
object[]
required

Time-bucketed breakdown per group. Keys in each window's 'groups' object correspond to CostReportGroup.key. The 'Other' bucket key is 'other'.

availableDimensions
string[]
required

Dimension keys available for further drill-down (populated when a single cost is filtered).

pagination
object
required
warnings
string[]

Non-fatal warnings, e.g. costs that could not be queried.

groupCount
integer

Every group the report found, empty groups included, before top-N folding into 'Other' and before pagination.

Required range: x >= 0
emptyGroupCount
integer | null

Groups with neither cost nor usage in the period, counted over the whole report and reported whether or not excludeEmpty is set. Null when a cost read failed (see warnings): a group empty in the costs that loaded may have usage in the one that failed, so none is counted and excludeEmpty leaves nobody out.

Required range: x >= 0
costRange
object | null

Where the caller's cost data actually lies in time. Present only when the selected range returned no cost. An object carries the bounds of the real cost events; null means the caller has no cost event at any time; an absent field means the extent was not resolved, because the result was not empty, because the lookup failed, or because the metering service does not serve the bounds method. An absent field must never be read as an absence.