Admin API: reports

The methods on this page build the same reports as the report builder in the panel and return data on individual clicks. Authorization is described on the Admin API: overview and authorization page, and the request format and common error codes on the Request, response and error format page.

Methods and token scopes

• A Summary reports («Сводные отчёты») token (reports:read) has access to three methods: POST /api/v1/reports, POST /api/v1/reports/export and GET /api/v1/custom-metrics.
• The other 14 methods need Full access («Полный доступ») (full).

A reports:read token builds a report only with the allowed groupings and filters. Their list is in the Summary reports access limits section. For a report with other fields, the server responds 403 with code token_scope.

Background exports and saved reports belong to the user who created the token. The API also shows the ones this user created in the panel.

Report request

Three methods accept the same body: POST /reports, POST /reports/export and POST /report-exports.

The time zone sets the boundaries of hours, days, weeks and months in groupings, and the spend day. What is counted by the click date and what by the conversion date is explained on the Period, time zone and attribution page.

Groupings

• Grouping values in the response are always strings.
• campaign, stream, offer, lander and source contain IDs, not names.
• Flags come as 1 or 0.
• A week starts on Monday. In dow, Monday is 1 and Sunday is 7.
• The sub_id_12 value is not revealed: the row contains *** or nothing.

Metrics

Built-in metrics: clicks, unique_clicks, bots, lp_clicks, lp_ctr, leads, sales, rejected, conversions, cost, revenue, revenue_expected, profit, profit_expected, roi, roi_expected, cr, approval, cpa, epc, cpl. The formulas are on the Report metrics and formulas page.

You can also pass in metrics:

• the key of a custom metric — its name field;
• a conversion type column — cv_ followed by the type ID without hyphens. The IDs are returned by GET /api/v1/conversion-types, see Admin API: conversions and postback.

Amounts come as numbers in USD, percentages as numbers without the % sign.

Filters

A condition is an object of three strings:

The operators depend on the kind of field:

• has and not_has check whether the field is filled in. The value is ignored.
• For a flag, the values 0, false, no, off, нет and an empty string mean “no”; any other value means “yes”.
• For a metric, value is a finite number.
• You cannot filter by time groupings: the period is set by from and to.

A group in filter_groups is an object {"mode": "or", "filters": [...]}. The mode field takes and or or, and the filters array cannot be empty. Groups are combined with each other and with filters using AND. In an or group, you cannot mix click fields and metrics. A request can have no more than 64 conditions in total. The operator values and examples are on the Report filters page.

Sorting

sort.field is one of the selected groupings or a metric, built-in or custom. sort.direction is asc or desc. The other groupings follow in ascending order.

Building a report

Build a report

POST /api/v1/reports

Returns a page of the report and the totals for all rows. Token scope: reports:read or full. The body is a report request. A report is built in no more than 70 seconds.

Response — code 200:

Compare timezone in the response with the requested one: if the time zone is not available on the server, the report is calculated in UTC.

To get the next page, repeat the request with offset increased by limit while has_more is true.

Example request:

curl -X POST https://panel.example.com/api/v1/reports \
  -H "Api-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2026-10-01T00:00:00Z",
    "to": "2026-10-07T23:59:59Z",
    "timezone": "Europe/Warsaw",
    "dimensions": ["campaign", "country"],
    "metrics": ["clicks", "leads", "cost", "revenue", "roi"],
    "filters": [
      {"field": "bot", "op": "eq", "value": "0"},
      {"field": "clicks", "op": "gte", "value": "100"}
    ],
    "sort": {"field": "roi", "direction": "desc"},
    "limit": 100
  }'

Example response:

{
  "columns": ["campaign", "country", "clicks", "leads", "cost", "revenue", "roi"],
  "rows": [
    ["c41a9e07-52bd-4f13-8a60-9d7e6f5a4b3c", "PL", 1520, 42, 310.5, 504, 62.318840579710144],
    ["7b0c1d52-3f4e-4a6b-9c8d-1e2f3a4b5c6d", "CZ", 830, 17, 190, 204, 7.368421052631579]
  ],
  "totals": {"clicks": 2350, "cost": 500.5, "leads": 59, "revenue": 708, "roi": 41.45854145854146},
  "truncated": false,
  "row_limit": 100,
  "total_rows": 2,
  "limit": 100,
  "offset": 0,
  "has_more": false,
  "attribution": "click",
  "timezone": "Europe/Warsaw"
}

Errors:

Get a report as a CSV file

POST /api/v1/reports/export

Builds the same report and returns it as a file right away. Token scope: reports:read or full. The body is a report request. The limit and offset fields do not affect the contents of the file: all rows go into it.

Response — code 200, type text/csv; charset=utf-8, a file name like report-20261007-101500.csv. The first line contains the column keys; there is no totals row. The file contents are described in the What's inside the CSV section, and the columns of a comparison file in the Comparison CSV section.

