Getting started

1. Create a key#

An owner or admin of the brand's organization creates keys in the app, under Settings > API Keys. Name the key after what will use it, such as “Warehouse reader”, and tick only what it needs. To read exports, that is Read your attribution data, the export:read scope.

The key is shown once. Copy it into your secrets store before you close the dialog; MTA keeps only a hash of it.

2. Set the key and brand id#

The API Keys page also shows the brand id, labelled Data-Client-ID, with a copy button. Put both values in your shell so the commands below run as pasted:

export MTA_API_KEY='paste the key here'
export MTA_BRAND_ID='paste the Data-Client-ID here'

3. Check the key#

Ask the API which brand the key belongs to:

curl "https://mta.growthdept.ai/api/v1/exports/account" \
  -H "Authorization: $MTA_API_KEY" \
  -H "Data-Client-ID: $MTA_BRAND_ID"

A 200 lists the brand's name, time zone, currency, and the model ids and windows it has switched on. A 401 means the key and the brand id do not belong together, or the key was revoked. The fields are described under Read the account.

4. Request an export#

This request asks for the last 7 days by campaign and by day, with spend, attributed revenue, ROAS and orders under the Linear model, over a 7-day window, on Accrual performance. linear is on for every new brand; if the account answer did not list it, use one of the ids it did list.

EXPORT_ID=$(curl -sS -X POST "https://mta.growthdept.ai/api/v1/exports/data-export" \
  -H "Authorization: $MTA_API_KEY" \
  -H "Data-Client-ID: $MTA_BRAND_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "level": "campaign",
    "time_granularity": "DAILY",
    "period_type": "LAST_7_DAYS",
    "options": { "export_aggregation": "DATE", "include_ids": true },
    "attribution_options": {
      "attribution_models": ["linear"],
      "attribution_windows": ["7"],
      "accounting_modes": ["accrual"]
    },
    "metrics": [
      { "id": "spend" },
      { "id": "revAttributed" },
      { "id": "roas" },
      { "id": "txns" }
    ]
  }' | jq -r .id)
echo "$EXPORT_ID"

The answer is 201 with the export's id, which the command keeps in EXPORT_ID. Every field the request can take is under Create an export.

5. Poll the result#

Seven days is processed while the create request runs, so the first poll usually says SUCCESS. A period longer than 31 days waits for the job dispatcher, which runs every minute. This loop checks every 5 seconds:

while true; do
  status=$(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 .status)
  echo "$status"
  [ "$status" = "PENDING" ] || break
  sleep 5
done

On ERROR, create the export again. The full answer, with its download links and per-file line counts, is described under Get an export result.

6. Download the files#

The result lists one signed link per file. Links need no API key and work for an hour from when you fetched the result. This loop fetches the result, downloads each file, and checks each file's data lines against its X-Row-Count header:

# 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

Every file starts with the same header row. For the request above it is:

date,campaign_name,campaign_id,status,accounting_mode,attribution_model,attribution_window,spend,attributed_revenue,roas,orders

Next steps#

1. Pick the models and windows that match how your team reads performance: Attribution models.
2. Choose metrics from the metrics reference, which shows each one's CSV column and format.
3. Before you schedule a job, read Rate limits and Errors.