Measurement

Measurement endpoints provides stats data that is updated approximately every 15 minutes.

All stats requests can be made with TOTAL, DAY, or HOUR granularity.

Request/Response Pattern

Stats endpoints have a consistent request and response pattern.

Request Pattern

Pattern:

GET /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}/stats

Example:

GET /v1/campaigns/ff869d1f-0923-4d28-8577-4c36291f0fca/stats

Response Pattern - TOTAL Granularity

Response pattern for TOTAL Granularity requests

{
  "request_status": "success",
  "request_id": "57ad1ad600076e58fa35e192",
  "total_stats": [
    {
      "sub_request_status": "success",
      "total_stat": {
        "id": "7057e31f-b908-4bc7-85dd-88169f53e08d",
        "type": "CAMPAIGN",
        "granularity": "TOTAL",
        "stats": {
          "impressions": 0,
          "swipes": 0,
          "spend": 0,
          "quartile_1": 0,
          "quartile_2": 0,
          "quartile_3": 0,
          "view_completion": 0,
          "screen_time_millis": 0
        }
      }
    }
  ]
}

Response Pattern - DAY Granularity

Response pattern for DAY Granularity requests

{
  "request_status": "success",
  "request_id": "57ad240f000756e8d435a6cd",
  "timeseries_stats": [
    {
      "sub_request_status": "success",
      "timeseries_stat": {
        "id": "7057e31f-b908-4bc7-85dd-88169f53e08d",
        "type": "CAMPAIGN",
        "granularity": "DAY",
        "start_time": "2016-08-05T22:00:00.000-07:00",
        "end_time": "2016-08-07T22:00:00.000-07:00",
        "timeseries": [
          {
            "start_time": "2016-08-05T22:00:00.000-07:00",
            "end_time": "2016-08-06T22:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "quartile_1": 0,
              "quartile_2": 0,
              "quartile_3": 0,
              "view_completion": 0,
              "screen_time_millis": 0
            }
          },
          {
            "start_time": "2016-08-06T22:00:00.000-07:00",
            "end_time": "2016-08-07T22:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "quartile_1": 0,
              "quartile_2": 0,
              "quartile_3": 0,
              "view_completion": 0,
              "screen_time_millis": 0
            }
          }
        ]
      }
    }
  ]
}

Response Pattern - HOUR Granularity

Response pattern for HOUR Granularity requests

{
  "request_status": "success",
  "request_id": "57ad245a000e3c88bc33ea4e",
  "timeseries_stats": [
    {
      "sub_request_status": "success",
      "timeseries_stat": {
        "id": "7057e31f-b908-4bc7-85dd-88169f53e08d",
        "type": "CAMPAIGN",
        "granularity": "HOUR",
        "start_time": "2016-08-05T18:00:00.000-07:00",
        "end_time": "2016-08-06T18:00:00.000-07:00",
        "timeseries": [
          {
            "start_time": "2016-08-05T18:00:00.000-07:00",
            "end_time": "2016-08-05T19:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "quartile_1": 0,
              "quartile_2": 0,
              "quartile_3": 0,
              "view_completion": 0,
              "screen_time_millis": 0
            }
          },
          {
            "start_time": "2016-08-05T19:00:00.000-07:00",
            "end_time": "2016-08-05T20:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "quartile_1": 0,
              "quartile_2": 0,
              "quartile_3": 0,
              "view_completion": 0,
              "screen_time_millis": 0
            }
          }
          ....
          {
            "start_time": "2016-08-06T16:00:00.000-07:00",
            "end_time": "2016-08-06T17:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "quartile_1": 0,
              "quartile_2": 0,
              "quartile_3": 0,
              "view_completion": 0,
              "screen_time_millis": 0
            }
          },
          {
            "start_time": "2016-08-06T17:00:00.000-07:00",
            "end_time": "2016-08-06T18:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "quartile_1": 0,
              "quartile_2": 0,
              "quartile_3": 0,
              "view_completion": 0,
              "screen_time_millis": 0
            }
          }
        ]
      }
    }
  ]
}

Request Parameters

Attribute	Description	Required	Possible Values
breakdown	Object-level breakdown	O	ad, adsquad [Only available on Campaign Stats endpoint], campaign [Only available on Ad Account Stats endpoint]
async	Designates processing of report to be asynchronous	O	true
async_format	Designates the response format of asynchronous reporting, can be either a csv or excel file	O	csv, excel
fields	Metrics requested (comma-separated)	O	(see table below; default: impressions,spend)
end_time	End Time (ISO 8601)	R*
start_time	Start Time (ISO 8601)	R*
granularity	Metrics granularity	R	TOTAL, DAY, HOUR, LIFETIME
test	Return Sample (fake) Stats	O	false (default), true
dimension	Insight-level breakdown	O	GEO, DEMO, INTEREST, DEVICE
pivot	The pivot to be used for insights breakdown	O	country, region, dma, gender, age_bucket, interest_category_id, interest_category_name, operating_system, make, model
action_report_time	Specifies the principle for conversion reporting	O	conversion (default), impression**
swipe_up_attribution_window	Attribution window for swipe ups	O	1_DAY, 7_DAY, 28_DAY (default)
view_attribution_window	Attribution window for views	O	none, 1_HOUR, 3_HOUR, 6_HOUR, 1_DAY (default), 7_DAY, 28_DAY***
position_stats	Position metric breakdown for Snap Ads within a Story Ad	O	true
omit_empty	Omits records with zero data for all metrics for a given date/entity. If there is data for any metric for a given date/entity, all metrics for that date/entity are returned	O	false (default), true
conversion_source_types	Conversion source breakout by platform	O	web, app, offline**, total, total_off_platform, total_on_platform
limit	The limit parameter specifies how many entities should be returned per page	O	integer, max 200

* start_time and end_time are required for DAY and HOUR granularity and they must be set to the start of an hour (e.g. 22:00 not 22:45)
** offline conversion data source ( conversion_source_types=offline ) and impression based conversions
** action_report_time=impression** ) are available from 1 May 2020 onwards
*** 28_DAY view_attribution_window is deprecated, legacy data is available up until 1 March 2021

Response Parameters & Finalization

Attribute	Description
finalized_data_end_time	This attribute defines the time up until when non-conversion reporting metrics are finalized. You can query for all metrics before this time including uniques and reach and they will have the final numbers. For any time after the finalized_data_end_time the metrics are still undergoing de-duplication and finalization and may change accordingly.
conversion_data_processed_end_time	This attribute defines the time up until when conversion metrics are finalized, for any time after the conversion_data_processed_end_time the conversion metrics are still undergoing processing and may change accordingly. Note that this attribute only covers conversion by time of conversion.
paging	If you are using pagination the paging attribute will contain a next_link attribute which holds the API call to fetch the next page.

Pagination

For calls that fetch stats for many entities we recommend that you use pagination. The limit parameter specifies how many entities should be returned per page. The maximum pagination limit is 200.

The returned result will contain a paging attribute, this in turn holds a next_link attribute which holds the API call to fetch the next page. Paginated calls are rdered by time of creation, non-paginated calls are unsorted.

Core Metrics

The following metrics are available for all Snap Ads.

Field Name	Description
impressions	Impression Count
swipes	Swipe-Up Count
view_time_millis	Use screen_time_millis instead. Total Time Spent on top Snap Ad (milliseconds)
screen_time_millis	Total Time Spent on top Snap Ad (milliseconds)
quartile_1	Video Views to 25%
quartile_2	Video Views to 50%
quartile_3	Video Views to 75%
view_completion	Video Views to completion
spend	Amount Spent (micro-currency)
coupon_used_local	Amount Spent via Coupon in the assigned currency of Ad Account (micro-currency)
coupon_used_usd	Amount Spent via Coupon in USD (micro-currency)
video_views	The total number of impressions that meet the qualifying video view criteria of at least 2 seconds of consecutive watch time or a swipe up action on the Top Snap

Micro-currency conversion: 1.00 local currency unit = 1000000 Micro-currency. See Monetary Values for details.

IMPORTANT: Metrics are finalized 48 hours after the end of the day in the timezone set by the Ad Account .

Asynchronous reporting requests

Large reporting requests may time out or return errors, these requests are suitable to be executed using the asynchronous mode. The format of an asynchronous report can be defined either as a comma separated file (CSV) or an Excel spreadsheet.

Requests marked as asynchronous will produce a report_run_id which is needed to check the status of a report, and to retrieve a report, once a report is ready the response body will contain a download url for the finished report.

Generating an async report

The first step to generate an asynchronous report is the creation, this request needs to include the async parameter.

HTTP Requests

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats
GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/stats
GET https://adsapi.snapchat.com/v1/adsquads/{adsquad_id}/stats
GET https://adsapi.snapchat.com/v1/ads/{ad_id}/stats

Parameters for creating an asynchronous report

The below listed parameters are specific for asynchronous reporting, aside from these parameters all request parameters are supported. The asynchronous creation will return a report_run_id which is needed to fetch the report.

Regular reporting restrictions still apply for async reporting;

• When the DAY granularity is used start_time and end_time are required values, the start_time and end_time must be the daily boundry for the timezone of the Ad Account in question
• When start_time and end_time is not defined in combination with granularity TOTAL it is treated the same as granularity LIFETIME

Parameter	Description	Required	Possible values
async	Designates processing of report to be asynchronous	R	true
async_format	Designates the response format of asynchronous reporting, can be either a csv or excel file	O	csv (default), excel
granularity	Metrics granularity	O	TOTAL, DAY, LIFETIME

Example - Step 1 Generating an async report

This request produces a report_run_id and the async_status returned is STARTED.

curl "https://adsapi.snapchat.com/v1/adaccounts/ce943c3b-2404-4fff-acb1-259b7b052f27/stats?breakdown=ad&granularity=DAY&view_attribution_window=1_DAY&async=true&omit_empty=true&fields=impressions,total_installs,spend,swipes,attachment_video_views,story_opens,story_completes,shares,saves,conversion_purchases,conversion_purchases_value,conversion_save,conversion_start_checkout,conversion_add_cart,conversion_view_content,conversion_add_billing,conversion_sign_ups,conversion_searches,conversion_level_completes,conversion_app_opens,conversion_page_views&start_time=2024-10-01T00:00:00&end_time=2024-10-08T00:00:00&swipe_up_attribution_window=28_DAY" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "acfacd19-bd51-4822-a9d3-e503a523d25f",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:ce943c3b-2404-4fff-acb1-259b7b052f27:1727755200000:7245f6e6-eda4-4650-9255-6e3ab38b95ce",
        "async_status": "STARTED"
      }
    }
  ]
}

Checking the status of an asynchronous report

The second step of asynchronus reporting is checking the status of the report and fetching the download url of the finished report, this request requires the report_run_id value returned in the previous request.

HTTP Requests

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats_report
GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/stats_report
GET https://adsapi.snapchat.com/v1/adsquads/{adsquad_id}/stats_report
GET https://adsapi.snapchat.com/v1/ads/{ad_id}/stats_report

Parameters for checking asynchronous reporting

When checking asynchronous reporting requests the

Parameter	Description	Required	Possible values
report_run_id	The id of the report to be fetched	R

Example - Step 2 Checking the status of an async report - Report is processing

This request requires the report_run_id and the async_status returned is RUNNING which indicates that the report is still processing.

curl "https://adsapi.snapchat.com/v1/adaccounts/ce943c3b-2404-4fff-acb1-259b7b052f27/stats_report?report_run_id=ASYNC_STATS:6b78bf3c-b7f4-4fcf-b74a-a5aaa91b15ef:1726804800000:7139d12c-910e-4e09-b3fd-a01f82b3af56" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "f8a5b7b0-14b4-950c-934f-7b746745e571",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:6b78bf3c-b7f4-4fcf-b74a-a5aaa91b15ef:1726804800000:7139d12c-910e-4e09-b3fd-a01f82b3af56",
        "async_status": "RUNNING"
      }
    }
  ]
}

Example - Step 2 Checking the status of an async report - Report is completed

This request requires the report_run_id and the async_status returned is COMPLETED, the url of the report is found in the result attribute.

curl "https://adsapi.snapchat.com/v1/adaccounts/ce943c3b-2404-4fff-acb1-259b7b052f27/stats_report?report_run_id=ASYNC_STATS:6b78bf3c-b7f4-4fcf-b74a-a5aaa91b15ef:1726804800000:7139d12c-910e-4e09-b3fd-a01f82b3af56" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "f8a5b7b0-14b4-950c-934f-7b746745e571",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:6b78bf3c-b7f4-4fcf-b74a-a5aaa91b15ef:1726804800000:7139d12c-910e-4e09-b3fd-a01f82b3af56",
        "async_status": "COMPLETED",
        "result": "https://data-transfer.snapads.com/async-report/snap_ads/ASYNC_STATS:6b78bf3c-b7f4-4fcf-b74a-a5aaa91b15ef:1726804800000:7139d12c-990e-4e09-b3fd-a01f82b3af56/9496dff0-07b9-44d8-8f0b-b44eb276cc9e.xlsx"
      }
    }
  ]
}

Reach Overlap Reporting

Reach overlap reporting via async reporting is available for Campaigns, Ad Squads and Ads using the Snapchat Marketing API.

The entities for which the calculation is made must belong to the same Ad Account, overlap reporting across different Ad Accounts is not possible. If an entity has no metrics for the given reporting period (start_time / end_time), it will be excluded from the resulting report.