Limits: 100,000 rows and 32 MiB.

The errors are the same as for POST /reports, plus two more:

Background CSV exports

A background export builds the same file without waiting for a response: the request puts the report in a queue, and the finished file is kept for 24 hours from its creation. All methods need full access. The same feature in the panel is described on the Saved reports and CSV export page.

Export object:

Create an export

POST /api/v1/report-exports

Puts a report in the queue. The body is a report request. The offset field is ignored, and limit does not affect the contents of the file. The default attribution is fixed at the moment of the request.

Response — code 202 and an export object in the pending state.

List exports

GET /api/v1/report-exports

Returns the unexpired exports of the token's creator: an array of objects, up to 20, newest first. There are no parameters. Poll the list until the state of the export you need becomes ready or failed.

Download the file

GET /api/v1/report-exports/{id}/file

Returns the finished file: code 200, type text/csv; charset=utf-8, name report-<id>.csv. The id path parameter is the export ID.

curl https://panel.example.com/api/v1/report-exports/5e2f8a10-9b3c-4d7e-8f21-0a1b2c3d4e5f/file \
  -H "Api-Key: <token>" \
  -o report.csv

Delete an export

DELETE /api/v1/report-exports/{id}

Deletes an export in any state and frees a place in the quota. Response — code 204 with no body. Error: 404, code not_found.

Saved reports

A saved report is a name and a set of report builder settings: what opens in the panel from the list of saved reports. All methods need full access. Object:

The definition fields. The object takes no more than 32 KiB, and a field outside this list gives a 422 error:

List saved reports

GET /api/v1/report-views

Returns an array of the saved reports of the token's creator. Recently changed ones come first. There are no parameters.

Save a report

POST /api/v1/report-views

Creates a saved report. The body has two required fields: name and definition. Response — code 201 and the object.

Error 422 with code validation: an invalid name, settings larger than 32 KiB, an unknown field in definition, an unknown grouping, metric or operator. The reason is in message.

Edit a saved report

PUT /api/v1/report-views/{id}

Replaces the name and settings entirely. The body and checks are the same as when creating. Response — code 200 and the object. Errors: 422 with code validation, 404 with code not_found.

Delete a saved report

DELETE /api/v1/report-views/{id}

Response — code 204 with no body. Error: 404, code not_found.

Custom metrics

A custom metric is a report column calculated by a formula from built-in metrics. Metrics are shared by the whole team. The list is available to reports:read and full tokens; creating, editing and deleting — only to full. Object:

List custom metrics

GET /api/v1/custom-metrics

Returns an array of metrics. There are no parameters.

Create a metric

POST /api/v1/custom-metrics

The body contains the object fields without id. Response — code 201 and the object.

Error 422 with code validation: name и formula обязательны (name and formula are required), имя совпадает с базовой метрикой (the name matches a base metric), имя — только латиница, цифры и _ (the name — only Latin letters, digits and _) or a message that starts with ошибка в формуле: (formula error:). The messages are explained in the Error messages section.

Edit a metric

PUT /api/v1/custom-metrics/{id}

Pass all fields: name, formula, title and decimals are replaced with the values from the body. An empty format keeps the previous format. Response — code 200 and the object. Errors: 422 with code validation, 404 with code not_found.

Delete a metric

DELETE /api/v1/custom-metrics/{id}

Response — code 204 with no body. Error: 404, code not_found.

Clicks

Three methods return data on individual clicks. All of them need full access. Searching for a click by IP, subid or external_id and the full click card are described on the Admin API: logs and diagnostics page.

Click log

GET /api/v1/reports/clicks

Returns the latest clicks across all campaigns for the period, newest first.

A date that could not be parsed is replaced with the default value. Encode the + sign in a time zone offset as %2B, or pass the time in UTC with the letter Z.

Response — code 200 and an object {"items": [...]}. The click fields: time, click_id, campaign_id, source_id, offer_id, country, city, device, os, browser, ip, is_bot, cost, external_id, sub_id_1.

Errors: 503 with code no_analytics — analytics is unavailable, 400 with code report_error — the query failed.

Cloaking decision for a click

GET /api/v1/reports/click-cloak?subid=<subid>

Returns the cloaking decision for a click. The subid query parameter is required — it is the click_id from the click log.

Response — code 200. If no decision is saved for the click, you get {"found": false}. Otherwise — {"found": true, "verdict": {...}}:

Errors: 400 with code bad_request — there is no subid parameter; 404 with code not_found and the message click not found — there is no such click.

Lead data for a click

GET /api/v1/reports/click-lead?subid=<subid>

Returns the contact details that a landing page form bound to the click. The subid query parameter is required.

Response — code 200 and an object {"found": true, "lead": {...}}. The lead fields: email, phone, first_name, last_name. If there is no data for the click, found is false and the lead fields are empty.

The errors are the same as for the cloaking decision.