---
title: "POST /api/v1/affiliate/reports/query"
method: POST
path: "/api/v1/affiliate/reports/query"
tags: ["Affiliation", "Reporting"]
---

# POST /api/v1/affiliate/reports/query

`POST /api/v1/affiliate/reports/query`

Runs a strictly validated report with an Affiliate scope derived from the authenticated session. Client input cannot replace that scope.

## Cookies

- `billing_session` string

## Request body

- object
  - `cumulative` object
    - `untilPayment` integer
    - `untilSubscriptionDay` integer
  - `dateBasis` 'event' | 'subscription'
  - `dimensions` string[]
  - `filters` object[]
    - `field` string, required
    - `operator` 'eq' | 'neq' | 'in' | 'not_in' | 'gt' | 'gte' | 'lt' | 'lte', required
    - `value` union, required
      - number
      - string
      - union[]
        - union
          - number
          - string
  - `having` object[]
    - `field` string, required
    - `operator` 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte', required
    - `period` integer
    - `value` number, required
  - `includeTotals` boolean
  - `metrics` string[], required
  - `order` object[]
    - `direction` 'asc' | 'desc', required
    - `field` string, required
    - `period` integer
  - `page` integer
  - `pageSize` integer
  - `periods` object[], required
    - `from` union, required
      - string, date
      - string, date-time
    - `from2` union
      - string, date
      - string, date-time
    - `to` union, required
      - string, date
      - string, date-time
    - `to2` union
      - string, date
      - string, date-time
  - `timezoneOffsetMinutes` integer

## Response `200`

Affiliate-scoped report rows, totals, pagination, and dimension metadata.

- object
  - `data` object[], required
  - `meta` object, required
    - `dimensionCoverage` object[], required
      - `defaultedTables` string[], required
      - `dimension` string, required
      - `populatedTables` string[], required
    - `dimensions` string[], required
    - `metrics` string[], required
    - `periods` integer, required
    - `tables` string[], required
    - `warnings` string[], required
  - `pagination` object, required
    - `page` integer, required
    - `pageSize` integer, required
    - `totalRows` integer, required
  - `totals` object, nullable, required

## Other responses

- `400` — The report contract, metric, dimension, filter, or policy is invalid.
- `401` — No valid Affiliate session exists.
- `503` — Reporting is unavailable.

---

[API](https://skmtc.dev/expertschat/apis/billing-core-api.md) · [All operations](https://skmtc.dev/expertschat/apis/billing-core-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/expertschat/billing-core-api/revisions/c6d0e986ce32/schema)