APG PayAPG Paydocs

Reporting

Create report queries

POST/report-queries

Ask a dataset a question. The answer is returned and not stored.

Permissions

Required permission
reports:query

Requires the `query` action on `reports` for the supplied runtime context

Request body

This body is a tagged shape: type is always "RqryCmdRun". Send it; more variants can be added, and a caller that switches on it keeps working when they are.

Discriminated by type
type = "RqryCmdRun"
reportDatasetIdstringrequired
measuresarray of string

What to add up, by name from the dataset's measures.

dimensionsarray of string

What to group by, by name from the dataset's dimensions.

Bucket by time. Absent for a total over all time.

Every filter must hold. A value is written as text whatever the dimension's kind: 12.50, 2026-09-01.

limitinteger (int32)

At most this many rows.

Example 25

pagestring

next from the previous answer, to continue the same row-mode question. It is opaque and forward only, and a question changed in anything but limit refuses it with 400.

segmentsarray of string

Named filters from the dataset's segments, applied as well as filters.

Every one must hold of a group for it to be kept, tested after grouping. Each names one of measures; a value is a decimal written as text. Absent for none.

Keep only the values of one dimension with the most of a measure, and fold the rest into an Others row.

Ask as tenants beneath the caller, as a marketplace views a report as some of its merchants. Every tenant must be one the caller may read, and the answer stays within the caller's own tenants. Absent to ask as the caller.

asAtstring (date-time)

Read each balance as at this instant: its latest snapshot before it, and every earlier one for a highest or lowest. Only balance measures have a value at an instant, and the question takes no time. Absent for all time.

Example 2026-08-19T04:21:07Z

Lay the answer out as a grid: rows and columns each name some of dimensions, together each of them once. The answer stays one row per cell of the grid, each row saying its level, with a total and, with subtotals, a subtotal per leading row dimension. Absent for none.

timezonestring

The timezone the question is answered in, an IANA name such as Australia/Perth or an offset such as +10:00, which keeps no daylight saving: where its buckets start, how its dates, periods and relative ranges are read, and which local day or hour a date part names. Absent for the asker's own, which the dataset's timezone gives: the timezone every active merchant the asker reads keeps, or the dataset's where they keep several.

curl -X POST https://api.tst.au.apgpay.dev/report-queries \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "RqryCmdRun",
  "reportDatasetId": "string",
  "measures": [
    "string"
  ],
  "dimensions": [
    "string"
  ],
  "time": {
    "type": "RqryTimeSliceAttributes",
    "grain": "string",
    "range": {
      "type": "RqryRangeBetween",
      "from": "2026-08-19",
      "to": "2026-08-19"
    },
    "compare": "PreviousPeriod"
  },
  "filters": [
    {
      "type": "RqryFilterAbove",
      "dimension": "string",
      "value": "string"
    }
  ],
  "sort": [
    {
      "type": "RqrySortDimension",
      "dimension": "string",
      "ascending": true
    }
  ],
  "limit": 25,
  "page": "string",
  "segments": [
    "string"
  ],
  "measureFilters": [
    {
      "type": "RqryMeasureFilterAbove",
      "measure": "string",
      "value": "string"
    }
  ],
  "top": {
    "type": "RqryTopAttributes",
    "dimension": "string",
    "count": 42,
    "measure": "string"
  },
  "narrowTo": {
    "type": "RqryNarrowCustomers",
    "customerIds": [
      "cust_9f2Kd8QpLzXw"
    ]
  },
  "asAt": "2026-08-19T04:21:07Z",
  "pivot": {
    "type": "RqryPivotAttributes",
    "rows": [
      "string"
    ],
    "columns": [
      "string"
    ],
    "subtotals": true
  },
  "timezone": "string"
}'

Responses

The response is a tagged shape: type is always "RqryCreateRspAttributes". Switch on it; subtypes can be added, and a client that already reads it will not break.

Discriminated by type
type = "RqryCreateRspAttributes"

The resource that was created.

Example
{
  "type": "RqryCreateRspAttributes",
  "created": {
    "type": "RqryResultAttributes",
    "reportDatasetId": "string",
    "columns": [
      {
        "type": "RqryColumnAttributes",
        "role": "Time",
        "name": "Ada Lovelace",
        "grain": "string",
        "axis": "Rows"
      }
    ],
    "rows": [
      {
        "type": "RqryRowAttributes",
        "level": "Detail",
        "depth": 1250,
        "cells": [
          "string"
        ]
      }
    ],
    "truncated": true,
    "next": "string",
    "asOf": "2026-08-19T04:21:07Z",
    "timezone": "string",
    "labels": [
      {
        "type": "RqryLabelsAttributes",
        "dimension": "string",
        "values": [
          {
            "type": "RdsetValueAttributes",
            "value": "string",
            "label": "string"
          }
        ]
      }
    ],
    "currentAsOf": "2026-08-19T04:21:07Z"
  }
}

Error responses