Skip to main content

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

AttributeDescriptionRequiredPossible Values
breakdownObject-level breakdownOad, adsquad [Only available on Campaign Stats endpoint], campaign [Only available on Ad Account Stats endpoint]
asyncDesignates processing of report to be asynchronousOtrue
async_formatDesignates the response format of asynchronous reporting, can be either a csv or excel fileOcsv, excel
fieldsMetrics requested (comma-separated)O(see table below; default: impressions,spend)
end_timeEnd Time (ISO 8601)R*
start_timeStart Time (ISO 8601)R*
granularityMetrics granularityRTOTAL, DAY, HOUR, LIFETIME
testReturn Sample (fake) StatsOfalse (default), true
dimensionInsight-level breakdownOGEO, DEMO, INTEREST, DEVICE
pivotThe pivot to be used for insights breakdownOcountry, region, dma, gender, age_bucket, interest_category_id, interest_category_name, operating_system, make, model
action_report_timeSpecifies the principle for conversion reportingOconversion (default), impression**
swipe_up_attribution_windowAttribution window for swipe upsO1_DAY, 7_DAY, 28_DAY (default)
view_attribution_windowAttribution window for viewsOnone, 1_HOUR, 3_HOUR, 6_HOUR, 1_DAY (default), 7_DAY, 28_DAY***
position_statsPosition metric breakdown for Snap Ads within a Story AdOtrue
omit_emptyOmits 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 returnedOfalse (default), true
conversion_source_typesConversion source breakout by platformOweb, app, offline**, total, total_off_platform, total_on_platform
limitThe limit parameter specifies how many entities should be returned per pageOinteger, 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

AttributeDescription
finalized_data_end_timeThis 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_timeThis 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.
pagingIf 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 NameDescription
impressionsImpression Count
swipesSwipe-Up Count
view_time_millisUse screen_time_millis instead. Total Time Spent on top Snap Ad (milliseconds)
screen_time_millisTotal Time Spent on top Snap Ad (milliseconds)
quartile_1Video Views to 25%
quartile_2Video Views to 50%
quartile_3Video Views to 75%
view_completionVideo Views to completion
spendAmount Spent (micro-currency)
coupon_used_localAmount Spent via Coupon in the assigned currency of Ad Account (micro-currency)
coupon_used_usdAmount Spent via Coupon in USD (micro-currency)
video_viewsThe 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

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
ParameterDescriptionRequiredPossible values
asyncDesignates processing of report to be asynchronousRtrue
async_formatDesignates the response format of asynchronous reporting, can be either a csv or excel fileOcsv (default), excel
granularityMetrics granularityOTOTAL, 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

ParameterDescriptionRequiredPossible values
report_run_idThe id of the report to be fetchedR

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

