Skip to main content
GET
/
v0
/
costs
/
report
Report
curl --request GET \
  --url https://api.paygentic.io/v0/costs/report \
  --header 'Authorization: Bearer <token>'
{
  "object": "cost_report",
  "currency": "<string>",
  "period": {
    "from": "2023-11-07T05:31:56Z",
    "to": "2023-11-07T05:31:56Z"
  },
  "groupBy": "<string>",
  "totalCost": 123,
  "totalQuantity": 123,
  "groups": [
    {
      "key": "<string>",
      "label": "<string>",
      "totalCost": 123,
      "totalQuantity": 123,
      "percentOfTotal": 123,
      "isOther": true,
      "unit": "<string>",
      "priorPeriod": {
        "cost": 123,
        "changePercent": 123
      }
    }
  ],
  "timeSeries": [
    {
      "windowStart": "2023-11-07T05:31:56Z",
      "windowEnd": "2023-11-07T05:31:56Z",
      "groups": {}
    }
  ],
  "availableDimensions": [
    "<string>"
  ],
  "pagination": {
    "total": 123,
    "limit": 123,
    "offset": 123
  },
  "warnings": [
    "<string>"
  ]
}

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.

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