HTTP Request

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats?overlap=true&overlap_type={campaign/ad_squad/ad}&ids={entity1_id,entity_id,...},{entity2_id}&start_time={start_time}&end_time={end_time}&async_format={csv/excel}

Request Parameters

Attribute	Description	Possible values
async_format	Defines the returned format of the report	csv,excel
ids	Two or more Campaign/Ad Squad/Ad entities to calculate the reach overlap for, these have to be the same type of entities and live within the same Ad Account	Comma separated string of up to 100 Campaign ID/Ad Squad ID/Ad ID values
overlap	Indicates whether an overlap calculation should take place	true
overlap_type	Specifies the entity level of the overlap calculation, you cannot use two different types of entities in one report	campaign, ad_squad, ad
start_time	Start time of the report	Start time in ISO format
end_time	End time of the report	End time in ISO format

Example Request

This request generates an async process to create an overlap report in Excel format for two Campaigns in the same Ad Account, for the time period 1-30 April 2024.

curl 'https://adsapi.snapchat.com/v1/adaccounts/62f51caa-394c-4f88-905c-71a9859f2b54/stats?overlap=true&overlap_type=campaign&ids=11f5bc01-22a4-469e-ba7e-d4c7edc5ef88%2C50984a9d-1b2e-4d5d-857e-5ac9d3665506%2C54f10e2d-55a8-4924-896d-5a94fba1a0c9&start_time=2024-04-01T07%3A00%3A00.000Z&end_time=2024-04-30T07%3A00%3A00.000Z&async_format=excel' \
-H "Authorization: Bearer meowmeowmeow"

Response

{
  "request_status": "SUCCESS",
  "request_id": "f5cdc549-f3f3-4aed-9e39-68216ba70be3",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:62f51caa-394c-4f88-905c-71a9859f2b54:1711954800000:f591f1c1-581e-477b-892f-7b8b5365b0e7",
        "async_status": "STARTED"
      }
    }
  ]
}

Once the async process for an overlap report is initiated using the above request, follow the steps in Checking the status of an asynchronous report to check the status and fetch the download url of a completed report.

Report Format

Below is an example of a Reach Overlap report downloaded in excel format. This resulting report includes metrics for reach and uniques, showing the overlap for the requested entities. The requested entities in this example are two campaigns - Wellness Campaign and Beauty Campaign.

The report starts with Reached by all, which is the Reach Overlap for all the entities that were included in the report.

Example

• Row 1 shows the Reach Overlap for all the Campaigns in the report.

The report also accounts for the Total Uniques for all the entities in the report.

Example

• Row 2 shows the Total Uniques reached by all campaigns in the report.

If Campaign Id 1 and Campaign Id 2 are the same, it means the metric is just for that campaign.

Example

• Row 4 below shows the total Reach of the Wellness Campaign
• Row 6 below shows the total Uniques of the Wellness Campaign
• Row 7 below shows the total Reach of the Beauty Campaign
• Row 9 below shows the total Uniques of the Beauty Campaign

If Campaign Id 1 and Campaign Id 2 are different it shows an overlap calculation between the two campaigns.

Example

• Row 5 and Row 8 shows the Reach Overlap of the Wellness Campaign and the Beauty Campaign.

	A	B	C	D	E	F
1	Reached by all	6,029
2	Total Uniques Reached	212,351
3	Campaign Id 1	Campaign Name 1	Campaign Id 2	Campaign Name 2	Reach Type	Reach Value
4	11111111-1111-1111-111111111111	Wellness Campaign	11111111-1111-1111-111111111111	Wellness Campaign	Total	160.356
5	11111111-1111-1111-111111111111	Wellness Campaign	222222222-2222-2222-2222-2222222222	Beauty Campaign	Overlap	6,029
6	11111111-1111-1111-111111111111	Wellness Campaign	11111111-1111-1111-111111111111	Wellness Campaign	Unique	154,327
7	222222222-2222-2222-2222-2222222222	Beauty Campaign	222222222-2222-2222-2222-2222222222	Beauty Campaign	Total	60,746
8	222222222-2222-2222-2222-2222222222	Beauty Campaign	11111111-1111-1111-111111111111	Wellness Campaign	Overlap	6,029
9	222222222-2222-2222-2222-2222222222	Beauty Campaign	222222222-2222-2222-2222-2222222222	Beauty Campaign	Unique	54,717

Additional Metrics

See the Metrics and supported granularities table for a breakdown of the reporting granularities available per Ad type. For LIFETIME granularity the data is only accessible as finalized data, available after 48-72 hours.

Field Name	Snap Ad Types	Description
android_installs	APP_INSTALL	# of Android App Installs
attachment_avg_view_time_millis	Any Attachment	Average Attachment View Time (milli-seconds)
attachment_frequency	Any Attachment	Average # of Attachment Views per User Reached
attachment_quartile_1	LONGFORM_VIDEO	Long Form Video Views to 25%
attachment_quartile_2	LONGFORM_VIDEO	Long Form Video Views to 50%
attachment_quartile_3	LONGFORM_VIDEO	Long Form Video Views to 75%
attachment_total_view_time_millis	Any Attachment	Total Attachment View Time (milli-seconds)
attachment_uniques	Any Attachment	# of unique attachment impressions
attachment_view_completion	LONGFORM_VIDEO	Long Form Video Views to completion
attachment_video_views	LONGFORM_VIDEO	Long Form Video Attachment Views, viewed for at least 10 consecutive seconds or reached 97% of the Long Form Video duration
avg_view_time_millis	Any	Use avg_screen_time_millis instead. Average Top Snap view time per User Reached
avg_screen_time_millis	Any	Average Top Snap view time across all impressions
frequency	Any	Average # of Impressions per User Reached
ios_installs	APP_INSTALL	# of iOS App Installs
swipe_up_percent	Any Attachment	% of Impressions that Swiped-Up
total_installs	APP_INSTALL	Total # of App Installs
uniques	Any	# of unique impressions
video_views_time_based	Any	The total number of impressions that meet the qualifying video view criteria of at least 2 seconds, not including swipe ups
video_views_5s*	Any	The total number of impressions that meet the qualifying video view criteria of at least 5 seconds, or a swipe up action on the ad
video_views_15s	Any	The total number of impressions that meet the qualifying video view criteria of at least 15 seconds, or 97% completion if it's shorter than 15 seconds, or a swipe up action on the ad
story_opens	STORY	# of times users tapped on the ad tile in the feed to view the Story Ad
story_completes	STORY	# of times users viewed through to the last Snap of your Story Ad
landing_page_views		# of times a Snapchatter has loaded the ad’s landing page after a click page
profile_clicks	Any	# of times users tapped the logo in the upper corner taking them to the profile page
position_impressions	STORY	# the impression number for this story ad position
position_screen_time_millis	STORY	# the total view time in milliseconds for this story ad position
position_swipe_up_percent	STORY	# the swipe up rate for this story ad position
avg_position_screen_time_millis	STORY	# the average view time for this story ad position
shares	LENS, AD_TO_LENS, FILTER	# of times lens/filter was shared in a Chat or Story
saves	LENS, AD_TO_LENS, FILTER	# of times lens/filter was saved to Memories
paid_impressions	LENS, FILTER, AD_TO_LENS	The total number of times your ad was served to a Snapchatter. Tracked when the ad fully renders on a device for the first time during a Snapchatter’s viewing session
earned_impressions	LENS, FILTER, AD_TO_LENS	The number of times your ad was viewed after being shared by a Snapchatter via Chat or Stories
total_impressions	LENS	The total number of impressions (Paid and Earned)
play_time_millis	LENS	The total amount of time in where Snapchatters interacted with your Lens in the camera (milliseconds)
total_reach	LENS	The number of unique Snapchatters who viewed your Lens ad, either by receiving a Paid or Earned Impression.
earned_reach	LENS, FILTER, AD_TO_LENS	The number of unique Snapchatters who viewed the filter/lens after being shared by a Snapchatter via Chat or Stories
native_leads	LEAD_GENERATION	Total number of Snapchat users that swipe up, fill out the required fields, and hit ‘Submit’ on Lead Form attachments. If a user swipes down or cancels before hitting 'Submit,' this action is not counted

*video_views_5s are available from 11 March 2025 onwards

Micro-currency conversion: 1.00 local currency unit = 1000000 Micro-currency. See Monetary Values for details.

Apple Transparent Tracking (ATT) Reporting

All the users whose activity is tracked using the attribution and measurement services will be split into two categories. Please note that only conversion metrics are affected by the ATT updates.

User Category	Description	User groups in category
Fully Tracked group	These user groups are fully supported for the features listed below.	Android, iOS opted-in users
Partially tracked group	These user groups are partially supported.	Snap Pixel, iOS opted out users and users reported via Conversions API

Below is the list of all the reporting fields and API fields that are affected for each group.

Dimension/Granularity	Conversion Sources
	Fully Tracked Group - Android (in-app), iOS (opt-in)	Partially tracked Group - Snap Pixel, iOS (opt-out), Conversion API
Time of Conversion action_report_time=conversion	Supported	Supported
Time of Exposure action_report_time=impression	Supported	Supported
Event Source (web/app/offline)	Supported	Supported
Entity (campaign/ad set/ad)	Supported	Supported
Age	Supported	Supported
Gender	Supported	Supported
Age, Gender	Supported	Supported
Country	Supported	Supported
OS	Supported	Supported
Platform (on/off snapchat)	Supported	Supported
Region (US Only)	Supported	NOT Supported
DMA (US Only)	Supported	NOT Supported
Device Make	Supported	NOT Supported
SLC (lifestyle category)	Supported	NOT Supported
Product	Supported	NOT Supported
Hourly Conversions	Supported	NOT Supported
Daily, Total, Lifetime Conversion	Supported	Supported
Swipe Up Window: 1_DAY, 7_DAY, 28_DAY View Thru Window: 1_DAY, 7_DAY	Supported	Supported
View Through Window: 1_HOUR, 3_HOUR, 6_HOUR	Supported	Supported
View Through Window: 28_DAY*	NOT Supported	NOT Supported

Please Note:

• The View Through Window value of 28_DAY is now effectively deprecated.

• Any legacy data for these users will continue to be returned.

*This field is now effectively deprecated.

SKAd Network Reporting

Due to the attribution methodology of Apple’s SKAdNetwork there are some limitations when fetching reporting for Ad serving entities that are opted into SKAdNetwork tracking.

• SKAdNetwork conversions reported at the Ad level or below may be modeled based on first party ad engagement signals using statistical methods. Modeling is only applied at the ad level. Please note that you should still take a patient approach to testing and optimization decisions including: waiting 48+ hours before adjusting Bids and Budgets, and starting with high Bids and Budgets to pass privacy thresholds. If you do not, you run the risk of prematurely pausing Ad creatives that may lead to strong performance.

• The available granularities are DAY, TOTAL, and LIFETIME, HOUR granularity is not available.

• The conversion window for a SKAd Network SWIPE (click) conversion is 30 day based on the time of conversion, all ad types support SWIPE conversions.

• The conversion window for a SKAd Network VIEW conversion is 24 hours based on the time of conversion. A VIEW is defined as 3 seconds in length.

• The ad types that currently support the VIEW conversion are; SNAP_AD, LONGFORM_VIDEO, APP_INSTALL, REMOTE_WEBPAGE, DEEP_LINK, COLLECTION

• Reporting Insights are not available for SKAdNetwork metrics, the use of report_dimension is not possible.

SKAd Network Conversion Metrics

Conversion metrics for the SKAd Network are broken out by Swipe conversions, View conversions, and the total number of conversions.

SKAd Network Swipe Conversion Metrics

The following metrics return the SKAd Network SWIPE (click) conversions.

Name	Description
conversion_total_installs_sk_ad_network	Total App Installs tracked via SKAd Network
conversion_ios_installs_sk_ad_network	Exact same metric as conversion_total_installs_sk_ad_network
conversion_purchases_sk_ad_network
conversion_save_sk_ad_network
conversion_start_checkout_sk_ad_network
conversion_add_cart_sk_ad_network
conversion_view_content_sk_ad_network
conversion_add_billing_sk_ad_network
conversion_sign_ups_sk_ad_network
conversion_searches_sk_ad_network
conversion_level_completes_sk_ad_network
conversion_app_opens_sk_ad_network
conversion_page_views_sk_ad_network
conversion_subscribe_sk_ad_network
conversion_ad_click_sk_ad_network
conversion_ad_view_sk_ad_network
conversion_complete_tutorial_sk_ad_network
conversion_invite_sk_ad_network
conversion_login_sk_ad_network
conversion_share_sk_ad_network
conversion_reserve_sk_ad_network
conversion_achievement_unlocked_sk_ad_network
conversion_add_to_wishlist_sk_ad_network
conversion_spend_credits_sk_ad_network
conversion_rate_sk_ad_network
conversion_start_trial_sk_ad_network
conversion_list_view_sk_ad_network
conversion_visitation_sk_ad_network
custom_event_1_sk_ad_network
custom_event_2_sk_ad_network
custom_event_3_sk_ad_network
custom_event_4_sk_ad_network
custom_event_5_sk_ad_network
unknown_sk_ad_network	SkAdNetwork conversion events with unknown Conversion Values
conversion_assist_install_sk_ad_network	The number of times the SKAdNetwork campaign drove an App Install, but was not the last touch before the App Install occurred. conversion_null_sk_ad_network
conversion_null_sk_ad_network	The number of SKAdNetwork conversion events with "null" Conversion Values. This indicates the campaign did not generate enough daily SKAdNetwork conversions to pass Apple’s privacy threshold.

