Run a custom report (arbitrary groupBy + metrics)

POST

/api/v1/analytics/report

curl --request POST \
  --url https://example.com/api/v1/analytics/report \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "from": "2026-03-01T00:00:00Z", "to": "2026-03-08T00:00:00Z", "timezone": "Europe/Moscow", "groupBy": [ "sub_id:sub_id_2" ], "filters": [ { "field": "country", "operator": "eq", "value": "US" } ], "metrics": [ "clicks", "revenue", "roi" ], "orderBy": { "field": "revenue", "direction": "asc" }, "limit": 100, "offset": 0, "dateBasis": "click", "compareWith": "previous_period", "customMetrics": [ { "name": "epc_x1000", "formula": "revenue / clicks * 1000" } ] }'

Authorizations

• bearer

Request Body^required

Media typeapplication/json

object

from

required

string

Example

2026-03-01T00:00:00Z

to

required

string

Example

2026-03-08T00:00:00Z

timezone

IANA timezone for date/hour/week/month bucketing. Defaults to the requesting user’s profile timezone (see PATCH /users/me).

string

Example

Europe/Moscow

groupBy

required

1..5 dimensions, e.g. [“date”, “country”] or [“sub_id:sub_id_2”]. Allowed: date, hour, week, month, link, offer, landing, network, traffic_source, country, city, device, os, browser, language, referer, bot, sub_id:<sub_id_1..sub_id_30>.

Array<string>

Example

[
  "sub_id:sub_id_2"
]

filters

Array<object>

object

field

required

Dimension to filter on — same vocabulary as groupBy (e.g. “country”, “sub_id:sub_id_2”)

string

Example

country

operator

required

string

Allowed values: eq neq in not_in

value

required

Value to compare against. Array required for in/not_in.

object

Example

US

metrics

Restrict output to these metric names (base or custom). Default: all.

Array<string>

Example

[
  "clicks",
  "revenue",
  "roi"
]

orderBy

object

field

required

A groupBy dimension token or a metric name (base or custom)

string

Example

revenue

direction

string

default: desc

Allowed values: asc desc

limit

number

default: 100 >= 1 <= 1000

offset

number

0

dateBasis

‘click’: a conversion is attributed to the period of the click it’s linked to. ‘conversion’: attributed to its own converted_at.

string

default: click

Allowed values: click conversion

compareWith

string

Allowed values: previous_period

customMetrics

Array<object>

object

name

required

Name this custom metric will appear under in the output

string

Example

epc_x1000

formula

required

Arithmetic expression over base metric names: + - * / and parentheses only

string

Example

revenue / clicks * 1000

Responses

200

Media typeapplication/json

object

from

required

string

to

required

string

timezone

required

string

dateBasis

required

string

Allowed values: click conversion

groupBy

required

Array<string>

rows

required

Array<object>

object

dimensions

required

Keyed by the groupBy token that produced it, e.g. “country”, “sub_id:sub_id_2”

object

metrics

required

Keyed by metric name (base metrics + any customMetrics)

object

totals

required

Totals across the whole filtered date range, ignoring groupBy

object

costAttributed

required

Whether a manual cost_records lookup was possible for the requested groupBy (“link”, a single “sub_id:” and/or one date/week/month bucket; each record is spread evenly over the days of its period). Filters other than “link is one of…” also switch it off. cost/profit/roi/cpc/cpm are populated either way — manual entries win when present for a row, otherwise cost falls back to the sum of the automatic per-click cost model (click_events.cost).

boolean

comparison

object

from

required

string

to

required

string

metrics

required

Same metrics as totals, for the previous equal-length period

object

deltaPercent

required

(current - previous) / |previous| * 100, per metric. Null when not computable.

object

limit

required

number

offset

required

number

totalGroups

required

Total number of groups before limit/offset was applied

number

Example

{
  "dateBasis": "click"
}