Download an export file

Streams one CSV file of a finished export from a signed link in its result.

GEThttps://mta.growthdept.ai/api/v1/exports/data-export/download/{brandId}/{id}/{file}

Request#

Request

curl -sS -D part-0.headers -o part-0.csv "$DOWNLOAD_URL"

Every file, with a completeness check (needs jq)

# Download every file of an export and check each one arrived whole.
i=0
for url in $(curl -sS "https://mta.growthdept.ai/api/v1/exports/data-export/result/$EXPORT_ID" \
    -H "Authorization: $MTA_API_KEY" -H "Data-Client-ID: $MTA_BRAND_ID" | jq -r '.result[]'); do
  curl -sS -D "part-$i.headers" -o "part-$i.csv" "$url"
  expected=$(grep -i '^x-row-count:' "part-$i.headers" | tr -dc '0-9')
  actual=$(( $(wc -l < "part-$i.csv") - 1 ))
  if [ "$expected" = "$actual" ]; then echo "part-$i.csv: $actual lines"; else echo "part-$i.csv is short: download it again"; fi
  i=$((i + 1))
done

Response#

Response 200 headers

HTTP/2 200
content-type: text/csv; charset=utf-8
content-disposition: attachment; filename="nb_ad-7d3e9b20-000000000000.csv"
cache-control: private, no-store
x-row-count: 25000
x-file-index: 0
x-file-count: 2

First line of the file

date,campaign_name,campaign_id,adset_name,adset_id,ad_name,ad_id,status,accounting_mode,attribution_model,attribution_window,spend,attributed_revenue,roas,orders

Authentication#

No API key. The link's expires and signature parameters are the credential, so use the links exactly as the result gives them.

Links stay valid for an hour, even if the key that fetched the result is revoked in the meantime.

Parameters#

Name	In, type	Description
`brandId`required	path, uuid	The brand's id.
`id`required	path, uuid	The export's id.
`file`required	path, integer	The file's position in `result`, counting from 0.
`expires`required	query, integer	When the link stops working, in Unix seconds.
`signature`required	query, string	The link's signature.

Response fields#

Response headers:

Header	Type	Description
`X-Row-Count`	integer	Data lines after the header, counted from the same rows the body is read from.
`X-File-Index`	integer	This file's position, counting from 0.
`X-File-Count`	integer	How many files the export has.
`Content-Disposition`	string	The file name: the request's `export_file_name`, or `nb_<level>-` and the first 8 characters of the export id, then `-` and the position padded to 12 digits.

Status codes#

Status	Meaning	Body
200	The CSV file.
403	The link is not valid: it was altered, or it is for another brand or file.	`This download link is not valid.`
404	No such export, the export has not finished, or no file at that position.	`Not found.`
410	The link has expired. Fetch the result again for a new one.	`This download link has expired. Fetch the export result again for a new one.`
500	Something failed on our side. Fetch the result again and retry with a fresh link.

What a file holds#

Every file of an export starts with the same header row, so the files read as shards of one table. An export with no rows is one file holding only the header.
A metric with no value is an empty, unquoted field. MTA stores a zero as no value, so an empty field means zero or not applicable; on Clicks + Deterministic Views rows it can also mean withheld. Never read a withheld cell as zero.
An _id column with no value is a quoted empty string, "".
Numbers carry no trailing zeros. Text is quoted only when it holds a comma, a quote or a line break.
Files are read from current data when you download them, so a file downloaded after MTA restated recent days carries the restated numbers.

Checking that a download is complete#

Count the data lines of each file and compare them with its X-Row-Count. The two always agree when the transfer finished; a shorter file means the connection dropped, so download it again.

Counting lines with wc -l is exact unless a text field holds a line break; a CSV parser's row count always is. files[].rows in the result is the count when the export was processed. It differs from X-Row-Count only if MTA added or removed rows for those dates since, and then the file as served is the one to trust.

The server gives a download up to 300 seconds. Files are sized to finish well inside that.

Questions about the API: support@growthdept.ai.