Request and Download Reports

Once your org is set up and at least one advertiser has shared an ad account with the Data Analyst role assigned (see Onboarding), use this flow whenever you need data. The MMM API is asynchronous: submit a report request, poll for completion, then download the file. All requests use the base URL https://adsapi.snapchat.com.

Step 1: Get a valid access token

An access_token is valid for 3600 seconds. If it's expired, get a new one with your refresh_token:

curl -X POST \
  -d "grant_type=refresh_token" \
  -d "refresh_token={refresh_token}" \
  -d "client_id={client_id}" \
  -d "client_secret={client_secret}" \
  https://accounts.snapchat.com/login/oauth2/access_token

Step 2: Enumerate your shared ad accounts

curl "https://adsapi.snapchat.com/v1/me/source_organizations?shared_entity_type=ad_account" \
  -H "Authorization: Bearer {access_token}"

The response lists each advertiser organization and the ad accounts it has shared with you, along with the roles your org holds on each account. If an account you expect is missing, no member of your org has been assigned a role on it yet. Return to Onboarding, Step 3.

Step 3: Submit a report request

Send one request per ad account.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "ad_account_id": "{ad_account_id}",
    "time_dimension": "weekEndingSat",
    "start_date": "2025-01-01",
    "end_date": "2026-01-01",
    "geo_dimension": "COUNTRY"
  }' \
  https://adsapi.snapchat.com/v1/mmm/reports

Parameter	Required	Values
ad_account_id	Yes	One account per request
time_dimension	Yes	Day, weekEndingSat, weekEndingSun, month
start_date / end_date	Yes	YYYY-MM-DD; end_date is inclusive
geo_dimension	No	COUNTRY (default), REGION, DMA
format	No	CSV (default) or JSON

Response:

{
  "request_status": "SUCCESS",
  "request_id": "...",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "MMM_REPORT:acc-abc123:...",
        "async_status": "STARTED"
      }
    }
  ]
}

Step 4: Poll for status

curl "https://adsapi.snapchat.com/v1/mmm/reports/{report_run_id}" \
  -H "Authorization: Bearer {access_token}"

async_status	Meaning
STARTED	Report is queued and waiting to process. Poll again.
RUNNING	Report is still processing. Poll again.
COMPLETED	Download URL is ready; valid for approximately 7 days.
FAILED	Check the error message in the response.

Completed response:

{
  "request_status": "SUCCESS",
  "request_id": "...",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "MMM_REPORT:acc-abc123:...",
        "async_status": "COMPLETED",
        "result": "https://data-transfer.snapads.com/<signed-path>"
      }
    }
  ]
}

Step 5: Download the report

Send a GET request to the result URL directly (no Authorization header needed). The response body is a CSV or JSON file, depending on the format you requested. The link expires after approximately 7 days; if it expires, re-poll the report_run_id to get a fresh one.

Limits

• Earliest start_date: 2023-01-01. This floor moves forward over time; there's no maximum lookback window.

For the full set of columns returned, see Report schema.