---
title: "Returns aggregated report grouped by the specified dimension(s)."
method: GET
path: "/report"
tags: ["Reports"]
---

# Returns aggregated report grouped by the specified dimension(s).

`GET /report`

Returns aggregated performance data grouped by the specified dimension(s).
This is the primary reporting endpoint for campaign analytics.

## Prerequisites

Before building report queries, call these endpoints to discover account-specific configuration:
- **GET /column/info** — returns all valid groupBy dimensions (canGroupBy: true) and metric
 columns with their display labels and types.
- **GET /custom-conversions** — returns custom conversion type definitions
 (index 1-20 mapping to customConversions{N} and customRevenue{N} columns).
- **GET /custom-columns** — returns user-defined derived metric names that can be passed as
 column values alongside built-in metrics.
- **GET /traffic-source** — returns each source's *customVariables[]* array, where every entry
 carries *index*, *name* (user-facing label) and *parameter* (the URL parameter the source sends
 on the click). Variable meanings are defined per traffic source — the same slot index can mean
 different things on different sources.

## Key behaviors

- **Date range is half-open [from, to)**: the 'to' date is exclusive.
To query March 5 in full, set from=2026-03-05T00:00:00Z and to=2026-03-06T00:00:00Z.
- **Name columns must be requested explicitly**: groupBy=campaignId only returns campaignId.
Add campaignName to the column list to get human-readable names.
- **Column is a repeated parameter**: use column=visits&column=clicks, not column=visits,clicks.
- **Drilldown filters**: use filter1=campaignId&filter1Value=<id> to filter results.
Multiple filters: filter1/filter1Value, filter2/filter2Value, etc.

## Metric formulas

- **CTR** = clicks / visits (lander effectiveness)
- **CR** = conversions / clicks (offer quality)
- **CV** = conversions / visits (end-to-end funnel efficiency)
- **ROI** = (revenue - cost) / cost (expressed as percentage, e.g. 125.0 = 125%)
- **CPA** = cost / conversions
- **EPV** = revenue / visits
- **EPC** = revenue / clicks
- **CPV** = cost / visits

## Direct-linking campaigns

Campaigns without a lander (direct-linking) never record click events.
CTR, CR, clicks, and EPC are always zero — this is expected, not a tracking error.
Use CV (conversions/visits) and EPV (revenue/visits) instead.
Detection: inspect the campaign's flow for lander presence (GET /campaign/{id}), or run
groupBy=landerId filtered to the campaign — if no landers appear, it is direct-linking.

## This endpoint vs /report/conversions

This endpoint returns aggregated data grouped by dimensions.
For individual conversion events (no grouping), use GET /report/conversions instead —
that endpoint does not accept groupBy, conversionTimeMode, or include parameters.

## Rate limits and response size

Throttling applies at three levels:

**Per Bearer token (per user)** — three independent buckets:

| Bucket | Base allocation | Notes |
|---|---|---|
| Per-second (burst) | **~4 req/s** | Hit first by most clients |
| Concurrent in-flight | **~30** | Counted while a request is on the wire |
| Per-minute (sustained) | Higher; rarely the binding cap | Only hit if you sustain perfectly even pacing |

Base allocation only — many accounts have higher negotiated limits.
Contact support for your values.

**Per IP** — anti-abuse cap; authenticated clients from a single host
should not normally hit it.

**Per-user utilization budget (reports only)** — independent of request
count. Heavier queries (longer date ranges, wider *groupBy*, more *column*
values) cost more; light queries cost little. Often the binding cap on
heavy analytics workloads — prefer many narrow queries over a few enormous
ones if you see 429s without exceeding the per-second cap.

Exceeding any of these returns **429 Too Many Requests** with an empty
body and no *Retry-After* header. Back off and retry.

Per-request row cap: see the *limit* query parameter.
Per-account caps and throttling thresholds are configurable; contact support to raise them.

## Query parameters

- `include` 'ALL' | 'ACTIVE' | 'ARCHIVED' | 'TRAFFIC'
- `offset` integer
- `tz` string
- `column` string[]
- `filter1` string
- `compareFrom` string
- `filter2` string
- `groupBy` string[], required
- `compareTo` string
- `sort` string
- `filter1Value` string
- `filter` string
- `limit` integer
- `from` string, required
- `currency` string
- `to` string
- `filter2Value` string
- `workspaces` string[]
- `conversionTimeMode` 'CONVERSION' | 'VISIT'
- `direction` 'ASC' | 'DESC'

## Response `200`

Aggregated report data.

## Other responses

- `429` — Rate limit exceeded. Empty body; no Retry-After header. See the operation description for bucket types and back-off guidance.

---

[API](https://skmtc.net/voluum/apis/voluum-api.md) · [All operations](https://skmtc.net/voluum/apis/voluum-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voluum/voluum-api/versions/81b7ec5eb841/schema)