Skip to content
GROWTH DEPT.MTA
DocsCreate an export

API reference

Create an export

Starts an export of the brand's attributed performance and returns the export's id.

POSThttps://mta.growthdept.ai/api/v1/exports/data-export

Request#

Request
curl -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" }
    ]
  }'
A fixed month by week, two platforms, Cash snapshot
curl -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": "platform",
    "time_granularity": "WEEKLY",
    "period_type": "FIXED",
    "period_options": {
      "period_starting_at": "2026-10-01",
      "period_ending_at": "2026-10-31"
    },
    "breakdowns": [
      {
        "key": "Platform (Northbeam)",
        "values": ["Facebook Ads", "Google Ads"]
      }
    ],
    "options": { "export_aggregation": "DATE", "aggregate_data": true },
    "attribution_options": {
      "attribution_models": ["northbeam_custom"],
      "attribution_windows": ["1"],
      "accounting_modes": ["cash"]
    },
    "metrics": [
      { "id": "spend" },
      { "id": "rev", "label": "cash_revenue" },
      { "id": "txns" }
    ],
    "export_file_name": "weekly-platform-cash"
  }'

Response#

Response 201
{ "id": "7d3e9b20-5c41-4a8e-b6f2-0d9c4e1a2b33" }

Authentication#

Send the API key in Authorization and the brand id in Data-Client-ID. The key needs the export:read scope.

Each key may create 60 exports a minute. This endpoint does not count toward the 100 requests a second the other export endpoints allow. See Rate limits.

HeaderTypeDescription
AuthorizationrequiredstringThe API key. See Authentication.
Data-Client-IDrequireduuidThe brand id.
Content-Typestringapplication/json.

Body#

A JSON object. A field this table does not list is refused with 422.

FieldTypeDescription
levelstringplatform (the default), campaign, adset or ad. Sets the grain of the rows and which entity columns the file has.
time_granularitystringDAILY (the default), WEEKLY or MONTHLY, used with export_aggregation DATE. Weeks start on Monday. HOURLY is refused.
period_typestringOne of the period types under Periods. LAST_7_DAYS when left out. FIXED needs period_options.
period_options.period_starting_atwith FIXEDstring (date)The first day, YYYY-MM-DD. A date-time is accepted and only its date is read.
period_options.period_ending_atwith FIXEDstring (date)The last day, included. Not before the first day, and at most 731 days after it.
attribution_options.attribution_modelsrequiredarray of stringsOne or more model ids from List attribution models.
attribution_options.attribution_windowsrequiredarray of stringsOne or more of "1", "3", "7", "14", "30", "60", "90". They apply to Accrual rows; Cash rows always carry the lifetime window.
attribution_options.accounting_modesrequiredarray of stringsOne or both of accrual and cash.
metricsrequiredarrayOne or more metrics, in the order their columns should appear.
metrics[].idrequiredstringA metric id from List metrics.
metrics[].labelstringThe column header for this metric. Letters, digits and _; it starts with a letter, ends with a letter or digit, and is at least 3 characters. Headers must be unique and must not be a dimension column's name.
breakdownsarrayObjects with a key from List breakdowns and the values to keep. Each key at most once.
options.export_aggregationstringBREAKDOWN (the default) sums the whole period into each line, with no date column. DATE adds a date column and one line per day, week or month.
options.include_idsbooleanAdds campaign_id, adset_id and ad_id next to the names, as the level has them. Default false.
options.include_kind_and_platformbooleanAdds the kind and platform columns. Default false.
options.remove_zero_spendbooleanDrops lines whose spend sums to 0. Default false.
options.aggregate_databooleanDrops the campaign, ad set, ad and status columns and sums across them. Default false.
export_file_namestringA base name for the files: at least 3 characters of letters, digits, _, - and /, not starting or ending with /. Only the part after the last / is used.
bucket_name, aws_role, regionstringAccepted only when empty or null. MTA does not write to your GCS or S3 bucket; download the files from the result instead.

Response fields#

FieldTypeDescription
idstring (uuid)The export's id. Poll Get an export result with it.

Status codes#

StatusMeaningBody
201The export was created. Its id is in the body.
401No key, an unknown or revoked key, or a key that belongs to another brand than Data-Client-ID.{ "detail": "Unauthorized: send a valid API key in Authorization and its brand id in Data-Client-ID." }
403The key is valid but lacks export:read.{ "detail": "This API key lacks the export:read scope." }
422The body is not valid JSON, or a field is wrong. detail lists each problem with its location in the body.{ "detail": [ { "loc": ["body", "attribution_options", "accounting_modes", 0], "msg": "value is not a valid enumeration member; permitted: 'cash', 'accrual'", "type": "type_error.enum" } ] }
429The key created 60 exports in the last minute. Wait the seconds in Retry-After.{ "detail": "Rate limit exceeded: 60 data-export requests per minute per API key. Retry after 12 seconds." }
500Something failed on our side. Retry later.{ "detail": "Internal server error." }

Processing#

A period of up to 31 days is processed while the request runs, so its result has usually finished by the time you get the 201. A longer period stays PENDING until the job dispatcher picks it up; the dispatcher runs every minute.

Relative periods are resolved in the brand's time zone when the export is created. The export keeps those dates, so polling it later does not move them.

Periods#