SKAd Network View Conversion Metrics

The following metrics return the SKAd Network VIEW conversions.

Name	Description
conversion_total_installs_sk_ad_network_view	Total App Installs tracked via SKAd Network
conversion_ios_installs_sk_ad_network_view	Exact same metric as conversion_total_installs_sk_ad_network_view
conversion_purchases_sk_ad_network_view
conversion_save_sk_ad_network_view
conversion_start_checkout_sk_ad_network_view
conversion_add_cart_sk_ad_network_view
conversion_view_content_sk_ad_network_view
conversion_add_billing_sk_ad_network_view
conversion_sign_ups_sk_ad_network_view
conversion_searches_sk_ad_network_view
conversion_level_completes_sk_ad_network_view
conversion_app_opens_sk_ad_network_view
conversion_page_views_sk_ad_network_view
conversion_subscribe_sk_ad_network_view
conversion_ad_click_sk_ad_network_view
conversion_ad_view_sk_ad_network_view
conversion_complete_tutorial_sk_ad_network_view
conversion_invite_sk_ad_network_view
conversion_login_sk_ad_network_view
conversion_share_sk_ad_network_view
conversion_reserve_sk_ad_network_view
conversion_achievement_unlocked_sk_ad_network_view
conversion_add_to_wishlist_sk_ad_network_view
conversion_spend_credits_sk_ad_network_view
conversion_rate_sk_ad_network_view
conversion_start_trial_sk_ad_network_view
conversion_list_view_sk_ad_network_view
conversion_visitation_sk_ad_network_view
custom_event_1_sk_ad_network_view
custom_event_2_sk_ad_network_view
custom_event_3_sk_ad_network_view
custom_event_4_sk_ad_network_view
custom_event_5_sk_ad_network_view
unknown_sk_ad_network_view	SkAdNetwork conversion events with unknown Conversion Values
conversion_assist_install_sk_ad_network_view	The number of times the SKAdNetwork campaign drove an App Install, but was not the last touch before the App Install occurred
conversion_null_sk_ad_network_view	The number of SKAdNetwork conversion events with "null" Conversion Values. This indicates the campaign did not generate enough daily SKAdNetwork conversions to pass Apple’s privacy threshold

SKAd Network Total Conversion Metrics

The following metrics return the total sum of the SKAd Network SWIPE and VIEW conversions.

Name	Description
conversion_total_installs_sk_ad_network_total	Total App Installs tracked via SKAd Network
conversion_ios_installs_sk_ad_network_total	Exact same metric as conversion_total_installs_sk_ad_network_total
conversion_purchases_sk_ad_network_total
conversion_save_sk_ad_network_total
conversion_start_checkout_sk_ad_network_total
conversion_add_cart_sk_ad_network_total
conversion_view_content_sk_ad_network_total
conversion_add_billing_sk_ad_network_total
conversion_sign_ups_sk_ad_network_total
conversion_searches_sk_ad_network_total
conversion_level_completes_sk_ad_network_total
conversion_app_opens_sk_ad_network_total
conversion_page_views_sk_ad_network_total
conversion_subscribe_sk_ad_network_total
conversion_ad_click_sk_ad_network_total
conversion_ad_view_sk_ad_network_total
conversion_complete_tutorial_sk_ad_network_total
conversion_invite_sk_ad_network_total
conversion_login_sk_ad_network_total
conversion_share_sk_ad_network_total
conversion_reserve_sk_ad_network_total
conversion_achievement_unlocked_sk_ad_network_total
conversion_add_to_wishlist_sk_ad_network_total
conversion_spend_credits_sk_ad_network_total
conversion_rate_sk_ad_network_total
conversion_start_trial_sk_ad_network_total
conversion_list_view_sk_ad_network_total
conversion_visitation_sk_ad_network_total
custom_event_1_sk_ad_network_total
custom_event_2_sk_ad_network_total
custom_event_3_sk_ad_network_total
custom_event_4_sk_ad_network_total
custom_event_5_sk_ad_network_total
unknown_sk_ad_network_total	SkAdNetwork conversion events with unknown Conversion Values
conversion_assist_install_sk_ad_network_total	The number of times the SKAdNetwork campaign drove an App Install, but was not the last touch before the App Install occurred. conversion_null_sk_ad_network
conversion_null_sk_ad_network_total	The number of SKAdNetwork conversion events with "null" Conversion Values. This indicates the campaign did not generate enough daily SKAdNetwork conversions to pass Apple’s privacy threshold

SKAd Network Conversion Example

curl "https://adsapi.snapchat.com/v1/campaigns/5b483328-dfab-4321-be60-8ad2dfd63d35/stats?granularity=TOTAL&start_time=2021-01-21T00:00:00.000&end_time=2021-01-25T00:00:00.000&fields=impressions,spend,swipes,conversion_total_installs_sk_ad_network,conversion_purchases_sk_ad_network,conversion_add_cart_sk_ad_network"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "601d83ee00ff06ea9762c9c4f20001737e616473617069736300016275696c642d31323762373738342d312d3432302d3000010161",
  "total_stats": [
    {
      "sub_request_status": "SUCCESS",
      "total_stat": {
        "id": "5b483328-dfab-4321-be60-8ad2dfd63d35",
        "type": "CAMPAIGN",
        "granularity": "TOTAL",
        "stats": {
          "impressions": 61295,
          "swipes": 4528,
          "spend": 407129814,
          "conversion_total_installs_sk_ad_network": 1199,
          "conversion_purchases_sk_ad_network": 6637,
          "conversion_add_cart_sk_ad_network": 7212
        },
        "start_time": "2021-01-20T16:00:00.000-08:00",
        "end_time": "2021-01-24T16:00:00.000-08:00",
        "finalized_data_end_time": "2021-02-05T03:00:00.000-08:00"
      }
    }
  ]
}

This example fetches three specific SKAd Network conversion metrics.

Conversion Reporting

The action_report_time parameter specifies the timing to use when requesting conversion reporting. Passing the value conversion will return conversions based on the time the user triggered the conversion event, passing the value impression will return conversions based on the time the ad impression took place.

Reporting for conversions based on ad impression (action_report_time=impression), are available from 1st May 2020 onwards.

Conversion Event Stats

The following conversion event metrics are available for ads that have been setup to track conversions through Snap Pixel.

