Skip to main content
GET
/
v0
/
costs
/
report
Report
curl --request GET \
  --url https://api.paygentic.io/v0/costs/report \
  --header 'Authorization: Bearer <token>'
import requests

url = "https://api.paygentic.io/v0/costs/report"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.paygentic.io/v0/costs/report', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.paygentic.io/v0/costs/report",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"net/http"
"io"
)

func main() {

url := "https://api.paygentic.io/v0/costs/report"

req, _ := http.NewRequest("GET", url, nil)

req.Header.Add("Authorization", "Bearer <token>")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.paygentic.io/v0/costs/report")
.header("Authorization", "Bearer <token>")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.paygentic.io/v0/costs/report")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
{
  "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>"
  ]
}
{
"message": "The requested resource was not found",
"error": "not_found"
}
{
"message": "The requested resource was not found",
"error": "not_found"
}
{
"message": "The requested resource was not found",
"error": "not_found"
}
{
"message": "The requested resource was not found",
"error": "not_found"
}

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.