AttributeDescriptionPossible values
async_formatDefines the returned format of the reportcsv,excel
idsTwo 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 AccountComma separated string of up to 100 Campaign ID/Ad Squad ID/Ad ID values
overlapIndicates whether an overlap calculation should take placetrue
overlap_typeSpecifies the entity level of the overlap calculation, you cannot use two different types of entities in one reportcampaign, ad_squad, ad
start_timeStart time of the reportStart time in ISO format
end_timeEnd time of the reportEnd 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.
ABCDEF
1Reached by all6,029
2Total Uniques Reached212,351
3Campaign Id 1Campaign Name 1Campaign Id 2Campaign Name 2Reach TypeReach Value
411111111-1111-1111-111111111111Wellness Campaign11111111-1111-1111-111111111111Wellness CampaignTotal160.356
511111111-1111-1111-111111111111Wellness Campaign222222222-2222-2222-2222-2222222222Beauty CampaignOverlap6,029
611111111-1111-1111-111111111111Wellness Campaign11111111-1111-1111-111111111111Wellness CampaignUnique154,327
7222222222-2222-2222-2222-2222222222Beauty Campaign222222222-2222-2222-2222-2222222222Beauty CampaignTotal60,746
8222222222-2222-2222-2222-2222222222Beauty Campaign11111111-1111-1111-111111111111Wellness CampaignOverlap6,029
9222222222-2222-2222-2222-2222222222Beauty Campaign222222222-2222-2222-2222-2222222222Beauty CampaignUnique54,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 NameSnap Ad TypesDescription
android_installsAPP_INSTALL# of Android App Installs
attachment_avg_view_time_millisAny AttachmentAverage Attachment View Time (milli-seconds)
attachment_frequencyAny AttachmentAverage # of Attachment Views per User Reached
attachment_quartile_1LONGFORM_VIDEOLong Form Video Views to 25%
attachment_quartile_2LONGFORM_VIDEOLong Form Video Views to 50%
attachment_quartile_3LONGFORM_VIDEOLong Form Video Views to 75%
attachment_total_view_time_millisAny AttachmentTotal Attachment View Time (milli-seconds)
attachment_uniquesAny Attachment# of unique attachment impressions
attachment_view_completionLONGFORM_VIDEOLong Form Video Views to completion
attachment_video_viewsLONGFORM_VIDEOLong Form Video Attachment Views, viewed for at least 10 consecutive seconds or reached 97% of the Long Form Video duration
avg_view_time_millisAnyUse avg_screen_time_millis instead. Average Top Snap view time per User Reached
avg_screen_time_millisAnyAverage Top Snap view time across all impressions
frequencyAnyAverage # of Impressions per User Reached
ios_installsAPP_INSTALL# of iOS App Installs
swipe_up_percentAny Attachment% of Impressions that Swiped-Up
total_installsAPP_INSTALLTotal # of App Installs
uniquesAny# of unique impressions
video_views_time_basedAnyThe total number of impressions that meet the qualifying video view criteria of at least 2 seconds, not including swipe ups
video_views_15sAnyThe 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_opensSTORY# of times users tapped on the ad tile in the feed to view the Story Ad
story_completesSTORY# 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_clicksAny# of times users tapped the logo in the upper corner taking them to the profile page
position_impressionsSTORY# the impression number for this story ad position
position_screen_time_millisSTORY# the total view time in milliseconds for this story ad position
position_swipe_up_percentSTORY# the swipe up rate for this story ad position
avg_position_screen_time_millisSTORY# the average view time for this story ad position
sharesLENS, AD_TO_LENS, FILTER# of times lens/filter was shared in a Chat or Story
savesLENS, AD_TO_LENS, FILTER# of times lens/filter was saved to Memories
paid_impressionsLENS, FILTER, AD_TO_LENSThe 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_impressionsLENS, FILTER, AD_TO_LENSThe number of times your ad was viewed after being shared by a Snapchatter via Chat or Stories
total_impressionsLENSThe total number of impressions (Paid and Earned)
play_time_millisLENSThe total amount of time in where Snapchatters interacted with your Lens in the camera (milliseconds)
total_reachLENSThe number of unique Snapchatters who viewed your Lens ad, either by receiving a Paid or Earned Impression.
earned_reachLENS, FILTER, AD_TO_LENSThe number of unique Snapchatters who viewed the filter/lens after being shared by a Snapchatter via Chat or Stories
native_leadsLEAD_GENERATIONTotal 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

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 CategoryDescriptionUser groups in category
Fully Tracked groupThese user groups are fully supported for the features listed below.Android, iOS opted-in users
Partially tracked groupThese 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/GranularityConversion 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

SupportedSupported

Time of Exposure
action_report_time=impression

SupportedSupported

Event Source


(web/app/offline)

SupportedSupported

Entity


(campaign/ad set/ad)

SupportedSupported
AgeSupportedSupported
GenderSupportedSupported
Age, GenderSupportedSupported
CountrySupportedSupported
OSSupportedSupported
Platform (on/off snapchat)SupportedSupported
Region (US Only)SupportedNOT Supported
DMA (US Only)SupportedNOT Supported
Device MakeSupportedNOT Supported
SLC (lifestyle category)SupportedNOT Supported
ProductSupportedNOT Supported
Hourly ConversionsSupportedNOT Supported
Daily, Total, Lifetime ConversionSupportedSupported

Swipe Up Window:
1_DAY, 7_DAY, 28_DAY


View Thru Window:
1_DAY, 7_DAY

SupportedSupported