Every period type, with the dates it covers when today is Friday 2026-11-06 in the brand's time zone. Both ends are included. The LAST_N_DAYS periods end yesterday, since today is still filling in.

period_typeCoversOn 2026-11-06
FIXEDThe dates in period_optionsas given
TODAYToday so far2026-11-06
YESTERDAYYesterday2026-11-05
YESTERDAY_AND_TODAYYesterday and today so far2026-11-05 to 2026-11-06
LAST_3_DAYSThe 3 days before today2026-11-03 to 2026-11-05
LAST_7_DAYSThe 7 days before today2026-10-30 to 2026-11-05
LAST_14_DAYSThe 14 days before today2026-10-23 to 2026-11-05
LAST_28_DAYSThe 28 days before today2026-10-09 to 2026-11-05
LAST_30_DAYSThe 30 days before today2026-10-07 to 2026-11-05
LAST_60_DAYSThe 60 days before today2026-09-07 to 2026-11-05
LAST_90_DAYSThe 90 days before today2026-08-08 to 2026-11-05
LAST_180_DAYSThe 180 days before today2026-05-10 to 2026-11-05
MONTH_TO_DATEThis month so far2026-11-01 to 2026-11-06
LAST_MONTHLast calendar month2026-10-01 to 2026-10-31
THIS_WEEKThis week from Monday, today included2026-11-02 to 2026-11-06
LAST_WEEKLast week, Monday to Sunday2026-10-26 to 2026-11-01
THIS_WEEK_AND_LAST_WEEKLast week and this week so far2026-10-26 to 2026-11-06
LAST_3_WEEKSThe 3 whole weeks before the current one2026-10-12 to 2026-11-01
LAST_4_WEEKSThe 4 whole weeks before the current one2026-10-05 to 2026-11-01
LAST_7_WEEKSThe 7 whole weeks before the current one2026-09-14 to 2026-11-01
LAST_12_WEEKSThe 12 whole weeks before the current one2026-08-10 to 2026-11-01
LAST_14_WEEKSThe 14 whole weeks before the current one2026-07-27 to 2026-11-01
LAST_26_WEEKSThe 26 whole weeks before the current one2026-05-04 to 2026-11-01
LAST_28_WEEKSThe 28 whole weeks before the current one2026-04-20 to 2026-11-01
LAST_52_WEEKSThe 52 whole weeks before the current one2025-11-03 to 2026-11-01
THIS_MONTHThis month so far2026-11-01 to 2026-11-06
THIS_MONTH_AND_LAST_MONTHLast month and this month so far2026-10-01 to 2026-11-06
LAST_3_MONTHSThe 3 whole calendar months before the current one2026-08-01 to 2026-10-31
LAST_6_MONTHSThe 6 whole calendar months before the current one2026-05-01 to 2026-10-31
LAST_9_MONTHSThe 9 whole calendar months before the current one2026-02-01 to 2026-10-31
LAST_12_MONTHSThe 12 whole calendar months before the current one2025-11-01 to 2026-10-31
YEAR_TO_DATEThis year so far2026-01-01 to 2026-11-06
LAST_YEARLast calendar year2025-01-01 to 2025-12-31
LAST_3_YEARSThe 3 whole calendar years before the current one2023-01-01 to 2025-12-31
LAST_5_YEARSThe 5 whole calendar years before the current one2021-01-01 to 2025-12-31

Columns in the file#

Every file starts with the same header row. The columns come in this order:

  • date, with export_aggregation DATE only. For WEEKLY and MONTHLY it is the Monday or the first of the month.
  • One column per requested breakdown, in the order List breakdowns gives the keys.
  • campaign_name at the platform and campaign levels; adset_name as well at adset; ad_name as well at ad. Each is followed by its _id column with include_ids. aggregate_data drops them all.
  • kind and platform, with include_kind_and_platform.
  • status, unless aggregate_data is set.
  • accounting_mode, attribution_model and attribution_window.
  • The metrics, in request order, headed by their labels or column names.

Each requested model and window gets its own lines: an Accrual line per window, and a Cash line with the lifetime window. The file names models by their names, such as Linear, and modes as Accrual performance and Cash snapshot.

Lines that sum several rows#

Most lines add up several stored rows. A line covers every row that shares its columns, so leaving out a breakdown, the ids, or kind and platform merges rows, and so do BREAKDOWN aggregation over more than one day, WEEKLY, MONTHLY and aggregate_data. Counts and amounts are summed.

Ratios cannot be summed. These are recomputed from their summed parts: aov, cpo, cpm, cpv, mer, roas, roas_new, roas_returning, rpv. Other ratios, rates and distinct counts (visitors, customers) are empty on such lines and keep their value only on a line built from a single row. Metrics marks which is which.

Revenue depends on the accounting mode#

Accrual rows carry revenue in attributed_revenue (metric revAttributed). Cash rows carry it in revenue (metric rev). Each column is empty in the other mode, so ask for the one that matches your accounting_modes, or both. roas and aov use the right one for each row.

Warnings#

The request still succeeds in these cases, and the result's warn.messages explains each:

  • a model or window that is switched off for the brand;
  • metrics that carry no data and export as empty columns;
  • a breakdown with an empty values list, which matches no rows.

Questions about the API: support@growthdept.ai.