Concepts

Files and pagination

Nothing in the API pages through results with a cursor or an offset. List endpoints answer in one response, and a large export arrives as several CSV files that the export result lists in full.

No cursor pagination#

There are no page, cursor or offset parameters anywhere. Each list endpoint returns everything at once, and an export's result lists every file of the export. To read a lot of data, request one export for the whole period and download all its files.

How an export is split#

MTA plans the files when it processes the export, and keeps the plan, so file 3 is the same file every time you fetch the result. The rules:

A DAILY export never puts two calendar months in one file.
Within that, whole days are packed into files of at most 25,000 data lines. With WEEKLY or MONTHLY the unit is a whole week or month, and with export_aggregation BREAKDOWN it is the whole period.
A file's start_date is the day after the previous file's end_date, so the files cover the whole period with no gap, even on days with no rows.
An export with no rows is one file holding only the header.

For example, October by day at ad level, then the first of November, which was too large for one file:

Part of a result

{
  "rows": 61000,
  "files": [
    {
      "url": "https://…/0?expires=…&signature=…",
      "rows": 25000,
      "start_date": "2026-10-01",
      "end_date": "2026-10-25",
      "part": 0,
      "parts": 1
    },
    {
      "url": "https://…/1?expires=…&signature=…",
      "rows": 6000,
      "start_date": "2026-10-26",
      "end_date": "2026-10-31",
      "part": 0,
      "parts": 1
    },
    {
      "url": "https://…/2?expires=…&signature=…",
      "rows": 14800,
      "start_date": "2026-11-01",
      "end_date": "2026-11-01",
      "part": 0,
      "parts": 2
    },
    {
      "url": "https://…/3?expires=…&signature=…",
      "rows": 15200,
      "start_date": "2026-11-01",
      "end_date": "2026-11-01",
      "part": 1,
      "parts": 2
    }
  ]
}

Days split into parts#

A single day (or week, month or period) with more than 25,000 lines is split into parts files that all cover the same dates. Each line goes to the part its dimension values hash to, so a line is never split or repeated across files, and the parts together hold the day exactly once. The parts are only roughly even.

Reading the files#

Every file starts with the same header row; the result's columns lists it. Load every file of an export into one table.
The links in result and files[].url work for an hour from when you fetched the result. Fetch the result again for fresh ones. The order and content of the file list do not change.
Each download says where it sits: X-File-Index and X-File-Count. X-Row-Count gives its data lines, to check the file arrived whole.
Files are read from current data when you download them. If MTA restated recent days between processing and download, the file carries the new numbers, and its line count can differ from files[].rows.

Downloading files in parallel is fine; they are independent. The server gives each download up to 300 seconds, and the files are sized to finish well inside that.

List endpoints#

Endpoint	Returns
GET /exports/metrics	All 537 metric ids in one array. The list is the same for every brand.
GET /exports/attribution-models	The brand's enabled models, or with `include_disabled=true` every model the API knows.
GET /exports/breakdowns	The four breakdown keys, each with every value the brand's data carries, sorted.

None of them has a page size or a limit. See API reference for each one.

Sending data in batches#

The endpoints that take data in limit the size of each request. Send more as several requests; each one is an upsert, so a retried batch does no harm.

Endpoint	Per request
POST /orders	1 to 1,000 orders, and at most 20 MB.
POST /spend	1 to 10,000 rows.
POST /views	Up to 10,000 views and 50 coverage ranges, and at most 20 MB.

A body that is not valid gets 400 with the first 50 problems in issues. Fix them and send the whole batch again; nothing from a refused batch was stored.

Questions about the API: support@growthdept.ai.