View Through Window:
1_HOUR, 3_HOUR, 6_HOUR

SupportedSupported
View Through Window: 28_DAY*NOT SupportedNOT Supported

*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.

NameDescription
conversion_total_installs_sk_ad_networkTotal App Installs tracked via SKAd Network
conversion_ios_installs_sk_ad_networkExact 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_networkSkAdNetwork conversion events with unknown Conversion Values
conversion_assist_install_sk_ad_networkThe 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_networkThe 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.

NameDescription
conversion_total_installs_sk_ad_network_viewTotal App Installs tracked via SKAd Network
conversion_ios_installs_sk_ad_network_viewExact 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_viewSkAdNetwork conversion events with unknown Conversion Values
conversion_assist_install_sk_ad_network_viewThe 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_viewThe 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.

NameDescription
conversion_total_installs_sk_ad_network_totalTotal App Installs tracked via SKAd Network
conversion_ios_installs_sk_ad_network_totalExact 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_totalSkAdNetwork conversion events with unknown Conversion Values
conversion_assist_install_sk_ad_network_totalThe 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_totalThe 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.

FieldsGranularityDescription
conversion_purchasesAny# of attributed "PURCHASE" conversion events
conversion_purchases_valueAnyValue of attributed "PURCHASE" conversion events (microcurrency in Ad Account's currency)
conversion_saveAny# of attributed "SAVE" conversion events
conversion_save_valueAnyValue of attributed "SAVE" conversion events (microcurrency in Ad Account's currency)
conversion_start_checkoutAny# of attributed "START_CHECKOUT" conversion events
conversion_start_checkout_valueAnyValue of attributed "START_CHECKOUT" conversion events (microcurrency in Ad Account's currency)
conversion_add_cartAny# of attributed "ADD_CART" conversion events
conversion_add_cart_valueAnyValue of attributed "ADD_CART" conversion events (microcurrency in Ad Account's currency)
conversion_view_contentAny# of attributed "VIEW_CONTENT" conversion events
conversion_view_content_valueAnyValue of attributed "VIEW_CONTENT" conversion events (microcurrency in Ad Account's currency)
conversion_add_billingAny# of attributed "ADD_BILLING" conversion events
conversion_add_billing_valueAnyValue of attributed "ADD_BILLING" conversion events (microcurrency in Ad Account's currency)
conversion_sign_upsAny# of attributed "SIGN_UP" conversion events
conversion_sign_ups_valueAnyValue of attributed "SIGN_UP" conversion events (microcurrency in Ad Account's currency)
conversion_searchesAny# of attributed "SEARCH" conversion events
conversion_searches_valueAnyValue of attributed "SEARCH" conversion events (microcurrency in Ad Account's currency)
conversion_level_completesAny# of attributed "LEVEL_COMPLETE" conversion events
conversion_level_completes_valueAnyValue of attributed "LEVEL_COMPLETE" conversion events (microcurrency in Ad Account's currency)
conversion_app_opensAny# of attributed "APP_OPEN" conversion events
conversion_app_opens_valueAnyValue of attributed "APP_OPEN" conversion events (microcurrency in Ad Account's currency)
conversion_page_viewsAny# of attributed "PAGE_VIEW" conversion events
conversion_page_views_valueAnyValue of attributed "PAGE_VIEW" conversion events (microcurrency in Ad Account's currency)
conversion_subscribeAny# of attributed "SUBSCRIBE" conversion events
conversion_subscribe_valueAnyValue of attributed "SUBSCRIBE" conversion events (microcurrency in Ad Account's currency)
conversion_ad_clickAny# of attributed "AD_CLICK" conversion events
conversion_ad_click_valueAnyValue of attributed "AD_CLICK" conversion events (microcurrency in Ad Account's currency)
conversion_ad_viewAny# of attributed "AD_VIEW" conversion events
conversion_ad_view_valueAnyValue of attributed "AD_VIEW" conversion events (microcurrency in Ad Account's currency)
conversion_complete_tutorialAny# of attributed "COMPLETE_TUTORIAL" conversion events
conversion_complete_tutorial_valueAnyValue of attributed "COMPLETE_TUTORIAL" conversion events (microcurrency in Ad Account's currency)
conversion_inviteAny# of attributed "INVITE" conversion events
conversion_invite_valueAnyValue of attributed "INVITE" conversion events (microcurrency in Ad Account's currency)
conversion_loginAny# of attributed "LOGIN" conversion events
conversion_login_valueAnyValue of attributed "LOGIN" conversion events (microcurrency in Ad Account's currency)
conversion_shareAny# of attributed "SHARE" conversion events
conversion_share_valueAnyValue of attributed "SHARE" conversion events (microcurrency in Ad Account's currency)
conversion_reserveAny# of attributed "RESERVE" conversion events
conversion_reserve_valueAnyValue of attributed "RESERVE" conversion events (microcurrency in Ad Account's currency)
conversion_achievement_unlockedAny# of attributed "ACHIEVEMENT_UNLOCKED" conversion events
conversion_achievement_unlocked_valueAnyValue of attributed "ACHIEVEMENT_UNLOCKED" conversion events (microcurrency in Ad Account's currency)
conversion_add_to_wishlistAny# of attributed "ADD_TO_WISHLIST" conversion events
conversion_add_to_wishlist_valueAnyValue of attributed "ADD_TO_WISHLIST" conversion events (microcurrency in Ad Account's currency)
conversion_spend_creditsAny# of attributed "SPENT_CREDITS" conversion events
conversion_spend_credits_valueAnyValue of attributed "SPENT_CREDITS" conversion events (microcurrency in Ad Account's currency)
conversion_rateAny# of attributed "RATE" conversion events
conversion_rate_valueAnyValue of attributed "RATE" conversion events (microcurrency in Ad Account's currency)
conversion_start_trialAny# of attributed "START_TRIAL" conversion events
conversion_start_trial_valueAnyValue of attributed "START_TRIAL" conversion events (microcurrency in Ad Account's currency)
conversion_list_viewAny# of attributed "LIST_VIEW" conversion events
conversion_list_view_valueAnyValue of attributed "LIST_VIEW" conversion events (microcurrency in Ad Account's currency)
conversion_visitAny# of attributed "VISIT" conversion events
conversion_visit_valueAnyValue of attributed "VISIT" conversion events (microcurrency in Ad Account's currency)
custom_event_1Any# of attributed "CUSTOM_EVENT_1" conversion events
custom_event_1_valueAnyValue of attributed "CUSTOM_EVENT_1" conversion events (microcurrency in Ad Account's currency)
custom_event_2Any# of attributed "CUSTOM_EVENT_2" conversion events
custom_event_2_valueAnyValue of attributed "CUSTOM_EVENT_2" conversion events (microcurrency in Ad Account's currency)
custom_event_3Any# of attributed "CUSTOM_EVENT_3" conversion events
custom_event_3_valueAnyValue of attributed "CUSTOM_EVENT_3" conversion events (microcurrency in Ad Account's currency)
custom_event_4Any# of attributed "CUSTOM_EVENT_4" conversion events
custom_event_4_valueAnyValue of attributed "CUSTOM_EVENT_4" conversion events (microcurrency in Ad Account's currency)
custom_event_5Any# of attributed "CUSTOM_EVENT_5" conversion events
custom_event_5_valueAnyValue 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

Example: 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 NameCustom Conversion IDID for reporting
kitten_sales0029904941conversion_0029904941
european_puppy_sales1828361131conversion_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 NameCustom Conversion IDID for reporting value
kitten_sales0029904941conversion_0029904941_value
european_puppy_sales1828361131conversion_1828361131_value

Pattern:

GET /adaccounts/{ad_account_id}/stats

Example I - 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 II - 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
}
}
]
}
}
}
]
}

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.

Conversion breakout

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

ParameterDescription
totalAll conversion events
webEvents reported via the Snap Pixel SDK
appEvents reported within an App
offlineEvents reported from an offline source (in-store)
totalThe combined events reported for web, app, offline, and on platform (Stores and Profiles)
total_off_platformThe combined events reported for web, app, and offline
total_on_platformEvents 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

MetricReal timeHOURDAYTOTALLIFETIME
android_installsYES

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_frequencyYESNOYESYES. Available from 1st January 2021YES
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

ParameterDefaultDescription
ad_account_idAd 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

ParameterDefaultDescription
campaign_idCampaign 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

ParameterDefaultDescription
adsquad_idAd 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

ParameterDefaultDescription
ad_idAd 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
CreativeTypeReporting availability
Snap AdSNAP_ADYes
Snap Ad with attachmentAPP_INSTALL, WEB_VIEW, DEEP_LINKYes
Preview CreativePREVIEWNo
MediaTypeReporting availability
Top SnapIMAGEYes
Top SnapVIDEOYes
Lens LENSLENS_PACKAGEYes
Story TileIMAGENo
Creative elementIMAGENo

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

ParameterDefaultDescription
creative_idCreative 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

CategoryAPI Dimension (report_dimension)ConditionsMetrics availability

Geo

countryMetrics broken down by ISO country codeDelivery/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

genderMetrics broken down by genderDelivery/Conversion
age**Metrics broken down by age buckets**Delivery/Conversion
age,genderMetrics broken down by age and genderDelivery/Conversion

Device

osDevice Operating SystemDelivery/Conversion
os,country

Metrics broken down by Device Operating System and ISO country code*

Delivery
makeDevice MakeDelivery
Interestlifestyle_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

MetricAPI fieldDescription
Paid ImpressionsimpressionsImpression Count
Unique ImpressionsuniquesUnique Impressions Count
Swipe UpsswipesSwipe-Up Count
25% Quartilequartile_1Video Views to 25%
50% Quartilequartile_2Video Views to 50%
75% Quartilequartile_3Video Views to 75%
Completionsview_completionVideo Views to completion
SpendspendAmount Spent (micro-currency)
Video Viewsvideo_viewsThe 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 Uniquesattachment_uniquesAttachment Uniques
25% Attachment Quartileattachment_quartile_1Long Form Video Views to 25%
50% Attachment Quartileattachment_quartile_2Long Form Video Views to 50%
75% Attachment Quartileattachment_quartile_3Long Form Video Views to 75%
Attachment Completionsattachment_view_completionLong Form Video Views to completion
Attachment View Timeattachment_total_view_time_millisTotal Attachment View Time (milli-seconds)
Attachment Video Viewsattachment_video_viewsLong Form Video Attachment Views
Story Opensstory_opens# of times users tapped on the ad tile in the feed to view the Story Ad
Story Completesstory_completes# of times users viewed through to the last Snap of your Story Ad
Sharesshares# of times lens/filter was shared in a Chat or Story
Savessaves# of times lens/filter was saved to Memories

*landing_page_views are available from 10 December 2024

Conversion Metrics

MetricAPI fieldDescription
Installstotal_installsTotal # of App Installs
Purchasesconversion_purchases# of attributed “PURCHASE” conversion events**
Purchase Valueconversion_purchases_valueValue of attributed “PURCHASE” conversion events (microcurrency in Ad Account’s currency)**
Savesconversion_save# of attributed “SAVE” conversion events**
Start Checkoutconversion_start_checkout# of attributed “START_CHECKOUT” conversion events**
Add To Cartconversion_add_cart# of attributed “ADD_CART” conversion events**
View Contentconversion_view_content# of attributed “VIEW_CONTENT” conversion events**
Add Billingconversion_add_billing# of attributed “ADD_BILLING” conversion events**
Sign Upsconversion_sign_ups# of attributed “SIGN_UP” conversion events**
Searchesconversion_searches# of attributed “SEARCH” conversion events**
Level Completesconversion_level_completes# of attributed “LEVEL_COMPLETE” conversion events**
App Opensconversion_app_opens# of attributed “APP_OPEN” conversion events**
Page Viewsconversion_page_views# of attributed “PAGE_VIEW” conversion events**
Subscribesconversion_subscribe# of attributed "SUBSCRIBE" conversion events++
Ad Clicksconversion_ad_click# of attributed “CONVERSION_AD_CLICK” conversion events++
Ad Viewsconversion_ad_view# of attributed “CONVERSION_AD_VIEW” conversion events++
Completed Tutorialsconversion_complete_tutorial# of attributed “CONVERSION_COMPLETE_TUTORIAL” conversion events++
Invites Sentconversion_invite# of attributed “CONVERSION_INVITE” conversion events++
Loginsconversion_login# of attributed “CONVERSION_LOGIN” conversion events++
Sharesconversion_share# of attributed “CONVERSION_SHARE” conversion events++
Reservationsconversion_reserve# of attributed “CONVERSION_RESERVE” conversion events++
Achievements Unlockedconversion_achievement_unlocked# of attributed “CONVERSION_ACHIEVEMENT_UNLOCKED” conversion events++
Adds to Wishlistconversion_add_to_wishlist# of attributed “CONVERSION_ADD_TO_WISHLIST” conversion events++
Credits Spentconversion_spend_credits# of attributed “CONVERSION_SPEND_CREDITS” conversion events++
Rates Submittedconversion_rate# of attributed “CONVERSION_RATE” conversion events++
Trial Startsconversion_start_trial# of attributed “CONVERSION_START_TRIAL” conversion events++
Lists Viewedconversion_list_view# of attributed “LIST_VIEW” conversion events++
Store Visitsconversion_visit# of attributed “VISIT” conversion events++
Custom Event 1custom_event_1# of attributed “CUSTOM_EVENT_1” conversion events++
Custom Event 2custom_event_2# of attributed “CUSTOM_EVENT_2” conversion events++
Custom Event 3custom_event_3# of attributed “CUSTOM_EVENT_3” conversion events++
Custom Event 4custom_event_4# of attributed “CUSTOM_EVENT_4” conversion events++
Custom Event 5custom_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

ParameterPossible valuesDescription
ad_account_idAd Account ID
report_dimensioncountry,region,dmaThe 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 2025Description
13-1713-17
18-2018-20
21-2421-24
25-3425-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

ParameterPossible valuesDescription
ad_account_idAd Account ID
report_dimensionage,genderThe 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.

DimensionPivotRequired/OptionalConditions

GEO

countryYesNone
regionNodma has to be queried with region
dmaNodma has to be queried with region

DEMO

genderNo

At least one of gender or age_bucket has to be specified if dimension is DEMO

age_bucketNo

At least one of gender or age_bucket has to be specified if dimension is DEMO

INTEREST

interest_category_idYesNone
interest_category_nameNoNone

DEVICE

operating_systemYesNone
makeNomodel has to be queried with make
modelNomodel has to be queried with make

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

FieldDescription
impressionsImpression Count
impression_compositionThe percent of impressions served to the insights category
uniques# of unique impressions
unique_compositionThe percent of uniques served to the insights category
spendAmount spent (microcurrency)
swipesSwipe 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.

MetricSwipe variantEngaged View variantView variant
total_installstotal_installs_swipe_uptotal_installs_engaged_viewtotal_installs_view
android_installsandroid_installs_swipe_upandroid_installs_engaged_viewandroid_installs_view
ios_installsios_installs_swipe_upios_installs_engaged_viewios_installs_view
conversion_purchasesconversion_purchases_swipe_upconversion_purchases_engaged_viewconversion_purchases_view
conversion_purchases_valueconversion_purchases_value_swipe_upconversion_purchases_value_engaged_viewconversion_purchases_value_view
conversion_saveconversion_save_swipe_upconversion_save_engaged_viewconversion_save_view
conversion_start_checkoutconversion_start_checkout_swipe_upconversion_start_checkout_engaged_viewconversion_start_checkout_view
conversion_add_cartconversion_add_cart_swipe_upconversion_add_cart_engaged_viewconversion_add_cart_view
conversion_view_contentconversion_view_content_swipe_upconversion_view_content_engaged_viewconversion_view_content_view
conversion_add_billingconversion_add_billing_swipe_upconversion_add_billing_engaged_viewconversion_add_billing_view
conversion_sign_upsconversion_sign_ups_swipe_upconversion_sign_ups_engaged_viewconversion_sign_ups_view
conversion_searchesconversion_searches_swipe_upconversion_searches_engaged_viewconversion_searches_view
conversion_level_completesconversion_level_completes_swipe_upconversion_level_completes_engaged_viewconversion_level_completes_view
conversion_app_opensconversion_app_opens_swipe_upconversion_app_opens_engaged_viewconversion_app_opens_view
conversion_page_viewsconversion_page_views_swipe_upconversion_page_views_engaged_viewconversion_page_views_view
conversion_subscribeconversion_subscribe_swipe_upconversion_subscribe_engaged_viewconversion_subscribe_view
conversion_ad_clickconversion_ad_click_swipe_upconversion_ad_click_engaged_viewconversion_ad_click_view
conversion_ad_viewconversion_ad_view_swipe_upconversion_ad_view_engaged_viewconversion_ad_view_view
conversion_complete_tutorialconversion_complete_tutorial_swipe_upconversion_complete_tutorial_engaged_viewconversion_complete_tutorial_view
conversion_inviteconversion_invite_swipe_upconversion_invite_engaged_viewconversion_invite_view
conversion_loginconversion_login_swipe_upconversion_login_engaged_viewconversion_login_view
conversion_shareconversion_share_swipe_upconversion_share_engaged_viewconversion_share_view
conversion_reserveconversion_reserve_swipe_upconversion_reserve_engaged_viewconversion_reserve_view
conversion_achievement_unlockedconversion_achievement_unlocked_swipe_upconversion_achievement_unlocked_engaged_viewconversion_achievement_unlocked_view
conversion_add_to_wishlistconversion_add_to_wishlist_swipe_upconversion_add_to_wishlist_engaged_viewconversion_add_to_wishlist_view
conversion_spend_creditsconversion_spend_credits_swipe_upconversion_spend_credits_engaged_viewconversion_spend_credits_view
conversion_rateconversion_rate_swipe_upconversion_rate_engaged_viewconversion_rate_view
conversion_start_trialconversion_start_trial_swipe_upconversion_start_trial_engaged_viewconversion_start_trial_view
conversion_list_viewconversion_list_view_swipe_upconversion_list_view_engaged_viewconversion_list_view_view
custom_event_1custom_event_1_swipe_upcustom_event_1_engaged_viewcustom_event_1_view
custom_event_2custom_event_2_swipe_upcustom_event_2_engaged_viewcustom_event_2_view
custom_event_3custom_event_3_swipe_upcustom_event_3_engaged_viewcustom_event_3_view
custom_event_4custom_event_4_swipe_upcustom_event_4_engaged_viewcustom_event_4_view
custom_event_5custom_event_5_swipe_upcustom_event_5_engaged_viewcustom_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 windowSwipe window 1_DAYSwipe window 7_DAYSwipe window 28_DAY
none*AllowedAllowedAllowed
1_HOURAllowedAllowedAllowed
3_HOURAllowedAllowedAllowed
6_HOURAllowedAllowedAllowed
1_DAYAllowedAllowedAllowed
7_DAYNot AllowedAllowedAllowed
28_DAYNot AllowedNot AllowedAllowed

*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_view,conversion_purchases,conversion_purchases_swipe_up,conversion_purchases_view&swipe_up_attribution_window=28_DAY&view_attribution_window=7_DAY&start_time=2017-11-10T00:00:00-08:00&end_time=2017-11-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": "2017-11-10T00:00:00.000-08:00",
"end_time": "2017-11-12T00:00:00.000-08:00",
"finalized_data_end_time": "2017-11-27T00:00:00.000-08:00",
"timeseries": [
{
"start_time": "2017-11-10T00:00:00.000-08:00",
"end_time": "2017-11-11T00:00:00.000-08:00",
"stats": {
"impressions": 63027,
"spend": 190136020,
"conversion_purchases": 13,
"conversion_purchases_swipe_up": 6,
"conversion_purchases_view": 7,
"conversion_add_cart": 20,
"conversion_add_cart_swipe_up": 8,
"conversion_add_cart_view": 12
}
},
{
"start_time": "2017-11-11T00:00:00.000-08:00",
"end_time": "2017-11-12T00:00:00.000-08:00",
"stats": {
"impressions": 74153,
"spend": 200905774,
"conversion_purchases": 10,
"conversion_purchases_swipe_up": 3,
"conversion_purchases_view": 7,
"conversion_add_cart": 20,
"conversion_add_cart_swipe_up": 5,
"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 nameDescription
product_impressionsnumber of impressions for a product ID
swipes
spendmicrocents 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

AttributeValues
report_dimensionproduct
asynctrue
async_formatcsv

Response - async_stats_report Object

AttributeDescriptionValues
report_run_idthe ID of your reporting taskeg: "ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6"
async_statusThe 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
resultThis contains the URL of the report fileeg: "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

AttributeValues
report_dimensionproduct_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

MetricAPI fieldDescription
Viewable Impressionsviewable_impressionsNumber 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 Impressionsnon_viewable_impressionsNumber of impressions that did not meet the criteria for a viewable impression
Viewable Rateviewable_rateThe percentage of the time that your paid Snap Ad impression met the qualifying viewable impression criteria
Measured Impressionsmeasured_impressionsNumber of impressions that were measured for viewability
Gross Impressionsgross_impressionsTotal impressions delivered, this includes invalid traffic which is excluded from spend & all other delivery metrics.
Paid Impressionspaid_impressionsThe 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.

FieldDescriptionAvailability
paid_impressionsThe 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 sessionReal Time
earned_impressionsThe number of times your ad was viewed after being shared by a Snapchatter via Chat or StoriesWithin 24 hours
sharesThe number of times your ad was shared via Chat or StoriesReal Time
savesThe number of times your ad was saved to MemoriesReal Time
spendThe total spend delivered in microcurrencyReal Time
uniquesThe number of unique paid impressionsWithin 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

ParameterDescription
adsquad-idAudience 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

ParameterDefault valueDescription
async_formatcsv
start_timeStart time in ISO format
end_timeEnd 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

ParameterDefault valueDescription
report_run_idReport idThe 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 NameTypeMax LengthRequired?DescriptionExample
DateDatetime17YesDate 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 IdString36YesAd account ID associated with the ad that generated the lead. Hyphen separated UUID string.f0d4666f-9f60-4df7-94c8-423ca55b2a17
Campaign IdString36YesCampaign ID associated with ad that generated the lead. Hyphen separated UUID string.033fe5aa-59b4-423d-8ab5-b7a7cf6c5242
Ad Set IdString36YesAd Set ID associated with ad that generated the lead. Hyphen separated UUID string.ebad6081-f387-4bce-b6dc-9ea4d2cbefbc
Ad IdString36YesAd ID associated with ad that generated the lead. Hyphen separated UUID string.ca72035c-9f8d-409b-abee-5e2e0c943f9c
First NameStringYesFirst name of Snapchat UserJane
Last NameStringYesLast name of Snapchat UserSmith
Phone NumberStringYes (Either Email Address or Phone Number)ex: 818-555-1234, +13105558765
*Not all formatted the same
818-555-1234
+13105558765
Email AddressStringYes (Either Email Address or Phone Number)Email address of Snapchat userjohndoe@gmail.com
Address Line 1StringNoAddress of Snapchat user, Line 119330 25th Ave
Address Line 2StringNoAddress of Snapchat user, Line 2Unit 3
Address Level 1StringNoAddress city or townSeattle
Address Level 2StringNoAddress state, province, or regionWA
Postal CodeStringNoPostal code of Snapchat user94012
BirthdayDate10NoSnapchat user's birthdate. Formatted "MM/DD/YYYY"05/20/1998
Job TitleStringNoJob titleMarketing Manager
Company NameStringNoCompany nameSnap, Inc.
Custom Field 1StringNoCan 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 2StringNo"
Custom Field 3StringNo"
Custom Field 4StringNo"
Custom Field 5StringNo"
Custom Field 6StringNo"
Custom Field 7StringNo"
Custom Field 8StringNo"
Consent 1StringDisclaimers: 80
Answer: 5
Total: 86
NoDisclaimer 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 2StringDisclaimers: 80
Answer: 5
Total: 86
NoDisclaimer 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 StatusStringPreferred | Non-PreferredNoIndicates 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.

Was this page helpful?
Yes
No