Fields	Granularity	Description
conversion_purchases	Any	# of attributed "PURCHASE" conversion events
conversion_purchases_value	Any	Value of attributed "PURCHASE" conversion events (microcurrency in Ad Account's currency)
conversion_save	Any	# of attributed "SAVE" conversion events
conversion_save_value	Any	Value of attributed "SAVE" conversion events (microcurrency in Ad Account's currency)
conversion_start_checkout	Any	# of attributed "START_CHECKOUT" conversion events
conversion_start_checkout_value	Any	Value of attributed "START_CHECKOUT" conversion events (microcurrency in Ad Account's currency)
conversion_add_cart	Any	# of attributed "ADD_CART" conversion events
conversion_add_cart_value	Any	Value of attributed "ADD_CART" conversion events (microcurrency in Ad Account's currency)
conversion_view_content	Any	# of attributed "VIEW_CONTENT" conversion events
conversion_view_content_value	Any	Value of attributed "VIEW_CONTENT" conversion events (microcurrency in Ad Account's currency)
conversion_add_billing	Any	# of attributed "ADD_BILLING" conversion events
conversion_add_billing_value	Any	Value of attributed "ADD_BILLING" conversion events (microcurrency in Ad Account's currency)
conversion_sign_ups	Any	# of attributed "SIGN_UP" conversion events
conversion_sign_ups_value	Any	Value of attributed "SIGN_UP" conversion events (microcurrency in Ad Account's currency)
conversion_searches	Any	# of attributed "SEARCH" conversion events
conversion_searches_value	Any	Value of attributed "SEARCH" conversion events (microcurrency in Ad Account's currency)
conversion_level_completes	Any	# of attributed "LEVEL_COMPLETE" conversion events
conversion_level_completes_value	Any	Value of attributed "LEVEL_COMPLETE" conversion events (microcurrency in Ad Account's currency)
conversion_app_opens	Any	# of attributed "APP_OPEN" conversion events
conversion_app_opens_value	Any	Value of attributed "APP_OPEN" conversion events (microcurrency in Ad Account's currency)
conversion_page_views	Any	# of attributed "PAGE_VIEW" conversion events
conversion_page_views_value	Any	Value of attributed "PAGE_VIEW" conversion events (microcurrency in Ad Account's currency)
conversion_subscribe	Any	# of attributed "SUBSCRIBE" conversion events
conversion_subscribe_value	Any	Value of attributed "SUBSCRIBE" conversion events (microcurrency in Ad Account's currency)
conversion_ad_click	Any	# of attributed "AD_CLICK" conversion events
conversion_ad_click_value	Any	Value of attributed "AD_CLICK" conversion events (microcurrency in Ad Account's currency)
conversion_ad_view	Any	# of attributed "AD_VIEW" conversion events
conversion_ad_view_value	Any	Value of attributed "AD_VIEW" conversion events (microcurrency in Ad Account's currency)
conversion_complete_tutorial	Any	# of attributed "COMPLETE_TUTORIAL" conversion events
conversion_complete_tutorial_value	Any	Value of attributed "COMPLETE_TUTORIAL" conversion events (microcurrency in Ad Account's currency)
conversion_invite	Any	# of attributed "INVITE" conversion events
conversion_invite_value	Any	Value of attributed "INVITE" conversion events (microcurrency in Ad Account's currency)
conversion_login	Any	# of attributed "LOGIN" conversion events
conversion_login_value	Any	Value of attributed "LOGIN" conversion events (microcurrency in Ad Account's currency)
conversion_share	Any	# of attributed "SHARE" conversion events
conversion_share_value	Any	Value of attributed "SHARE" conversion events (microcurrency in Ad Account's currency)
conversion_reserve	Any	# of attributed "RESERVE" conversion events
conversion_reserve_value	Any	Value of attributed "RESERVE" conversion events (microcurrency in Ad Account's currency)
conversion_achievement_unlocked	Any	# of attributed "ACHIEVEMENT_UNLOCKED" conversion events
conversion_achievement_unlocked_value	Any	Value of attributed "ACHIEVEMENT_UNLOCKED" conversion events (microcurrency in Ad Account's currency)
conversion_add_to_wishlist	Any	# of attributed "ADD_TO_WISHLIST" conversion events
conversion_add_to_wishlist_value	Any	Value of attributed "ADD_TO_WISHLIST" conversion events (microcurrency in Ad Account's currency)
conversion_spend_credits	Any	# of attributed "SPENT_CREDITS" conversion events
conversion_spend_credits_value	Any	Value of attributed "SPENT_CREDITS" conversion events (microcurrency in Ad Account's currency)
conversion_rate	Any	# of attributed "RATE" conversion events
conversion_rate_value	Any	Value of attributed "RATE" conversion events (microcurrency in Ad Account's currency)
conversion_start_trial	Any	# of attributed "START_TRIAL" conversion events
conversion_start_trial_value	Any	Value of attributed "START_TRIAL" conversion events (microcurrency in Ad Account's currency)
conversion_list_view	Any	# of attributed "LIST_VIEW" conversion events
conversion_list_view_value	Any	Value of attributed "LIST_VIEW" conversion events (microcurrency in Ad Account's currency)
conversion_visit	Any	# of attributed "VISIT" conversion events
conversion_visit_value	Any	Value of attributed "VISIT" conversion events (microcurrency in Ad Account's currency)
custom_event_1	Any	# of attributed "CUSTOM_EVENT_1" conversion events
custom_event_1_value	Any	Value of attributed "CUSTOM_EVENT_1" conversion events (microcurrency in Ad Account's currency)
custom_event_2	Any	# of attributed "CUSTOM_EVENT_2" conversion events
custom_event_2_value	Any	Value of attributed "CUSTOM_EVENT_2" conversion events (microcurrency in Ad Account's currency)
custom_event_3	Any	# of attributed "CUSTOM_EVENT_3" conversion events
custom_event_3_value	Any	Value of attributed "CUSTOM_EVENT_3" conversion events (microcurrency in Ad Account's currency)
custom_event_4	Any	# of attributed "CUSTOM_EVENT_4" conversion events
custom_event_4_value	Any	Value of attributed "CUSTOM_EVENT_4" conversion events (microcurrency in Ad Account's currency)
custom_event_5	Any	# of attributed "CUSTOM_EVENT_5" conversion events
custom_event_5_value	Any	Value of attributed "CUSTOM_EVENT_5" conversion events (microcurrency in Ad Account's currency)

Custom Conversions

If you are using Custom Conversions, metrics are available using the conversion ID.

Fetch Custom Conversion IDs

Custom conversions are created under the event source that they are reported via, for web events they will be created under the Pixel Entity. To fetch all custom conversions that have been defined under a specific pixel you should use this method.

Pattern:

GET /pixels/{pixel_id}/custom_conversions

Reporting Restrictions

Custom conversions can be requested at all levels (Ad Account, Campaign, Ad Set, Ad), with all parameters and granularities, with the exception of report_dimension (insights), the report_dimension parameter cannot be used with custom conversions.

Example I: Fetch Custom Conversions via event source

Request:

curl https://adsapi.snapchat.com/v1/pixels/82225ba6-7559-4000-9663-bace8adff5f8/custom_conversions
  -H "Authorization: Bearer meowmeowmeow"

Response:

{
  "request_status": "SUCCESS",
  "request_id": "631a177c-5068-475f-ad08-0622243df1e6",
  "paging": {},
  "custom_conversions": [
    {
      "sub_request_status": "SUCCESS",
      "custom_conversion": {
        "id": "0029904941",
        "updated_at": "2023-07-20T21:25:11.550Z",
        "created_at": "2023-07-12T21:58:21.425Z",
        "event_source": {
          "id": "82225ba6-7559-4000-9663-bace8adff5f8",
          "type": "PIXEL"
        },
        "name": "kitten_sales",
        "description": "Recording all kitten purchases",
        "event_type": "PURCHASE",
        "rules": [
          {
            "key": "BRAND",
            "values": ["kitten"],
            "operator": "I_CONTAINS"
          }
        ]
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "custom_conversion": {
        "id": "1828361131",
        "updated_at": "2023-07-18T07:16:28.440Z",
        "created_at": "2023-07-12T21:56:57.705Z",
        "event_source": {
          "id": "82225ba6-7559-4000-9663-bace8adff5f8",
          "type": "PIXEL"
        },
        "name": "european_puppy_sales",
        "description": "Recording country specific Puppy Purchases for Germany/France/Italy",
        "event_type": "PURCHASE",
        "rules": [
          {
            "key": "BRAND",
            "values": ["puppy"],
            "operator": "CONTAINS"
          },
          {
            "key": "EVENT_TAG",
            "values": ["DE", "FR", "IT"],
            "operator": "CONTAINS"
          }
        ]
      }
    }
  ]
}

Once you have the ID value of a custom conversion, you can use it to fetch reporting for the Custom Conversion via the Marketing API. You need to prepend the term conversion_ to the ID of the custom conversion.

Example of how to create the ID for reporting using two custom conversions:

Custom Conversion Name	Custom Conversion ID	ID for reporting
kitten_sales	0029904941	conversion_0029904941
european_puppy_sales	1828361131	conversion_1828361131

The custom conversion IDs would look the following way when used to fetch reporting. This value is passed via the fields parameter.

If you have set up your events in Conversions API v3 to use the contents attribute to pass id, quantity, item_price, and brand for each item sold in the PURCHASE event, you can also fetch reporting on the value of the sales of each Custom Conversion. This is achieved by adding _value to the reporting ID.

Custom Conversion Name	Custom Conversion ID	ID for reporting value
kitten_sales	0029904941	conversion_0029904941_value
european_puppy_sales	1828361131	conversion_1828361131_value

Pattern:

GET /adaccounts/{ad_account_id}/stats

Example II - API reporting request by Campaign

Fetch custom conversions (conversion_0029904941 & conversion_1828361131) broken into Campaign.

Request:

curl "https://adsapi.snapchat.com/v1/adaccounts/52b56e53-2c90-426c-af68-8bc12a472fa1/stats?\
granularity=TOTAL&\
breakdown=campaign&\
fields=impressions,swipes,conversion_0029904941,conversion_0029904941_value,conversion_1828361131,conversion_1828361131_value"
-H "Authorization: Bearer meowmeowmeow"

Response:

{
  "request_status": "SUCCESS",
  "request_id": "7aff1136-7a77-4111-b6bf-b3e1e3072b3c",
  "total_stats": [
    {
      "sub_request_status": "SUCCESS",
      "total_stat": {
        "id": "52b56e53-2c90-426c-af68-8bc12a472fa1",
        "type": "AD_ACCOUNT",
        "granularity": "TOTAL",
        "swipe_up_attribution_window": "28_DAY",
        "view_attribution_window": "1_DAY",
        "end_time": "2023-08-02T14:00:00.000-07:00",
        "finalized_data_end_time": "2023-08-02T07:00:00.000-07:00",
        "conversion_data_processed_end_time": "2023-08-01T12:00:00.000Z",
        "breakdown_stats": {
          "campaign": [
            {
              "id": "2249077d-b714-4088-860d-c06b4dbe53a2",
              "type": "CAMPAIGN",
              "granularity": "TOTAL",
              "stats": {
                "impressions": 1235768,
                "swipes": 11759,
                "conversion_0029904941": 14,
                "conversion_1828361131": 10,
                "conversion_0029904941_value": 2345,
                "conversion_1828361131_value": 678
              }
            }
          ]
        }
      }
    }
  ]
}

Example III - API reporting request Swipe and View

An example breaking the custom conversions into swipe and view.

Request:

curl "https://adsapi.snapchat.com/v1/adaccounts/52b56e53-2c90-426c-af68-8bc12a472fa1/stats?\
granularity=TOTAL&\
fields=impressions,swipes,conversion_0029904941,conversion_0029904941_swipe,conversion_0029904941_view,conversion_1828361131,conversion_1828361131_swipe,conversion_1828361131_view&\
swipe_up_attribution_window=28_DAY&\
view_attribution_window=1_DAY"
-H "Authorization: Bearer meowmeowmeow"

Response:

{
  "request_status": "SUCCESS",
  "request_id": "9bff1136-7a77-4111-b6bf-b3e1e3072b4a",
  "total_stats": [
    {
      "sub_request_status": "SUCCESS",
      "total_stat": {
        "id": "52b56e53-2c90-426c-af68-8bc12a472fa1",
        "type": "AD_ACCOUNT",
        "granularity": "TOTAL",
        "swipe_up_attribution_window": "28_DAY",
        "view_attribution_window": "1_DAY",
        "end_time": "2023-08-02T14:00:00.000-07:00",
        "finalized_data_end_time": "2023-08-02T07:00:00.000-07:00",
        "conversion_data_processed_end_time": "2023-08-01T12:00:00.000Z",
        "breakdown_stats": {
          "campaign": [
            {
              "id": "2249077d-b714-4088-860d-c06b4dbe53a2",
              "type": "CAMPAIGN",
              "granularity": "TOTAL",
              "stats": {
                "impressions": 1235768,
                "swipes": 11759,
                "conversion_0029904941": 14,
                "conversion_0029904941_swipe": 7,
                "conversion_0029904941_view": 7,
                "conversion_1828361131": 10,
                "conversion_1828361131_swipe": 4,
                "conversion_1828361131_view": 6
              }
            }
          ]
        }
      }
    }
  ]
}

Conversion breakout

The parameter conversion_source_types provides a breakout of conversions based on where the conversions occurred.

Parameter	Description
total	All conversion events
web	Events reported via the Snap Pixel SDK
app	Events reported within an App
offline	Events reported from an offline source (in-store)
total	The combined events reported for web, app, offline, and on platform (Stores and Profiles)
total_off_platform	The combined events reported for web, app, and offline
total_on_platform	Events reported from a Snap platform source (Stores and Profiles)

Conversion breakout example

curl "https://adsapi.snapchat.com/v1/adsquads/0b7e62aa-a8bc-48f6-a410-c65eee9cc9a7/stats?fields=conversion_purchases,impressions,spend,swipe_up_percent,swipes,view_completion&conversion_source_types=total,web,app"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "5de004c100ff03ea1eeb1050430001737e616473617069736300016275696c642d61663733336133322d312d3330372d3000010103",
  "total_stats": [
    {
      "sub_request_status": "SUCCESS",
      "total_stat": {
        "id": "0b7e62aa-a8bc-48f6-a410-c65eee9cc9a7",
        "type": "AD_SQUAD",
        "granularity": "TOTAL",
        "stats": {
          "impressions": 2337371,
          "swipes": 14745,
          "view_completion": 69506,
          "swipe_up_percent": 0.0063,
          "spend": 3449137066,
          "conversion_purchases": 1141,
          "conversion_purchases_web": 659,
          "conversion_purchases_app": 482
        },
        "finalized_data_end_time": "2019-11-28T02:00:00.000-08:00"
      }
    }
  ]
}

This parameter breaks down conversions based on where the conversion occurred.

Omitting empty records example

curl "https://adsapi.snapchat.com/v1/campaigns/9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37/stats?granularity=DAY&start_time=2019-11-12T00%3A00%3A00-08%3A00&end_time=2019-11-16T00%3A00%3A00-08%3A00&&swipe_up_attribution_window=28_DAY&view_attribution_window=7_DAY&fields=conversion_purchases,impressions,swipes,spend&conversion_source_types=web,app,total"
  -H "Authorization: Bearer meowmeowmeow"

An example not using omit_empty, this returns several day entries with no metrics.

{
  "request_status": "SUCCESS",
  "request_id": "5de0f99900ff02f49ea1540d1c0001737e616473617069736300016275696c642d61663733336133322d312d3330372d300001013c",
  "timeseries_stats": [
    {
      "sub_request_status": "SUCCESS",
      "timeseries_stat": {
        "id": "9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37",
        "type": "CAMPAIGN",
        "granularity": "DAY",
        "swipe_up_attribution_window": "28_DAY",
        "view_attribution_window": "7_DAY",
        "start_time": "2019-11-12T00:00:00.000-08:00",
        "end_time": "2019-11-16T00:00:00.000-08:00",
        "finalized_data_end_time": "2019-11-28T00:00:00.000-08:00",
        "timeseries": [
          {
            "start_time": "2019-11-12T00:00:00.000-08:00",
            "end_time": "2019-11-13T00:00:00.000-08:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "conversion_purchases": 0,
              "conversion_purchases_web": 0,
              "conversion_purchases_app": 0
            }
          },
          {
            "start_time": "2019-11-13T00:00:00.000-08:00",
            "end_time": "2019-11-14T00:00:00.000-08:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "conversion_purchases": 0,
              "conversion_purchases_web": 0,
              "conversion_purchases_app": 0
            }
          },
          {
            "start_time": "2019-11-14T00:00:00.000-08:00",
            "end_time": "2019-11-15T00:00:00.000-08:00",
            "stats": {
              "impressions": 599725,
              "swipes": 3790,
              "spend": 594736665,
              "conversion_purchases": 62,
              "conversion_purchases_web": 42,
              "conversion_purchases_app": 20
            }
          },
          {
            "start_time": "2019-11-15T00:00:00.000-08:00",
            "end_time": "2019-11-16T00:00:00.000-08:00",
            "stats": {
              "impressions": 670692,
              "swipes": 4189,
              "spend": 716170632,
              "conversion_purchases": 125,
              "conversion_purchases_web": 82,
              "conversion_purchases_app": 43
            }
          }
        ]
      }
    }
  ]
}

curl "https://adsapi.snapchat.com/v1/campaigns/9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37/stats?granularity=DAY&start_time=2019-11-12T00%3A00%3A00-08%3A00&end_time=2019-11-16T00%3A00%3A00-08%3A00&&swipe_up_attribution_window=28_DAY&view_attribution_window=7_DAY&fields=conversion_purchases,impressions,swipes,spend&conversion_source_types=web,app,total&omit_empty=true"
  -H "Authorization: Bearer meowmeowmeow"

An example using omit_empty, this returns only day entries with metrics:

{
  "request_status": "SUCCESS",
  "request_id": "5de0fa4900ff0942bb5374cb8f0001737e616473617069736300016275696c642d61663733336133322d312d3330372d300001014d",
  "timeseries_stats": [
    {
      "sub_request_status": "SUCCESS",
      "timeseries_stat": {
        "id": "9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37",
        "type": "CAMPAIGN",
        "granularity": "DAY",
        "swipe_up_attribution_window": "28_DAY",
        "view_attribution_window": "7_DAY",
        "start_time": "2019-11-12T00:00:00.000-08:00",
        "end_time": "2019-11-16T00:00:00.000-08:00",
        "finalized_data_end_time": "2019-11-28T00:00:00.000-08:00",
        "timeseries": [
          {
            "start_time": "2019-11-14T00:00:00.000-08:00",
            "end_time": "2019-11-15T00:00:00.000-08:00",
            "stats": {
              "impressions": 599725,
              "swipes": 3790,
              "spend": 594736665,
              "conversion_purchases": 62,
              "conversion_purchases_web": 42,
              "conversion_purchases_app": 20
            }
          },
          {
            "start_time": "2019-11-15T00:00:00.000-08:00",
            "end_time": "2019-11-16T00:00:00.000-08:00",
            "stats": {
              "impressions": 670692,
              "swipes": 4189,
              "spend": 716170632,
              "conversion_purchases": 125,
              "conversion_purchases_web": 82,
              "conversion_purchases_app": 43
            }
          }
        ]
      }
    }
  ]
}

The parameter omit_empty will omit records with zero data for all metrics for a given date/entity. If there is data for any metric for a given date/entity, all metrics for that date/entity are returned.

The omit_empty parameter allows developers to speed up calculations as empty entries can be removed before the calculation is made, it also allows developers to structure an app to avoid displaying empty entries in the UI.

Metrics and supported granularities

Metric	Real time	HOUR	DAY	TOTAL	LIFETIME
android_installs	YES	YES. time must be of hour boundary, start_time and end_time within 7 days	YES. time must be of day boundary, start_time and end_time within 31 days	YES. time must be of day boundary, start_time and end_time must be both specified, or neither. In the latter case, it combines lifetime and realtime stats.	YES. no start_time, end_time can be specified.
attachment_avg_view_time_millis
attachment_impressions
attachment_quartile_1
attachment_quartile_2
attachment_quartile_3
attachment_total_view_time_millis
attachment_view_completion
avg_screen_time_millis
avg_view_time_millis
impressions
ios_installs
quartile_1
quartile_2
quartile_3
screen_time_millis
spend
coupon_used_local
coupon_used_usd
swipe_up_percent
swipes
total_installs
landing_page_views
video_views
video_views_time_based
video_views_15s
view_completion
view_time_millis
paid_impressions
earned_impressions
total_impressions
play_time_millis
profile_clicks
shares
saves
native_leads
conversion_purchases
conversion_purchases_value
conversion_save
conversion_save_value
conversion_start_checkout
conversion_start_checkout_value
conversion_add_cart
conversion_add_cart_value
conversion_view_content
conversion_view_content_value
conversion_add_billing
conversion_add_billing_value
conversion_signups
conversion_signups_value
conversion_searches
conversion_searches_value
conversion_level_completes
conversion_level_completes_value
conversion_app_opens
conversion_app_opens_value
conversion_page_views
conversion_page_views_value
conversion_subscribe
conversion_subscribe_value
conversion_ad_click
conversion_ad_click_value
conversion_ad_view
conversion_ad_view_value
conversion_complete_tutorial
conversion_complete_tutorial_value
conversion_invite
conversion_invite_value
conversion_login
conversion_login_value
conversion_share
conversion_share_value
conversion_reserve
conversion_reserve_value
conversion_achievement_unlocked
conversion_achievement_unlocked_value
conversion_add_to_wishlist
conversion_add_to_wishlist_value
conversion_spend_credits
conversion_spend_credits_value
conversion_rate
conversion_rate_value
conversion_start_trial
conversion_start_trial_value
conversion_list_view
conversion_list_view_value
custom_event_1
custom_event_1_value
custom_event_2
custom_event_2_value
custom_event_3
custom_event_3_value
custom_event_4
custom_event_4_value
custom_event_5
custom_event_5_value
attachment_frequency	YES	NO	YES	YES. Available from 1st January 2021	YES
attachment_uniques
frequency
uniques
total_reach
earned_reach

Example for All Metrics

curl -H "Authorization: Bearer meowmeow" \
    "https://adsapi.snapchat.com/v1/campaigns/2bbaa6e3-4ddb-4358-9efe-48334952f4aa/stats?breakdown=adsquad&fields=android_installs,avg_screen_time_millis,attachment_frequency,attachment_quartile_1,attachment_quartile_2,attachment_quartile_3,attachment_total_view_time_millis,attachment_uniques,attachment_view_completion,frequency,impressions,ios_installs,quartile_1,quartile_2,quartile_3,spend,swipe_up_percent,swipes,total_installs,uniques,view_completion,screen_time_millis&granularity=DAY&start_time=2016-10-24T07:00:00.000-00:00&end_time=2016-10-26T07:00:00.000-00:00"

{
  "request_status": "SUCCESS",
  "request_id": "5813ccf400ff07b016a837c09f0001737e616473617069736300016275696c642d65373832323966352d73746174732d322d7465737400010133",
  "timeseries_stats": [
    {
      "sub_request_status": "SUCCESS",
      "timeseries_stat": {
        "id": "2bbaa6e3-4ddb-4358-9efe-48334952f4aa",
        "type": "CAMPAIGN",
        "start_time": "2016-10-24T07:00:00.000Z",
        "end_time": "2016-10-26T07:00:00.000Z",
        "breakdown_stats": {
          "adsquad": [
            {
              "id": "134aeb99-6552-4f1d-b7a6-82b9813fd079",
              "type": "AD_SQUAD",
              "granularity": "DAY",
              "start_time": "2016-10-24T07:00:00.000Z",
              "end_time": "2016-10-26T07:00:00.000Z",
              "timeseries": [
                {
                  "start_time": "2016-10-24T07:00:00.000Z",
                  "end_time": "2016-10-25T07:00:00.000Z",
                  "stats": {
                    "impressions": 18294,
                    "swipes": 0,
                    "quartile_1": 7489,
                    "quartile_2": 2595,
                    "quartile_3": 1964,
                    "view_completion": 1635,
                    "attachment_quartile_1": 0,
                    "attachment_quartile_2": 0,
                    "attachment_quartile_3": 0,
                    "attachment_view_completion": 0,
                    "attachment_total_view_time_millis": 0,
                    "frequency": 1.0014,
                    "avg_screen_time_millis": 1832,
                    "swipe_up_percent": 0,
                    "attachment_frequency": 0,
                    "attachment_avg_view_time_millis": 0,
                    "uniques": 18268,
                    "attachment_uniques": 0,
                    "ios_installs": 0,
                    "android_installs": 0,
                    "total_installs": 0,
                    "spend": 144213617,
                    "screen_time_millis": 33876700
                  }
                },
                {
                  "start_time": "2016-10-25T07:00:00.000Z",
                  "end_time": "2016-10-26T07:00:00.000Z",
                  "stats": {
                    "impressions": 15377,
                    "swipes": 0,
                    "quartile_1": 6345,
                    "quartile_2": 2185,
                    "quartile_3": 1596,
                    "view_completion": 1324,
                    "attachment_quartile_1": 0,
                    "attachment_quartile_2": 0,
                    "attachment_quartile_3": 0,
                    "attachment_view_completion": 0,
                    "attachment_total_view_time_millis": 0,
                    "frequency": 1.0011,
                    "avg_screen_time_millis": 1828,
                    "swipe_up_percent": 0,
                    "attachment_frequency": 0,
                    "attachment_avg_view_time_millis": 0,
                    "uniques": 15360,
                    "attachment_uniques": 0,
                    "ios_installs": 0,
                    "android_installs": 0,
                    "total_installs": 0,
                    "spend": 120978178,
                    "screen_time_millis": 28547600
                  }
                }
              ]
            }
}

Get Ad Account Stats

curl "https://adsapi.snapchat.com/v1/adaccounts/22335ba6-7558-4100-9663-baca7adff5f2/stats?granularity=TOTAL&fields=spend" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b24d9c00ff0d85622341e7c60001737e616473617069736300016275676c642b34326313636139312d332d31312d390001010d",
  "total_stats": [
    {
      "sub_request_status": "success",
      "total_stat": {
        "id": "22335ba6-7558-4100-9663-baca7adff5f2",
        "type": "AD_ACCOUNT",
        "granularity": "TOTAL",
        "stats": {
          "spend": 89196290
        },
        "finalized_data_end_time": "2019-08-29T03:00:00.000-07:00"
      }
    }
  ]
}

This endpoint retrieves the spend metric for the specified Ad Account, the spend metric is the only metric available for the ad account entity.

HTTP Request

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Get Campaign Stats

curl "https://adsapi.snapchat.com/v1/campaigns/92e1c28a-a331-45b4-8c26-fd3e0eea8c39/stats?granularity=TOTAL&fields=impressions,swipes,screen_time_millis,quartile_1,quartile_2,quartile_3,view_completion,spend" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b24d9c00ff0d85622341e7c60001737e616473617069736300016275696c642d34326333636139312d312d31312d390001010d",
  "total_stats": [
    {
      "sub_request_status": "success",
      "total_stat": {
        "id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
        "type": "CAMPAIGN",
        "granularity": "TOTAL",
        "stats": {
          "impressions": 0,
          "swipes": 0,
          "spend": 0,
          "quartile_1": 0,
          "quartile_2": 0,
          "quartile_3": 0,
          "view_completion": 0,
          "screen_time_millis": 0
        }
      }
    }
  ]
}

This endpoint retrieves stats for the specified Campaign.

HTTP Request

GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/stats

Parameters

Parameter	Default	Description
campaign_id		Campaign ID

Get Ad Squad Stats

curl "https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/stats?granularity=TOTAL&fields=impressions,swipes,screen_time_millis,quartile_1,quartile_2,quartile_3,view_completion,spend"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b24e5200ff0225cdf221e6c90001737e616473617069736300016275696c642d34326333636139312d312d31312d3900010106",
  "total_stats": [
    {
      "sub_request_status": "success",
      "total_stat": {
        "id": "23995202-bfbc-45a0-9702-dd6841af52fe",
        "type": "AD_SQUAD",
        "granularity": "TOTAL",
        "stats": {
          "impressions": 0,
          "swipes": 0,
          "spend": 0,
          "quartile_1": 0,
          "quartile_2": 0,
          "quartile_3": 0,
          "view_completion": 0,
          "screen_time_millis": 0
        }
      }
    }
  ]
}

This endpoint retrieves stats for the specified Ad Squad.

HTTP Request

GET https://adsapi.snapchat.com/v1/adsquads/{adsquad_id}/stats

Parameters

Parameter	Default	Description
adsquad_id		Ad Squad ID

Get Ad Stats

curl "https://adsapi.snapchat.com/v1/ads/e8d6217f-32ab-400f-9e54-39a86a7963e4/stats?granularity=TOTAL&fields=impressions,swipes,screen_time_millis,quartile_1,quartile_2,quartile_3,view_completion,spend"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b24ec400ff0b0a2104182f430001737e616473617069736300016275696c642d34326333636139312d312d31312d390001010f",
  "total_stats": [
    {
      "sub_request_status": "success",
      "total_stat": {
        "id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
        "type": "AD",
        "granularity": "TOTAL",
        "stats": {
          "impressions": 0,
          "swipes": 0,
          "spend": 0,
          "quartile_1": 0,
          "quartile_2": 0,
          "quartile_3": 0,
          "view_completion": 0,
          "screen_time_millis": 0
        }
      }
    }
  ]
}

This endpoint retrieves stats for the specified Ad.

HTTP Request

GET https://adsapi.snapchat.com/v1/ads/{ad_id}/stats

Parameters

Parameter	Default	Description
ad_id		Ad ID

Reporting for Creatives and Media

It's possible to fetch reporting for the Creative entity and the Media entity given some restrictions.

• The available granularities for Media and Creative reporting are DAY and LIFETIME, TOTAL granularity is not available.
• Reach metrics (frequency, attachmentfrequency, uniques, attachment_uniques, total_reach) are _not available for Media and Creatives
• Reporting is only available to non-DPA Creatives

Creative	Type	Reporting availability
Snap Ad	SNAP_AD	Yes
Snap Ad with attachment	APP_INSTALL, WEB_VIEW, DEEP_LINK	Yes
Preview Creative	PREVIEW	No

Media	Type	Reporting availability
Top Snap	IMAGE	Yes
Top Snap	VIDEO	Yes
Lens LENS	LENS_PACKAGE	Yes
Story Tile	IMAGE	No
Creative element	IMAGE	No

Fetching reporting for a Creative

This endpoint retrieves stats for the specified Creative.

HTTP Request

GET https://adsapi.snapchat.com/v1/creatives/{creative_id}/stats

Parameters

Parameter	Default	Description
creative_id		Creative ID

curl "https://adsapi.snapchat.com/v1/creatives/abc123/stats?granularity=TOTAL&fields=impressions,swipes,screen_time_millis,quartile_1,quartile_2,quartile_3,view_completion,spend"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "",
  "total_stats": [
    {
      "sub_request_status": "success",
      "total_stat": {
        }
      }
    }
  ]
}

Reporting Insights and Dimensions

Delivery Insights can help you understand who viewed, engaged, and took action on your ads. These insights across demographic, location, device, and interest categories can help inform optimization and increase overall campaign efficiency. Insights can be pulled for specific campaigns, ad squads, or ads; insights can also use breakdowns for multiple campaigns, ad squads, or ads at once.

• Delivery Insights are estimated to protect user privacy. They are meant to provide directional guidance on audience performance.
• Delivery Insights are only availble on days when there are at least 30 impressions.
• Delivery Insights are only available from 1 January 2020. DAY, TOTAL, and LIFETIME granularities are supported, the HOUR granularity is not available for delivery insights. Some conversion reporting metrics are available from 1 May 2020.
• Delivery insights for the combination of Country and Operating System are available from 24 October 2022 onwards.

Dimensions

You can get reporting insights based on different geographic, demographic, interest-based, and device-based dimensions. You can only query one dimension at a time unless you are querying age & gender which may be combined. Some of the dimensions (region/dma/make) only support Delivery metrics, for these dimensions it's not possible to fetch conversion metrics.

Using the report_dimension query string parameter you can see Snapchat metrics based on a number of new dimensions

Category	API Dimension (report_dimension)	Conditions	Metrics availability
Geo	country	Metrics broken down by ISO country code	Delivery/Conversion
	country,os*	Metrics broken down by ISO country code and Device Operating System*	Delivery
	region	Metrics broken down by ISO country code (US only)	Delivery
	dma	Metrics broken down by ISO country code (US only)	Delivery
Demographic	gender	Metrics broken down by gender	Delivery/Conversion
	age**	Metrics broken down by age buckets**	Delivery/Conversion
	age,gender	Metrics broken down by age and gender	Delivery/Conversion
Device	os	Device Operating System	Delivery/Conversion
	os,country	Metrics broken down by Device Operating System and ISO country code*	Delivery
	make	Device Make	Delivery
Interest	lifestyle_category	Metrics broken down by interest category (Snapchat Lifestyle Category)	Delivery

*Country/OS metrics breakdown is available from 24 October 2022

**Age bucket breakdown have been expanded since 28 February 2025

Metrics

You may pass these metrics as a comma separated list for the fields query parameter. Conversion metrics support attribution windows, swipe/view variants, and value metrics in local microcents. Note that conversion metrics are not available for the dimensions lifestyle_category, region,dma or make.

Delivery Metrics

Metric	API field	Description
Paid Impressions	impressions	Impression Count
Unique Impressions	uniques	Unique Impressions Count
Swipe Ups	swipes	Swipe-Up Count
25% Quartile	quartile_1	Video Views to 25%
50% Quartile	quartile_2	Video Views to 50%
75% Quartile	quartile_3	Video Views to 75%
Completions	view_completion	Video Views to completion
Spend	spend	Amount Spent (micro-currency)
Video Views	video_views	The total number of impressions that meet the qualifying video view criteria of at least 2 seconds of consecutive watch time or a swipe up action on the Top Snap
Landing Page Views*	landing_page_views*	The total number of times a user loaded the ad’s landing page after a click
Attachment Uniques	attachment_uniques	Attachment Uniques
25% Attachment Quartile	attachment_quartile_1	Long Form Video Views to 25%
50% Attachment Quartile	attachment_quartile_2	Long Form Video Views to 50%
75% Attachment Quartile	attachment_quartile_3	Long Form Video Views to 75%
Attachment Completions	attachment_view_completion	Long Form Video Views to completion
Attachment View Time	attachment_total_view_time_millis	Total Attachment View Time (milli-seconds)
Attachment Video Views	attachment_video_views	Long Form Video Attachment Views
Story Opens	story_opens	# of times users tapped on the ad tile in the feed to view the Story Ad
Story Completes	story_completes	# of times users viewed through to the last Snap of your Story Ad
Shares	shares	# of times lens/filter was shared in a Chat or Story
Saves	saves	# of times lens/filter was saved to Memories

*landing_page_views are available from 10 December 2024

Conversion Metrics

Metric	API field	Description
Installs	total_installs	Total # of App Installs
Purchases	conversion_purchases	# of attributed “PURCHASE” conversion events**
Purchase Value	conversion_purchases_value	Value of attributed “PURCHASE” conversion events (microcurrency in Ad Account’s currency)**
Saves	conversion_save	# of attributed “SAVE” conversion events**
Start Checkout	conversion_start_checkout	# of attributed “START_CHECKOUT” conversion events**
Add To Cart	conversion_add_cart	# of attributed “ADD_CART” conversion events**
View Content	conversion_view_content	# of attributed “VIEW_CONTENT” conversion events**
Add Billing	conversion_add_billing	# of attributed “ADD_BILLING” conversion events**
Sign Ups	conversion_sign_ups	# of attributed “SIGN_UP” conversion events**
Searches	conversion_searches	# of attributed “SEARCH” conversion events**
Level Completes	conversion_level_completes	# of attributed “LEVEL_COMPLETE” conversion events**
App Opens	conversion_app_opens	# of attributed “APP_OPEN” conversion events**
Page Views	conversion_page_views	# of attributed “PAGE_VIEW” conversion events**
Subscribes	conversion_subscribe	# of attributed "SUBSCRIBE" conversion events++
Ad Clicks	conversion_ad_click	# of attributed “CONVERSION_AD_CLICK” conversion events++
Ad Views	conversion_ad_view	# of attributed “CONVERSION_AD_VIEW” conversion events++
Completed Tutorials	conversion_complete_tutorial	# of attributed “CONVERSION_COMPLETE_TUTORIAL” conversion events++
Invites Sent	conversion_invite	# of attributed “CONVERSION_INVITE” conversion events++
Logins	conversion_login	# of attributed “CONVERSION_LOGIN” conversion events++
Shares	conversion_share	# of attributed “CONVERSION_SHARE” conversion events++
Reservations	conversion_reserve	# of attributed “CONVERSION_RESERVE” conversion events++
Achievements Unlocked	conversion_achievement_unlocked	# of attributed “CONVERSION_ACHIEVEMENT_UNLOCKED” conversion events++
Adds to Wishlist	conversion_add_to_wishlist	# of attributed “CONVERSION_ADD_TO_WISHLIST” conversion events++
Credits Spent	conversion_spend_credits	# of attributed “CONVERSION_SPEND_CREDITS” conversion events++
Rates Submitted	conversion_rate	# of attributed “CONVERSION_RATE” conversion events++
Trial Starts	conversion_start_trial	# of attributed “CONVERSION_START_TRIAL” conversion events++
Lists Viewed	conversion_list_view	# of attributed “LIST_VIEW” conversion events++
Store Visits	conversion_visit	# of attributed “VISIT” conversion events++
Custom Event 1	custom_event_1	# of attributed “CUSTOM_EVENT_1” conversion events++
Custom Event 2	custom_event_2	# of attributed “CUSTOM_EVENT_2” conversion events++
Custom Event 3	custom_event_3	# of attributed “CUSTOM_EVENT_3” conversion events++
Custom Event 4	custom_event_4	# of attributed “CUSTOM_EVENT_4” conversion events++
Custom Event 5	custom_event_5	# of attributed “CUSTOM_EVENT_5” conversion events++

** This conversion metric is available from 1st January 2020 when using action_report_time=conversion and 1st May 2020 when using **action_report_time=impression**

++ This conversion metric is available from 1st of May 2020 for both action_report_time=conversion and action_report_time=impression

Insights by GEO

HTTP Request

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats

Parameters

Parameter	Possible values	Description
ad_account_id		Ad Account ID
report_dimension	country,region,dma	The desired Report Dimension

Example of Geographic Insights

This retrieves insights for country broken down to Campaign level using report_dimension=country.

curl "https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/stats/?granularity=TOTAL&breakdown=campaign&fields=impressions,swipes,conversion_purchases&report_dimension=country&start_time=2020-01-25T00:00:00-08:00&end_time=2020-01-26T00:00:00-08:00&swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "5e6bee5400ff0aaf11217b24900001737e616473617069736300016275696c642d31636430373832652d312d3333342d3000010128",
  "total_stats": [
    {
      "sub_request_status": "SUCCESS",
      "total_stat": {
        "id": "22225ba6-7559-4000-9663-bace8adff5f2",
        "type": "AD_ACCOUNT",
        "granularity": "TOTAL",
        "swipe_up_attribution_window": "28_DAY",
        "view_attribution_window": "1_DAY",
        "start_time": "2020-01-25T00:00:00.000-08:00",
        "end_time": "2020-01-26T00:00:00.000-08:00",
        "finalized_data_end_time": "2020-03-13T00:00:00.000-07:00",
        "breakdown_stats": {
          "campaign": [
            {
              "id": "88821981-14be-4315-9832-278b27004d68",
              "type": "CAMPAIGN",
              "granularity": "TOTAL",
              "start_time": "2020-01-25T00:00:00.000-08:00",
              "end_time": "2020-01-26T00:00:00.000-08:00",
              "dimension_stats": [
                {
                  "impressions": 23433,
                  "swipes": 141,
                  "country": "au",
                  "conversion_purchases": 3
                }
              ]
            },
            {
              "id": "8079bbff-8a7b-4548-8556-d726461da248",
              "type": "CAMPAIGN",
              "granularity": "TOTAL",
              "start_time": "2020-01-25T00:00:00.000-08:00",
              "end_time": "2020-01-26T00:00:00.000-08:00",
              "dimension_stats": [
                {
                  "impressions": 19970,
                  "swipes": 488,
                  "country": "us",
                  "conversion_purchases": 4
                }
              ]
            },
            {
              "id": "828f739c-7f32-4013-9a92-58c6495e9438",
              "type": "CAMPAIGN",
              "granularity": "TOTAL",
              "start_time": "2020-01-25T00:00:00.000-08:00",
              "end_time": "2020-01-26T00:00:00.000-08:00",
              "dimension_stats": [
                {
                  "impressions": 46068,
                  "swipes": 74,
                  "country": "fr",
                  "conversion_purchases": 5
                }
              ]
            }
          ]
        },
        "split_results": []
      }
    }
  ]
}

Insights by DEMO

When requesting reporting insights using demographic parameters (age/gender) the response will be broken into age buckets.

Following the introduction of the possibility to target Snapchat users aged 55+ in February 2025 we have introduced additional age buckets, this means the age buckets returned in reporting depends on the date that the campaign was live. Campaigns that ran prior to to February 2025 only have a specific set of Age buckets available.

Age buckets (age_bucket)	Age buckets (age_bucket) after 28 February 2025	Description
13-17	13-17
18-20	18-20
21-24	21-24
25-34	25-34
35+	35+	This bucket will start to return 0 from Day Month
	35-44*	New age bucket
	45-54*	New age bucket
	55+*	New age bucket

*These age bucket will start to account for conversion metrics from the 27 March 2025

HTTP Request

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats

Parameters

Parameter	Possible values	Description
ad_account_id		Ad Account ID
report_dimension	age,gender	The desired Report Dimension

Example of Demographic Insights

curl "https://adsapi.snapchat.com/v1/ads/a08f3e23-735b-4cd2-b72d-0cdb4d47967b/stats?granularity=TOTAL&fields=impressions,spend,swipe_up_percent,swipes,view_completion,conversion_sign_ups&start_time=2025-02-15&end_time=2025-03-05&report_dimension=age,gender"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "0126c186-4416-4dea-8be0-2a999b54c780",
  "total_stats": [
    {
      "sub_request_status": "SUCCESS",
      "total_stat": {
        "id": "a08f3e23-735b-4cd2-b72d-0cdb4d47967b",
        "type": "AD",
        "granularity": "TOTAL",
        "swipe_up_attribution_window": "28_DAY",
        "view_attribution_window": "1_DAY",
        "engaged_view_attribution_window": "2_DAY",
        "start_time": "2025-02-15T00:00:00.000-05:00",
        "end_time": "2025-03-05T00:00:00.000-05:00",
        "finalized_data_end_time": "2025-03-05T13:00:00.000Z",
        "conversion_data_processed_end_time": "2025-03-05T00:00:00.000Z",
        "dimension_stats": [
          {
            "impressions": 17461,
            "swipes": 16,
            "view_completion": 90,
            "swipe_up_percent": 0.0027,
            "spend": 362083431,
            "age_bucket": "13-17",
            "gender": "female",
            "conversion_sign_ups": 11
          },
          {
            "impressions": 12480,
            "swipes": 26,
            "view_completion": 59,
            "swipe_up_percent": 0.0019,
            "spend": 62093431,
            "age_bucket": "13-17",
            "gender": "male",
            "conversion_sign_ups": 22
          },
          {
            "impressions": 15461,
            "swipes": 26,
            "view_completion": 80,
            "swipe_up_percent": 0.0017,
            "spend": 262083431,
            "age_bucket": "25-34",
            "gender": "female",
            "conversion_sign_ups": 11
          },
          {
            "impressions": 2489,
            "swipes": 3,
            "view_completion": 10,
            "swipe_up_percent": 0.0012,
            "spend": 51786604,
            "age_bucket": "35-44",
            "gender": "female",
            "conversion_sign_ups": 0
          },
          {
            "impressions": 3379,
            "swipes": 7,
            "view_completion": 12,
            "swipe_up_percent": 0.0021,
            "spend": 70961784,
            "age_bucket": "35+",
            "gender": "female",
            "conversion_sign_ups": 2
          },
          {
            "impressions": 677,
            "swipes": 1,
            "view_completion": 2,
            "swipe_up_percent": 0.0015,
            "spend": 12764108,
            "age_bucket": "45-54",
            "gender": "female",
            "conversion_sign_ups": 0
          },
          {
            "impressions": 213,
            "swipes": 3,
            "view_completion": 0,
            "swipe_up_percent": 0.0141,
            "spend": 6410980,
            "age_bucket": "55+",
            "gender": "female",
            "conversion_sign_ups": 0
          },
          {
            "impressions": 2381,
            "swipes": 6,
            "view_completion": 6,
            "swipe_up_percent": 0.0025,
            "spend": 43242099,
            "age_bucket": "35-44",
            "gender": "male",
            "conversion_sign_ups": 0
          },
          {
            "impressions": 48007,
            "swipes": 82,
            "view_completion": 176,
            "swipe_up_percent": 0.0017,
            "spend": 536629398,
            "age_bucket": "18-20",
            "gender": "male",
            "conversion_sign_ups": 8
          },
          {
            "impressions": 35379,
            "swipes": 59,
            "view_completion": 116,
            "swipe_up_percent": 0.0017,
            "spend": 464316698,
            "age_bucket": "21-24",
            "gender": "male",
            "conversion_sign_ups": 10
          },
          {
            "impressions": 16760,
            "swipes": 18,
            "view_completion": 44,
            "swipe_up_percent": 0.0011,
            "spend": 270528840,
            "age_bucket": "25-34",
            "gender": "male",
            "conversion_sign_ups": 3
          },
          {
            "impressions": 3201,
            "swipes": 8,
            "view_completion": 9,
            "swipe_up_percent": 0.0025,
            "spend": 59504925,
            "age_bucket": "35+",
            "gender": "male",
            "conversion_sign_ups": 2
          },
          {
            "impressions": 60964,
            "swipes": 85,
            "view_completion": 177,
            "swipe_up_percent": 0.0014,
            "spend": 696182537,
            "age_bucket": "18-20",
            "gender": "female",
            "conversion_sign_ups": 22
          },
          {
            "impressions": 595,
            "swipes": 2,
            "view_completion": 1,
            "swipe_up_percent": 0.0034,
            "spend": 11822674,
            "age_bucket": "45-54",
            "gender": "male",
            "conversion_sign_ups": 0
          },
          {
            "impressions": 46007,
            "swipes": 58,
            "view_completion": 104,
            "swipe_up_percent": 0.0013,
            "spend": 583008613,
            "age_bucket": "21-24",
            "gender": "female",
            "conversion_sign_ups": 12
          },
          {
            "impressions": 225,
            "swipes": 0,
            "view_completion": 2,
            "swipe_up_percent": 0.0,
            "spend": 4440022,
            "age_bucket": "55+",
            "gender": "male",
            "conversion_sign_ups": 0
          }
        ]
      }
    }
  ]
}

This API requests retrieves insights for an Ad, broken down by age and gender by using the parameter report_dimension=gender,age.

Reporting Insights: Dimension and Pivots

On the 20th of March 2020 we announced the deprecation of the dimension and pivots parameters, please ensure that you have switched to using report_dimension by the 20th of June 2020. After the deprecation you will still be able to use dimension and pivots to retrieve data finalized prior to the 20th June 2020.

The new parameter report_dimension is described in Reporting Insights and Dimensions.

Dimension and Pivots

You can get reporting insights based on different dimensions like GEO, DEMO, INTEREST and DEVICE by using the parameters dimension and pivots. Within each dimension, data can be broken down by different pivots. You can only query one dimension at a time. For insights breakdown, only LIFETIME granularity is supported.

Dimension	Pivot	Required/Optional	Conditions
GEO	country	Yes	None
	region	No	dma has to be queried with region
	dma	No	dma has to be queried with region
DEMO	gender	No	At least one of gender or age_bucket has to be specified if dimension is DEMO
	age_bucket	No	At least one of gender or age_bucket has to be specified if dimension is DEMO
INTEREST	interest_category_id	Yes	None
	interest_category_name	No	None
DEVICE	operating_system	Yes	None
	make	No	model has to be queried with make
	model	No	model has to be queried with make

The fields that can be broken down by dimenssion and pivots are:

Field	Description
impressions	Impression Count
impression_composition	The percent of impressions served to the insights category
uniques	# of unique impressions
unique_composition	The percent of uniques served to the insights category
spend	Amount spent (microcurrency)
swipes	Swipe up Count

Attribution windows

The attribution window is the time period in which a conversion will be counted after a user sees an ad. By default, Snap's attribution windows are 28 days post-swipe, 2 day post-view for engaged views (5 seconds or longer) and 1 day post-view (views shorter than 5 seconds).

Metrics and their variants

Conversions can be broken down by the method by which they were attributed, this table outlines the variant name that should be used in reporting requests.

Metric	Swipe variant	Engaged View variant	View variant
total_installs	total_installs_swipe_up	total_installs_engaged_view	total_installs_view
android_installs	android_installs_swipe_up	android_installs_engaged_view	android_installs_view
ios_installs	ios_installs_swipe_up	ios_installs_engaged_view	ios_installs_view
conversion_purchases	conversion_purchases_swipe_up	conversion_purchases_engaged_view	conversion_purchases_view
conversion_purchases_value	conversion_purchases_value_swipe_up	conversion_purchases_value_engaged_view	conversion_purchases_value_view
conversion_save	conversion_save_swipe_up	conversion_save_engaged_view	conversion_save_view
conversion_start_checkout	conversion_start_checkout_swipe_up	conversion_start_checkout_engaged_view	conversion_start_checkout_view
conversion_add_cart	conversion_add_cart_swipe_up	conversion_add_cart_engaged_view	conversion_add_cart_view
conversion_view_content	conversion_view_content_swipe_up	conversion_view_content_engaged_view	conversion_view_content_view
conversion_add_billing	conversion_add_billing_swipe_up	conversion_add_billing_engaged_view	conversion_add_billing_view
conversion_sign_ups	conversion_sign_ups_swipe_up	conversion_sign_ups_engaged_view	conversion_sign_ups_view
conversion_searches	conversion_searches_swipe_up	conversion_searches_engaged_view	conversion_searches_view
conversion_level_completes	conversion_level_completes_swipe_up	conversion_level_completes_engaged_view	conversion_level_completes_view
conversion_app_opens	conversion_app_opens_swipe_up	conversion_app_opens_engaged_view	conversion_app_opens_view
conversion_page_views	conversion_page_views_swipe_up	conversion_page_views_engaged_view	conversion_page_views_view
conversion_subscribe	conversion_subscribe_swipe_up	conversion_subscribe_engaged_view	conversion_subscribe_view
conversion_ad_click	conversion_ad_click_swipe_up	conversion_ad_click_engaged_view	conversion_ad_click_view
conversion_ad_view	conversion_ad_view_swipe_up	conversion_ad_view_engaged_view	conversion_ad_view_view
conversion_complete_tutorial	conversion_complete_tutorial_swipe_up	conversion_complete_tutorial_engaged_view	conversion_complete_tutorial_view
conversion_invite	conversion_invite_swipe_up	conversion_invite_engaged_view	conversion_invite_view
conversion_login	conversion_login_swipe_up	conversion_login_engaged_view	conversion_login_view
conversion_share	conversion_share_swipe_up	conversion_share_engaged_view	conversion_share_view
conversion_reserve	conversion_reserve_swipe_up	conversion_reserve_engaged_view	conversion_reserve_view
conversion_achievement_unlocked	conversion_achievement_unlocked_swipe_up	conversion_achievement_unlocked_engaged_view	conversion_achievement_unlocked_view
conversion_add_to_wishlist	conversion_add_to_wishlist_swipe_up	conversion_add_to_wishlist_engaged_view	conversion_add_to_wishlist_view
conversion_spend_credits	conversion_spend_credits_swipe_up	conversion_spend_credits_engaged_view	conversion_spend_credits_view
conversion_rate	conversion_rate_swipe_up	conversion_rate_engaged_view	conversion_rate_view
conversion_start_trial	conversion_start_trial_swipe_up	conversion_start_trial_engaged_view	conversion_start_trial_view
conversion_list_view	conversion_list_view_swipe_up	conversion_list_view_engaged_view	conversion_list_view_view
custom_event_1	custom_event_1_swipe_up	custom_event_1_engaged_view	custom_event_1_view
custom_event_2	custom_event_2_swipe_up	custom_event_2_engaged_view	custom_event_2_view
custom_event_3	custom_event_3_swipe_up	custom_event_3_engaged_view	custom_event_3_view
custom_event_4	custom_event_4_swipe_up	custom_event_4_engaged_view	custom_event_4_view
custom_event_5	custom_event_5_swipe_up	custom_event_5_engaged_view	custom_event_5_view

Allowed combinations of attribution windows

Engaged View Conversions are always available with a fixed attribution window of two days, for this reason there is no need to provide an attribution window.

View window	Swipe window 1_DAY	Swipe window 7_DAY	Swipe window 28_DAY
none*	Allowed	Allowed	Allowed
1_HOUR	Allowed	Allowed	Allowed
3_HOUR	Allowed	Allowed	Allowed
6_HOUR	Allowed	Allowed	Allowed
1_DAY	Allowed	Allowed	Allowed
7_DAY	Not Allowed	Allowed	Allowed
28_DAY	Not Allowed	Not Allowed	Allowed

*When using view_attribution_window=none no View conversions will be returned

Attribution windows example

curl "https://adsapi.snapchat.com/v1/campaigns/04dd5e26-7156-4e07-b2b8-2911ae3aaccc/stats?granularity=DAY&fields=impressions,spend,conversion_add_cart,conversion_add_cart_swipe_up,conversion_add_cart_engaged_view,conversion_add_cart_view,conversion_purchases,conversion_purchases_swipe_up,conversion_purchases_engaged_view,conversion_purchases_view&swipe_up_attribution_window=28_DAY&view_attribution_window=7_DAY&start_time=2025-03-10T00:00:00-08:00&end_time=2025-03-12T00:00:00-08:00"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "5a1e176f00ff09ef429913ea970001737e616473617069736300016275696c642d65336335336136322d312d3132312d31",
  "timeseries_stats": [
    {
      "sub_request_status": "SUCCESS",
      "timeseries_stat": {
        "id": "04dd5e26-7156-4e07-b2b8-2911ae3aaccc",
        "type": "CAMPAIGN",
        "granularity": "DAY",
        "swipe_up_attribution_window": "28_DAY",
        "view_attribution_window": "7_DAY",
        "start_time": "2025-03-10T00:00:00-08:00",
        "end_time": "2025-03-12T00:00:00-08:00",
        "finalized_data_end_time": "2025-03-20T00:00:00.000-08:00",
        "timeseries": [
          {
            "start_time": "2025-03-10T00:00:00-08:00",
            "end_time": "2025-03-12T00:00:00-08:00",
            "stats": {
              "impressions": 63027,
              "spend": 190136020,
              "conversion_purchases": 23,
              "conversion_purchases_swipe_up": 6,
              "conversion_purchases_engaged_view": 10,
              "conversion_purchases_view": 7,
              "conversion_add_cart": 27,
              "conversion_add_cart_swipe_up": 8,
              "conversion_add_cart_engaged_view": 7,
              "conversion_add_cart_view": 12
            }
          },
          {
            "start_time": "2025-03-10T00:00:00-08:00",
            "end_time": "2025-03-12T00:00:00-08:00",
            "stats": {
              "impressions": 74153,
              "spend": 200905774,
              "conversion_purchases": 12,
              "conversion_purchases_swipe_up": 3,
              "conversion_purchases_engaged_view": 2,
              "conversion_purchases_view": 7,
              "conversion_add_cart": 26,
              "conversion_add_cart_swipe_up": 5,
              "conversion_add_cart_engaged_view": 6,
              "conversion_add_cart_view": 15
            }
          }
        ]
      }
    }
  ]
}

This retrieves insights broken down by specified attribution windows.

Reporting for Dynamic Product Ads (DPA)

Snapchat now offers a reporting API endpoint so that advertisers can retrieve product-level reporting for Dynamic Product Ads. This report allows advertisers to understand how their campaigns, ad squads, ads delivered & performed for individual products. Reports can only be pulled with a 1 day date range for TOTAL granularity. There are two types of reports that can be retrieved. These are the full reports using the async API and the top-k report using the regular API.

Supported Breakdowns

• Results can be broken down by campaign, ad squad, and ad
• Results can be broken down by date or total

Supported Metrics

Field name	Description
product_impressions	number of impressions for a product ID
swipes
spend	microcents local currency

Report Requirements

• Reports must be 1 day in length
• Start (start_time) & End Date (end_time) must be specified

Full reports for DPA (Async)

Due to the size of reports, DPA reporting runs on Snapchat’s asynchronous API and returns a file for the full DPA breakdown. The API call to the stats endpoint for a DPA report returns a report run ID. This run ID can be used to make a subsequent call to the stats_report endpoint to check its status. Upon completion, a signed URL is generated to download the report as a CSV; this CSV has a time to live of 24 hours.

Stats request - Step 1

curl "https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats?breakdown=campaign&granularity=DAY&swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY&start_time=2023-03-17&end_time=2023-03-18&fields=product_impressions,swipes,spend&position_stats=false&platform_stats=false&report_dimension=product&omit_empty=true&async=true&async_format=csv" -H "Authorization: Bearer meowmeowmeow"

{
  "request_status": "SUCCESS",
  "request_id": "<ID>",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6"
      }
    }
  ]
}

Additional Request Parameters

These are the specific request parameters necessary to call the DPA Async report API

Attribute	Values
report_dimension	product
async	true
async_format	csv

Response - async_stats_report Object

Attribute	Description	Values
report_run_id	the ID of your reporting task	eg: "ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6"
async_status	The current status of the reporting task. Once this changes to COMPLETED, the result field will be populated with the URL for the report.	RUNNING, COMPLETED
result	This contains the URL of the report file	eg: "https://data-transfer.snapads.com/async-report/dpa_full/ASYNC_STATS:0efa41e1-5087-48af-8dbc-2cf8aefasdf66e6/4a6csdf1-3234-484b-b2cf-eeb6f1a63c3f.csv"

CSV request - Step 2

curl "https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats_report?report_run_id=ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6" -H "Authorization: Bearer  meowmeowmeow"

Report is running

{
  "request_status": "SUCCESS",
  "request_id": "<ID>",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6",
        "async_status": "RUNNING",
        "result": ""
      }
    }
  ]
}

Report is completed

{
  "request_status": "SUCCESS",
  "request_id": "<ID>",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6",
        "async_status": "COMPLETED",
        "result": "https://data-transfer.snapads.com/async-report/dpa_full/ASYNC_STATS:0efa41e1-5087-48af-8dbc-2cf8aefasdf66e6/4a6csdf1-3234-484b-b2cf-eeb6f1a63c3f.csv"
      }
    }
  ]
}

Top-K report for DPA

To support UI reporting and understand the performance of DPA among products with the highest level of spend, Snapchat supports a Top-K report, which will return the top 50 products per entity by impression volume (Campaign, Ad Set, and Ad). This API is similar to the standard reporting API used for non DPA ads.

Additional Request Parameters

These are the specific request parameters necessary to call the DPA Async report API

Attribute	Values
report_dimension	product_topk

curl "https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats?breakdown=campaign&granularity=TOTAL&swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY&start_time=2020-03-17T00:00:00-07:00&end_time=2020-03-25T00:00:00-07:00&fields=product_impressions,swipes,spend,total_installs,conversion_purchases&position_stats=false&platform_stats=false&report_dimension=product_topk&omit_empty=true" -H "Authorization: Bearer meowmeowmeow"

{
    "request_status": "SUCCESS",
    "request_id": "5fb4467d00ff07d2b1b1968d810001737e616473617069736300016275696c642d36393939316436622d312d3430332d3100010142",
    "total_stats": [
        {
            "sub_request_status": "SUCCESS",
            "total_stat": {
                "id": "<ID>",
                "type": "AD_ACCOUNT",
                "granularity": "TOTAL",
                "swipe_up_attribution_window": "28_DAY",
                "view_attribution_window": "1_DAY",
                "start_time": "2020-10-27T00:00:00.000-07:00",
                "end_time": "2020-10-29T00:00:00.000-07:00",
                "finalized_data_end_time": "2020-11-17T00:00:00.000-08:00",
                "breakdown_stats": {
                    "campaign": [
                        {
                            "id": "<CAMPAIGN_ID>",
                            "type": "CAMPAIGN",
                            "granularity": "TOTAL",
                            "start_time": "2020-10-27T00:00:00.000-07:00",
                            "end_time": "2020-10-29T00:00:00.000-07:00",
                            "dimension_stats": [
                                {
                                    "product_id": "56e39d8f1b0dd675f10e0131",
                                    "product_impressions": 84051
                                },
                                {
                                    "product_id": "577dfc15dac4a378150ebab0",
                                    "product_impressions": 55271
                                },
                                {
                                    "product_id": "5694f07db06a78118dd2bbae",
                                    "product_impressions": 47643
                                },
                                {
                                    "product_id": "56dff400cec25a1a9e1271cd",
                                    "product_impressions": 26599
                                },
                                {
                                    "product_id": "56eebe757505925c618e9807",
                                    "product_impressions": 23737
                                },
                                {
                                    "product_id": "569cbb6f16805211bb1f7750",
                                    "product_impressions": 21171
                                },
                                {
                                    "product_id": "57a6fad104e0d075a6084059",
                                    "product_impressions": 19274
                                },
                                {
                                    "product_id": "57ab01b93999d9602c743b8e",
                                    "product_impressions": 12256
                                },
                                {
                                    "product_id": "57ad3c3fd227704b8bab09dc",
                                    "product_impressions": 12248
                                },
                                {
                                    "product_id": "57a6c97c5bd8ec7787ea328f",
                                    "product_impressions": 11340
                                },
                                {
                                    "product_id": "569f56793fe3625b0cf56bd9",
                                    "product_impressions": 7433
                                },
                                {
                                    "product_id": "56e14676ae8c93398a13a7d3",
                                    "product_impressions": 6597
                                },
                                {
                                    "product_id": "56f24379f5f899740ec4c0b5",
                                    "product_impressions": 6438
                                },
                                {
                                    "product_id": "575645a524a8f27640d3d40c",
                                    "product_impressions": 6419
                                },
                                {
                                    "product_id": "5700b35e5581e05ce0b4adc3",
                                    "product_impressions": 6056
                                },
                                {
                                    "product_id": "576130685d3faf6218fd8dac",
                                    "product_impressions": 5701
                                },
                                {
                                    "product_id": "579eba20a037085566e39683",
                                    "product_impressions": 1980
                                },
                                {
                                    "product_id": "57adae01b1ce26244dd4012c",
                                    "product_impressions": 1707
                                },
                                {
                                    "product_id": "57a02216e3ada7734f02b275",
                                    "product_impressions": 1185
                                },
                                {
                                    "product_id": "579b220904af45576fae20a3",
                                    "product_impressions": 1083
                                },
                                {
                                    "product_id": "56b1adcdac5bc550738df9fb",
                                    "product_impressions": 857
                                },
                                {
                                    "product_id": "57623c6d823409625004be5e",
                                    "product_impressions": 736
                                },
                                {
                                    "product_id": "57b14c09689ce95b71558fff",
                                    "product_impressions": 671
                                },
                                {
                                    "product_id": "5779ced99bfad279a9783889",
                                    "product_impressions": 573
                                },
                                {
                                    "product_id": "56c29339a3537416ae4b7822",
                                    "product_impressions": 556
                                }
                                ...
                            ]
                        }
                    ]
                },
                "split_results": []
            }
        }
    ]
}

Viewability Metrics

Viewability Metrics are available given the following criteria;

• Metrics are available from the 1 April 2021
• Available in all granularities (HOUR, DAY, TOTAL, LIFETIME)
• Metrics cannot be broken down by Insights
• Story Ads are not covered by these metrics

Metrics

Metric	API field	Description
Viewable Impressions	viewable_impressions	Number of impressions that were 100% viewable on a user's screen for 1 second for display ads or 2 seconds for video ads.
Non-Viewable Impressions	non_viewable_impressions	Number of impressions that did not meet the criteria for a viewable impression
Viewable Rate	viewable_rate	The percentage of the time that your paid Snap Ad impression met the qualifying viewable impression criteria
Measured Impressions	measured_impressions	Number of impressions that were measured for viewability
Gross Impressions	gross_impressions	Total impressions delivered, this includes invalid traffic which is excluded from spend & all other delivery metrics.
Paid Impressions	paid_impressions	The total number of times your ad was served to a Snapchatter. Tracked when the ad fully renders on a device for the first time during a Snapchatter’s viewing session. These impressions are net of invalid traffic.

Audience filters

Audience filters were deprecated on 1 February 2023, this reporting information is preserved for Audience Filters created prior to the deprecation.

Field	Description	Availability
paid_impressions	The total number of times your ad was served to a Snapchatter. Tracked when the ad fully renders on a device for the first time during a Snapchatter's viewing session	Real Time
earned_impressions	The number of times your ad was viewed after being shared by a Snapchatter via Chat or Stories	Within 24 hours
shares	The number of times your ad was shared via Chat or Stories	Real Time
saves	The number of times your ad was saved to Memories	Real Time
spend	The total spend delivered in microcurrency	Real Time
uniques	The number of unique paid impressions	Within 24 hours

Stats are available at the Ad, Ad Squad and Campaign levels and are supported for all granularities: HOUR, DAY, TOTAL and LIFETIME.

curl "https://adsapi.snapchat.com/v1/adsquads/419d41d7-e4d4-4c13-803c-55e140a0ec1c/stats?granularity=LIFETIME&fields=paid_impressions,shares,saves,spend,uniques,earned_impressions"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "59b9cde600ff04b518a3c18db20001737e616473617069736300016275696c642d31386433356533662d312d3130302d3100010148",
  "lifetime_stats": [
    {
      "sub_request_status": "SUCCESS",
      "lifetime_stat": {
        "id": "419d41d7-e4d4-4c13-803c-55e140a0eb1c",
        "type": "AD_SQUAD",
        "granularity": "LIFETIME",
        "stats": {
          "uniques": 186219,
          "spend": 247184000,
          "earned_impressions": 196140,
          "paid_impressions": 199290,
          "shares": 5762,
          "saves": 799
        },
        "start_time": "2016-09-26T00:00:00.000-07:00",
        "end_time": "2017-09-13T00:00:00.000-07:00",
        "finalized_data_end_time": "2017-09-13T00:00:00.000-07:00"
      }
    }
  ]
}

HTTP Request

GET https://adsapi.snapchat.com/v1/adsquads/{adsquad-id}/stats

Parameters

Parameter	Description
adsquad-id	Audience filter Ad squad ID

Create Lead Gen Report

This request initiates a lead gen report for an Ad Account given the selected start time and end time, the request returns a Report id in the form of report_run_id which is then used to retrieve the report itself.

Data collected via Lead Gen Ads is not stored for more than 30 days, this also means that the start time can't be more than 30 days in the past.

curl -X POST  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/leads_report?async_format=csv&start_time=2021-12-01T00:00:00-07:00&end_time=2021-12-14T00:00:00-07:00

The above command returns a report_run_id:

{
  "request_status": "SUCCESS",
  "request_id": "61b8c10a00ff08449824e366290001737e616473617069736300016275696c642d38333537336364642d312d3530332d3000010159",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:2e480f4f-0c2a-463c-a883-841f88175449",
        "async_status": "STARTED"
      }
    }
  ]
}

HTTP Request

POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/leads_report

Parameters

Parameter	Default value	Description
async_format	csv
start_time		Start time in ISO format
end_time		End time in ISO format

Fetch Lead Gen Report

This request uses the report_run_id in order to fetch the status of a report.

If the report is ready the request returns the URL of a list of leads in CSV format, the async_status indicates whether the report is completed and ready to be downloaded. If the report is ready the value of the async_status is COMPLETED, if the report is still running the async_status will be RUNNING.

When a report is completed the url for downloading the data is found in the result attribute. This URL is valid for 48 hours.

curl "https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/leads_report?report_run_id=ASYNC_STATS:7766eab2-643e-4117-8b58-c9ee3fe854f3" \
  -H "Authorization: Bearer meowmeowmeow"

Example #1 - Report in progress

{
  "request_status": "SUCCESS",
  "request_id": "61b8bf2d00ff07c8f092caf50b0001737e616473617069736300016275696c642d38333537336364642d312d3530332d3000010142",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:7766eae2-643e-4117-8b58-c9ee3fe854f3",
        "async_status": "RUNNING"
      }
    }
  ]
}

curl "https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/leads_report?report_run_id=ASYNC_STATS:7766eeb2-643e-4117-8b58-c9ee3fe854f3" \
  -H "Authorization: Bearer meowmeowmeow"

Example #2 - Completed report

{
  "request_status": "SUCCESS",
  "request_id": "61b8bf2d00ff07c8f092caf50b0001737e616473617069736300016275696c642d38333537336364642d312d3530332d3000010142",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:7766eeb2-643e-4117-8b58-c9ee3fe854f3",
        "async_status": "COMPLETED",
        "result": "https://data-transfer.snapads.com/async-report/native_lead/ASYNC_STATS:7766eeb2-643e-4117-8b58-c9ee3fe854f3/00ea875b-1645-4fe8-8825-aa7a351b260b.csv"
      }
    }
  ]
}

HTTP Request

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/leads_report

Parameters

Parameter	Default value	Description
report_run_id	Report id	The Report id returned by API request to initiate a report

Lead Gen Report

This is a list of fields in the Lead Gen Report and their properties.

Field Name	Type	Max Length	Required?	Description	Example
Date	Datetime	17	Yes	Date that lead was submitted. The timestamp is truncated to the beginning of the local day and the time is always "00:00:00" Format: "yyyy-MM-dd 00:00:00"	2022-05-11 00:00:00
Ad Account Id	String	36	Yes	Ad account ID associated with the ad that generated the lead. Hyphen separated UUID string.	f0d4666f-9f60-4df7-94c8-423ca55b2a17
Campaign Id	String	36	Yes	Campaign ID associated with ad that generated the lead. Hyphen separated UUID string.	033fe5aa-59b4-423d-8ab5-b7a7cf6c5242
Ad Set Id	String	36	Yes	Ad Set ID associated with ad that generated the lead. Hyphen separated UUID string.	ebad6081-f387-4bce-b6dc-9ea4d2cbefbc
Ad Id	String	36	Yes	Ad ID associated with ad that generated the lead. Hyphen separated UUID string.	ca72035c-9f8d-409b-abee-5e2e0c943f9c
First Name	String		Yes	First name of Snapchat User	Jane
Last Name	String		Yes	Last name of Snapchat User	Smith
Phone Number	String		Yes (Either Email Address or Phone Number)	ex: 818-555-1234, +13105558765 *Not all formatted the same	818-555-1234 +13105558765
Email Address	String		Yes (Either Email Address or Phone Number)	Email address of Snapchat user	johndoe@gmail.com
Address Line 1	String		No	Address of Snapchat user, Line 1	19330 25th Ave
Address Line 2	String		No	Address of Snapchat user, Line 2	Unit 3
Address Level 1	String		No	Address city or town	Seattle
Address Level 2	String		No	Address state, province, or region	WA
Postal Code	String		No	Postal code of Snapchat user	94012
Birthday	Date	10	No	Snapchat user's birthdate. Formatted "MM/DD/YYYY"	05/20/1998
Job Title	String		No	Job title	Marketing Manager
Company Name	String		No	Company name	Snap, Inc.
Custom Field 1	String		No	Can be one of the following based on the type of Custom Question: Single-select: key-value object that contains the answer that the user selected and "true": {answer:true} Multi-select: key-value object that contains all of the answers that the user selected and "true": {answer1:true, answer2: true, answer3: true, answer4:true} Short Answer: String that contains the answer that the user entered into the form. Date Widget: The date that the user entered in the format "MM/DD/YYYY"	{Pizza:true} {Pizza:true, Sushi:true, Hamburgers:true} This is what I entered into the form 01/02/2022
Custom Field 2	String		No	"
Custom Field 3	String		No	"
Custom Field 4	String		No	"
Custom Field 5	String		No	"
Custom Field 6	String		No	"
Custom Field 7	String		No	"
Custom Field 8	String		No	"
Consent 1	String	Disclaimers: 80 Answer: 5 Total: 86	No	Disclaimer in the consent section of the form and the user's response. Data is a key-value string in the following format: disclaimer:answer "answer" will be "true" if the user consented and "false" if they did not consent.	do you consent?:true https://www.example.com:false
Consent 2	String	Disclaimers: 80 Answer: 5 Total: 86	No	Disclaimer in the consent section of the form and the user's response. Data is a key-value string in the following format: disclaimer:answer "answer" will be "true" if the user consented and "false" if they did not consent.	do you consent?:true https://www.example.com:false
Preferred Status	String	Preferred | Non-Preferred	No	Indicates whether this lead is preferred or non-preferred based on the responses to the qualifying questions.	Preferred

Example Lead Gen Report

Here is an example Lead Gen Report .csv file. All the sample data is made-up; no actual user data is included.