Measurement
Measurement endpoints provides stats data that is updated approximately every 15 minutes.
All stats requests can be made with TOTAL, DAY, or HOUR granularity.
Request/Response Pattern
Stats endpoints have a consistent request and response pattern.
Request Pattern
Pattern:
GET /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}/stats
Example:
GET /v1/campaigns/ff869d1f-0923-4d28-8577-4c36291f0fca/stats
Response Pattern - TOTAL Granularity
Response pattern for TOTAL Granularity requests
{
"request_status": "success",
"request_id": "57ad1ad600076e58fa35e192",
"total_stats": [
{
"sub_request_status": "success",
"total_stat": {
"id": "7057e31f-b908-4bc7-85dd-88169f53e08d",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
}
}
]
}
Response Pattern - DAY Granularity
Response pattern for DAY Granularity requests
{
"request_status": "success",
"request_id": "57ad240f000756e8d435a6cd",
"timeseries_stats": [
{
"sub_request_status": "success",
"timeseries_stat": {
"id": "7057e31f-b908-4bc7-85dd-88169f53e08d",
"type": "CAMPAIGN",
"granularity": "DAY",
"start_time": "2016-08-05T22:00:00.000-07:00",
"end_time": "2016-08-07T22:00:00.000-07:00",
"timeseries": [
{
"start_time": "2016-08-05T22:00:00.000-07:00",
"end_time": "2016-08-06T22:00:00.000-07:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
},
{
"start_time": "2016-08-06T22:00:00.000-07:00",
"end_time": "2016-08-07T22:00:00.000-07:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
}
]
}
}
]
}
Response Pattern - HOUR Granularity
Response pattern for HOUR Granularity requests
{
"request_status": "success",
"request_id": "57ad245a000e3c88bc33ea4e",
"timeseries_stats": [
{
"sub_request_status": "success",
"timeseries_stat": {
"id": "7057e31f-b908-4bc7-85dd-88169f53e08d",
"type": "CAMPAIGN",
"granularity": "HOUR",
"start_time": "2016-08-05T18:00:00.000-07:00",
"end_time": "2016-08-06T18:00:00.000-07:00",
"timeseries": [
{
"start_time": "2016-08-05T18:00:00.000-07:00",
"end_time": "2016-08-05T19:00:00.000-07:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
},
{
"start_time": "2016-08-05T19:00:00.000-07:00",
"end_time": "2016-08-05T20:00:00.000-07:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
}
....
{
"start_time": "2016-08-06T16:00:00.000-07:00",
"end_time": "2016-08-06T17:00:00.000-07:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
},
{
"start_time": "2016-08-06T17:00:00.000-07:00",
"end_time": "2016-08-06T18:00:00.000-07:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
}
]
}
}
]
}
Request Parameters
Attribute | Description | Required | Possible Values |
---|---|---|---|
breakdown | Object-level breakdown | O | ad, adsquad [Only available on Campaign Stats endpoint], campaign [Only available on Ad Account Stats endpoint] |
async | Designates processing of report to be asynchronous | O | true |
async_format | Designates the response format of asynchronous reporting, can be either a csv or excel file | O | csv, excel |
fields | Metrics requested (comma-separated) | O | (see table below; default: impressions,spend) |
end_time | End Time (ISO 8601) | R* | |
start_time | Start Time (ISO 8601) | R* | |
granularity | Metrics granularity | R | TOTAL, DAY, HOUR, LIFETIME |
test | Return Sample (fake) Stats | O | false (default), true |
dimension | Insight-level breakdown | O | GEO, DEMO, INTEREST, DEVICE |
pivot | The pivot to be used for insights breakdown | O | country, region, dma, gender, age_bucket, interest_category_id, interest_category_name, operating_system, make, model |
action_report_time | Specifies the principle for conversion reporting | O | conversion (default), impression** |
swipe_up_attribution_window | Attribution window for swipe ups | O | 1_DAY, 7_DAY, 28_DAY (default) |
view_attribution_window | Attribution window for views | O | none, 1_HOUR, 3_HOUR, 6_HOUR, 1_DAY (default), 7_DAY, 28_DAY*** |
position_stats | Position metric breakdown for Snap Ads within a Story Ad | O | true |
omit_empty | Omits records with zero data for all metrics for a given date/entity. If there is data for any metric for a given date/entity, all metrics for that date/entity are returned | O | false (default), true |
conversion_source_types | Conversion source breakout by platform | O | web, app, offline**, total, total_off_platform, total_on_platform |
limit | The limit parameter specifies how many entities should be returned per page | O | integer, max 200 |
* start_time and end_time are required for DAY and HOUR granularity and they must be set to the start of an hour (e.g. 22:00 not 22:45)
** offline conversion data source ( conversion_source_types=offline ) and impression based conversions
** action_report_time=impression** ) are available from 1 May 2020 onwards
*** 28_DAY view_attribution_window is deprecated, legacy data is available up until 1 March 2021
Response Parameters & Finalization
Attribute | Description |
---|---|
finalized_data_end_time | This attribute defines the time up until when non-conversion reporting metrics are finalized. You can query for all metrics before this time including uniques and reach and they will have the final numbers. For any time after the finalized_data_end_time the metrics are still undergoing de-duplication and finalization and may change accordingly. |
conversion_data_processed_end_time | This attribute defines the time up until when conversion metrics are finalized, for any time after the conversion_data_processed_end_time the conversion metrics are still undergoing processing and may change accordingly. Note that this attribute only covers conversion by time of conversion. |
paging | If you are using pagination the paging attribute will contain a next_link attribute which holds the API call to fetch the next page. |
Pagination
For calls that fetch stats for many entities we recommend that you use pagination. The limit parameter specifies how many entities should be returned per page. The maximum pagination limit is 200.
The returned result will contain a paging
attribute, this in turn holds a next_link
attribute which holds the API call to fetch the next
page. Paginated calls are rdered by time of creation, non-paginated calls are unsorted.
Core Metrics
The following metrics are available for all Snap Ads.
Field Name | Description |
---|---|
impressions | Impression Count |
swipes | Swipe-Up Count |
view_time_millis | Use screen_time_millis instead. Total Time Spent on top Snap Ad (milliseconds) |
screen_time_millis | Total Time Spent on top Snap Ad (milliseconds) |
quartile_1 | Video Views to 25% |
quartile_2 | Video Views to 50% |
quartile_3 | Video Views to 75% |
view_completion | Video Views to completion |
spend | Amount Spent (micro-currency) |
coupon_used_local | Amount Spent via Coupon in the assigned currency of Ad Account (micro-currency) |
coupon_used_usd | Amount Spent via Coupon in USD (micro-currency) |
video_views | The total number of impressions that meet the qualifying video view criteria of at least 2 seconds of consecutive watch time or a swipe up action on the Top Snap |
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
andend_time
are required values, thestart_time
andend_time
must be the daily boundry for the timezone of the Ad Account in question - When
start_time
andend_time
is not defined in combination with granularity TOTAL it is treated the same as granularity LIFETIME
Parameter | Description | Required | Possible values |
---|---|---|---|
async | Designates processing of report to be asynchronous | R | true |
async_format | Designates the response format of asynchronous reporting, can be either a csv or excel file | O | csv (default), excel |
granularity | Metrics granularity | O | TOTAL, DAY, LIFETIME |
Example - Step 1 Generating an async report
This request produces a report_run_id
and the async_status
returned is STARTED.
curl "https://adsapi.snapchat.com/v1/adaccounts/ce943c3b-2404-4fff-acb1-259b7b052f27/stats?breakdown=ad&granularity=DAY&view_attribution_window=1_DAY&async=true&omit_empty=true&fields=impressions,total_installs,spend,swipes,attachment_video_views,story_opens,story_completes,shares,saves,conversion_purchases,conversion_purchases_value,conversion_save,conversion_start_checkout,conversion_add_cart,conversion_view_content,conversion_add_billing,conversion_sign_ups,conversion_searches,conversion_level_completes,conversion_app_opens,conversion_page_views&start_time=2024-10-01T00:00:00&end_time=2024-10-08T00:00:00&swipe_up_attribution_window=28_DAY" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "acfacd19-bd51-4822-a9d3-e503a523d25f",
"async_stats_reports": [
{
"sub_request_status": "SUCCESS",
"async_stats_report": {
"report_run_id": "ASYNC_STATS:ce943c3b-2404-4fff-acb1-259b7b052f27:1727755200000:7245f6e6-eda4-4650-9255-6e3ab38b95ce",
"async_status": "STARTED"
}
}
]
}
Checking the status of an asynchronous report
The second step of asynchronus reporting is checking the status of the report and fetching the download url of the finished report, this request requires the report_run_id
value returned in the previous request.
HTTP Requests
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats_report
GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/stats_report
GET https://adsapi.snapchat.com/v1/adsquads/{adsquad_id}/stats_report
GET https://adsapi.snapchat.com/v1/ads/{ad_id}/stats_report
Parameters for checking asynchronous reporting
When checking asynchronous reporting requests the
Parameter | Description | Required | Possible values |
---|---|---|---|
report_run_id | The id of the report to be fetched | R |
Example - Step 2 Checking the status of an async report - Report is processing
This request requires the report_run_id
and the async_status
returned is RUNNING which indicates that the report is still processing.
curl "https://adsapi.snapchat.com/v1/adaccounts/ce943c3b-2404-4fff-acb1-259b7b052f27/stats_report?report_run_id=ASYNC_STATS:6b78bf3c-b7f4-4fcf-b74a-a5aaa91b15ef:1726804800000:7139d12c-910e-4e09-b3fd-a01f82b3af56" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "f8a5b7b0-14b4-950c-934f-7b746745e571",
"async_stats_reports": [
{
"sub_request_status": "SUCCESS",
"async_stats_report": {
"report_run_id": "ASYNC_STATS:6b78bf3c-b7f4-4fcf-b74a-a5aaa91b15ef:1726804800000:7139d12c-910e-4e09-b3fd-a01f82b3af56",
"async_status": "RUNNING"
}
}
]
}
Example - Step 2 Checking the status of an async report - Report is completed
This request requires the report_run_id
and the async_status
returned is COMPLETED, the url of the report is found in the result
attribute.
curl "https://adsapi.snapchat.com/v1/adaccounts/ce943c3b-2404-4fff-acb1-259b7b052f27/stats_report?report_run_id=ASYNC_STATS:6b78bf3c-b7f4-4fcf-b74a-a5aaa91b15ef:1726804800000:7139d12c-910e-4e09-b3fd-a01f82b3af56" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "f8a5b7b0-14b4-950c-934f-7b746745e571",
"async_stats_reports": [
{
"sub_request_status": "SUCCESS",
"async_stats_report": {
"report_run_id": "ASYNC_STATS:6b78bf3c-b7f4-4fcf-b74a-a5aaa91b15ef:1726804800000:7139d12c-910e-4e09-b3fd-a01f82b3af56",
"async_status": "COMPLETED",
"result": "https://data-transfer.snapads.com/async-report/snap_ads/ASYNC_STATS:6b78bf3c-b7f4-4fcf-b74a-a5aaa91b15ef:1726804800000:7139d12c-990e-4e09-b3fd-a01f82b3af56/9496dff0-07b9-44d8-8f0b-b44eb276cc9e.xlsx"
}
}
]
}
Reach Overlap Reporting
Reach overlap reporting via async reporting is available for Campaigns, Ad Squads and Ads using the Snapchat Marketing API.
The entities for which the calculation is made must belong to the same Ad Account, overlap reporting across different Ad Accounts is not possible. If an entity has no metrics for the given reporting period (start_time / end_time), it will be excluded from the resulting report.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats?overlap=true&overlap_type={campaign/ad_squad/ad}&ids={entity1_id,entity_id,...},{entity2_id}&start_time={start_time}&end_time={end_time}&async_format={csv/excel}
Request Parameters
Attribute | Description | Possible values |
---|---|---|
async_format | Defines the returned format of the report | csv,excel |
ids | Two or more Campaign/Ad Squad/Ad entities to calculate the reach overlap for, these have to be the same type of entities and live within the same Ad Account | Comma separated string of up to 100 Campaign ID/Ad Squad ID/Ad ID values |
overlap | Indicates whether an overlap calculation should take place | true |
overlap_type | Specifies the entity level of the overlap calculation, you cannot use two different types of entities in one report | campaign, ad_squad, ad |
start_time | Start time of the report | Start time in ISO format |
end_time | End time of the report | End time in ISO format |
Example Request
This request generates an async process to create an overlap report in Excel format for two Campaigns in the same Ad Account, for the time period 1-30 April 2024.
curl 'https://adsapi.snapchat.com/v1/adaccounts/62f51caa-394c-4f88-905c-71a9859f2b54/stats?overlap=true&overlap_type=campaign&ids=11f5bc01-22a4-469e-ba7e-d4c7edc5ef88%2C50984a9d-1b2e-4d5d-857e-5ac9d3665506%2C54f10e2d-55a8-4924-896d-5a94fba1a0c9&start_time=2024-04-01T07%3A00%3A00.000Z&end_time=2024-04-30T07%3A00%3A00.000Z&async_format=excel' \
-H "Authorization: Bearer meowmeowmeow"
Response
{
"request_status": "SUCCESS",
"request_id": "f5cdc549-f3f3-4aed-9e39-68216ba70be3",
"async_stats_reports": [
{
"sub_request_status": "SUCCESS",
"async_stats_report": {
"report_run_id": "ASYNC_STATS:62f51caa-394c-4f88-905c-71a9859f2b54:1711954800000:f591f1c1-581e-477b-892f-7b8b5365b0e7",
"async_status": "STARTED"
}
}
]
}
Once the async process for an overlap report is initiated using the above request, follow the steps in Checking the status of an asynchronous report to check the status and fetch the download url of a completed report.
Report Format
Below is an example of a Reach Overlap
report downloaded in excel format. This resulting report includes metrics for reach
and uniques
, showing the overlap for the requested entities.
The requested entities in this example are two campaigns - Wellness Campaign and Beauty Campaign.
The report starts with Reached by all
, which is the Reach Overlap
for all the entities that were included in the report.
Example
Row 1
shows theReach 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 theTotal 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 totalReach
of the Wellness CampaignRow 6
below shows the totalUniques
of the Wellness CampaignRow 7
below shows the totalReach
of the Beauty CampaignRow 9
below shows the totalUniques
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
andRow 8
shows theReach Overlap
of the Wellness Campaign and the Beauty Campaign.
A | B | C | D | E | F | |
---|---|---|---|---|---|---|
1 | Reached by all | 6,029 | ||||
2 | Total Uniques Reached | 212,351 | ||||
3 | Campaign Id 1 | Campaign Name 1 | Campaign Id 2 | Campaign Name 2 | Reach Type | Reach Value |
4 | 11111111-1111-1111-111111111111 | Wellness Campaign | 11111111-1111-1111-111111111111 | Wellness Campaign | Total | 160.356 |
5 | 11111111-1111-1111-111111111111 | Wellness Campaign | 222222222-2222-2222-2222-2222222222 | Beauty Campaign | Overlap | 6,029 |
6 | 11111111-1111-1111-111111111111 | Wellness Campaign | 11111111-1111-1111-111111111111 | Wellness Campaign | Unique | 154,327 |
7 | 222222222-2222-2222-2222-2222222222 | Beauty Campaign | 222222222-2222-2222-2222-2222222222 | Beauty Campaign | Total | 60,746 |
8 | 222222222-2222-2222-2222-2222222222 | Beauty Campaign | 11111111-1111-1111-111111111111 | Wellness Campaign | Overlap | 6,029 |
9 | 222222222-2222-2222-2222-2222222222 | Beauty Campaign | 222222222-2222-2222-2222-2222222222 | Beauty Campaign | Unique | 54,717 |
Additional Metrics
See the Metrics and supported granularities table for a breakdown of the reporting granularities available per Ad type. For LIFETIME granularity the data is only accessible as finalized data, available after 48-72 hours.
Field Name | Snap Ad Types | Description |
---|---|---|
android_installs | APP_INSTALL | # of Android App Installs |
attachment_avg_view_time_millis | Any Attachment | Average Attachment View Time (milli-seconds) |
attachment_frequency | Any Attachment | Average # of Attachment Views per User Reached |
attachment_quartile_1 | LONGFORM_VIDEO | Long Form Video Views to 25% |
attachment_quartile_2 | LONGFORM_VIDEO | Long Form Video Views to 50% |
attachment_quartile_3 | LONGFORM_VIDEO | Long Form Video Views to 75% |
attachment_total_view_time_millis | Any Attachment | Total Attachment View Time (milli-seconds) |
attachment_uniques | Any Attachment | # of unique attachment impressions |
attachment_view_completion | LONGFORM_VIDEO | Long Form Video Views to completion |
attachment_video_views | LONGFORM_VIDEO | Long Form Video Attachment Views, viewed for at least 10 consecutive seconds or reached 97% of the Long Form Video duration |
avg_view_time_millis | Any | Use avg_screen_time_millis instead. Average Top Snap view time per User Reached |
avg_screen_time_millis | Any | Average Top Snap view time across all impressions |
frequency | Any | Average # of Impressions per User Reached |
ios_installs | APP_INSTALL | # of iOS App Installs |
swipe_up_percent | Any Attachment | % of Impressions that Swiped-Up |
total_installs | APP_INSTALL | Total # of App Installs |
uniques | Any | # of unique impressions |
video_views_time_based | Any | The total number of impressions that meet the qualifying video view criteria of at least 2 seconds, not including swipe ups |
video_views_15s | Any | The total number of impressions that meet the qualifying video view criteria of at least 15 seconds, or 97% completion if it's shorter than 15 seconds, or a swipe up action on the ad |
story_opens | STORY | # of times users tapped on the ad tile in the feed to view the Story Ad |
story_completes | STORY | # of times users viewed through to the last Snap of your Story Ad |
landing_page_views | # of times a Snapchatter has loaded the ad’s landing page after a click page | |
profile_clicks | Any | # of times users tapped the logo in the upper corner taking them to the profile page |
position_impressions | STORY | # the impression number for this story ad position |
position_screen_time_millis | STORY | # the total view time in milliseconds for this story ad position |
position_swipe_up_percent | STORY | # the swipe up rate for this story ad position |
avg_position_screen_time_millis | STORY | # the average view time for this story ad position |
shares | LENS, AD_TO_LENS, FILTER | # of times lens/filter was shared in a Chat or Story |
saves | LENS, AD_TO_LENS, FILTER | # of times lens/filter was saved to Memories |
paid_impressions | LENS, FILTER, AD_TO_LENS | The total number of times your ad was served to a Snapchatter. Tracked when the ad fully renders on a device for the first time during a Snapchatter’s viewing session |
earned_impressions | LENS, FILTER, AD_TO_LENS | The number of times your ad was viewed after being shared by a Snapchatter via Chat or Stories |
total_impressions | LENS | The total number of impressions (Paid and Earned) |
play_time_millis | LENS | The total amount of time in where Snapchatters interacted with your Lens in the camera (milliseconds) |
total_reach | LENS | The number of unique Snapchatters who viewed your Lens ad, either by receiving a Paid or Earned Impression. |
earned_reach | LENS, FILTER, AD_TO_LENS | The number of unique Snapchatters who viewed the filter/lens after being shared by a Snapchatter via Chat or Stories |
native_leads | LEAD_GENERATION | Total number of Snapchat users that swipe up, fill out the required fields, and hit ‘Submit’ on Lead Form attachments. If a user swipes down or cancels before hitting 'Submit,' this action is not counted |
Apple Transparent Tracking (ATT) Reporting
All the users whose activity is tracked using the attribution and measurement services will be split into two categories. Please note that only conversion metrics are affected by the ATT updates.
User Category | Description | User groups in category |
---|---|---|
Fully Tracked group | These user groups are fully supported for the features listed below. | Android, iOS opted-in users |
Partially tracked group | These user groups are partially supported. | Snap Pixel, iOS opted out users and users reported via Conversions API |
Below is the list of all the reporting fields and API fields that are affected for each group.
Dimension/Granularity | Conversion Sources | |
---|---|---|
Fully Tracked Group - | Partially tracked Group - | |
Time of Conversion | Supported | Supported |
Time of Exposure | Supported | Supported |
Event Source (web/app/offline) | Supported | Supported |
Entity (campaign/ad set/ad) | Supported | Supported |
Age | Supported | Supported |
Gender | Supported | Supported |
Age, Gender | Supported | Supported |
Country | Supported | Supported |
OS | Supported | Supported |
Platform (on/off snapchat) | Supported | Supported |
Region (US Only) | Supported | NOT Supported |
DMA (US Only) | Supported | NOT Supported |
Device Make | Supported | NOT Supported |
SLC (lifestyle category) | Supported | NOT Supported |
Product | Supported | NOT Supported |
Hourly Conversions | Supported | NOT Supported |
Daily, Total, Lifetime Conversion | Supported | Supported |
Swipe Up Window: View Thru Window:
| Supported | Supported |
View Through Window: | Supported | Supported |
View Through Window: 28_DAY* | NOT Supported | NOT 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.
Name | Description |
---|---|
conversion_total_installs_sk_ad_network | Total App Installs tracked via SKAd Network |
conversion_ios_installs_sk_ad_network | Exact same metric as conversion_total_installs_sk_ad_network |
conversion_purchases_sk_ad_network | |
conversion_save_sk_ad_network | |
conversion_start_checkout_sk_ad_network | |
conversion_add_cart_sk_ad_network | |
conversion_view_content_sk_ad_network | |
conversion_add_billing_sk_ad_network | |
conversion_sign_ups_sk_ad_network | |
conversion_searches_sk_ad_network | |
conversion_level_completes_sk_ad_network | |
conversion_app_opens_sk_ad_network | |
conversion_page_views_sk_ad_network | |
conversion_subscribe_sk_ad_network | |
conversion_ad_click_sk_ad_network | |
conversion_ad_view_sk_ad_network | |
conversion_complete_tutorial_sk_ad_network | |
conversion_invite_sk_ad_network | |
conversion_login_sk_ad_network | |
conversion_share_sk_ad_network | |
conversion_reserve_sk_ad_network | |
conversion_achievement_unlocked_sk_ad_network | |
conversion_add_to_wishlist_sk_ad_network | |
conversion_spend_credits_sk_ad_network | |
conversion_rate_sk_ad_network | |
conversion_start_trial_sk_ad_network | |
conversion_list_view_sk_ad_network | |
conversion_visitation_sk_ad_network | |
custom_event_1_sk_ad_network | |
custom_event_2_sk_ad_network | |
custom_event_3_sk_ad_network | |
custom_event_4_sk_ad_network | |
custom_event_5_sk_ad_network | |
unknown_sk_ad_network | SkAdNetwork conversion events with unknown Conversion Values |
conversion_assist_install_sk_ad_network | The number of times the SKAdNetwork campaign drove an App Install, but was not the last touch before the App Install occurred. conversion_null_sk_ad_network |
conversion_null_sk_ad_network | The number of SKAdNetwork conversion events with "null" Conversion Values. This indicates the campaign did not generate enough daily SKAdNetwork conversions to pass Apple’s privacy threshold. |
SKAd Network View Conversion Metrics
The following metrics return the SKAd Network VIEW conversions.
Name | Description |
---|---|
conversion_total_installs_sk_ad_network_view | Total App Installs tracked via SKAd Network |
conversion_ios_installs_sk_ad_network_view | Exact same metric as conversion_total_installs_sk_ad_network_view |
conversion_purchases_sk_ad_network_view | |
conversion_save_sk_ad_network_view | |
conversion_start_checkout_sk_ad_network_view | |
conversion_add_cart_sk_ad_network_view | |
conversion_view_content_sk_ad_network_view | |
conversion_add_billing_sk_ad_network_view | |
conversion_sign_ups_sk_ad_network_view | |
conversion_searches_sk_ad_network_view | |
conversion_level_completes_sk_ad_network_view | |
conversion_app_opens_sk_ad_network_view | |
conversion_page_views_sk_ad_network_view | |
conversion_subscribe_sk_ad_network_view | |
conversion_ad_click_sk_ad_network_view | |
conversion_ad_view_sk_ad_network_view | |
conversion_complete_tutorial_sk_ad_network_view | |
conversion_invite_sk_ad_network_view | |
conversion_login_sk_ad_network_view | |
conversion_share_sk_ad_network_view | |
conversion_reserve_sk_ad_network_view | |
conversion_achievement_unlocked_sk_ad_network_view | |
conversion_add_to_wishlist_sk_ad_network_view | |
conversion_spend_credits_sk_ad_network_view | |
conversion_rate_sk_ad_network_view | |
conversion_start_trial_sk_ad_network_view | |
conversion_list_view_sk_ad_network_view | |
conversion_visitation_sk_ad_network_view | |
custom_event_1_sk_ad_network_view | |
custom_event_2_sk_ad_network_view | |
custom_event_3_sk_ad_network_view | |
custom_event_4_sk_ad_network_view | |
custom_event_5_sk_ad_network_view | |
unknown_sk_ad_network_view | SkAdNetwork conversion events with unknown Conversion Values |
conversion_assist_install_sk_ad_network_view | The number of times the SKAdNetwork campaign drove an App Install, but was not the last touch before the App Install occurred |
conversion_null_sk_ad_network_view | The number of SKAdNetwork conversion events with "null" Conversion Values. This indicates the campaign did not generate enough daily SKAdNetwork conversions to pass Apple’s privacy threshold |
SKAd Network Total Conversion Metrics
The following metrics return the total sum of the SKAd Network SWIPE and VIEW conversions.
Name | Description |
---|---|
conversion_total_installs_sk_ad_network_total | Total App Installs tracked via SKAd Network |
conversion_ios_installs_sk_ad_network_total | Exact same metric as conversion_total_installs_sk_ad_network_total |
conversion_purchases_sk_ad_network_total | |
conversion_save_sk_ad_network_total | |
conversion_start_checkout_sk_ad_network_total | |
conversion_add_cart_sk_ad_network_total | |
conversion_view_content_sk_ad_network_total | |
conversion_add_billing_sk_ad_network_total | |
conversion_sign_ups_sk_ad_network_total | |
conversion_searches_sk_ad_network_total | |
conversion_level_completes_sk_ad_network_total | |
conversion_app_opens_sk_ad_network_total | |
conversion_page_views_sk_ad_network_total | |
conversion_subscribe_sk_ad_network_total | |
conversion_ad_click_sk_ad_network_total | |
conversion_ad_view_sk_ad_network_total | |
conversion_complete_tutorial_sk_ad_network_total | |
conversion_invite_sk_ad_network_total | |
conversion_login_sk_ad_network_total | |
conversion_share_sk_ad_network_total | |
conversion_reserve_sk_ad_network_total | |
conversion_achievement_unlocked_sk_ad_network_total | |
conversion_add_to_wishlist_sk_ad_network_total | |
conversion_spend_credits_sk_ad_network_total | |
conversion_rate_sk_ad_network_total | |
conversion_start_trial_sk_ad_network_total | |
conversion_list_view_sk_ad_network_total | |
conversion_visitation_sk_ad_network_total | |
custom_event_1_sk_ad_network_total | |
custom_event_2_sk_ad_network_total | |
custom_event_3_sk_ad_network_total | |
custom_event_4_sk_ad_network_total | |
custom_event_5_sk_ad_network_total | |
unknown_sk_ad_network_total | SkAdNetwork conversion events with unknown Conversion Values |
conversion_assist_install_sk_ad_network_total | The number of times the SKAdNetwork campaign drove an App Install, but was not the last touch before the App Install occurred. conversion_null_sk_ad_network |
conversion_null_sk_ad_network_total | The number of SKAdNetwork conversion events with "null" Conversion Values. This indicates the campaign did not generate enough daily SKAdNetwork conversions to pass Apple’s privacy threshold |
SKAd Network Conversion Example
curl "https://adsapi.snapchat.com/v1/campaigns/5b483328-dfab-4321-be60-8ad2dfd63d35/stats?granularity=TOTAL&start_time=2021-01-21T00:00:00.000&end_time=2021-01-25T00:00:00.000&fields=impressions,spend,swipes,conversion_total_installs_sk_ad_network,conversion_purchases_sk_ad_network,conversion_add_cart_sk_ad_network"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "601d83ee00ff06ea9762c9c4f20001737e616473617069736300016275696c642d31323762373738342d312d3432302d3000010161",
"total_stats": [
{
"sub_request_status": "SUCCESS",
"total_stat": {
"id": "5b483328-dfab-4321-be60-8ad2dfd63d35",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"stats": {
"impressions": 61295,
"swipes": 4528,
"spend": 407129814,
"conversion_total_installs_sk_ad_network": 1199,
"conversion_purchases_sk_ad_network": 6637,
"conversion_add_cart_sk_ad_network": 7212
},
"start_time": "2021-01-20T16:00:00.000-08:00",
"end_time": "2021-01-24T16:00:00.000-08:00",
"finalized_data_end_time": "2021-02-05T03:00:00.000-08:00"
}
}
]
}
This example fetches three specific SKAd Network conversion metrics.
Conversion Reporting
The action_report_time parameter specifies the timing to use when requesting conversion reporting. Passing the value conversion will return conversions based on the time the user triggered the conversion event, passing the value impression will return conversions based on the time the ad impression took place.
Reporting for conversions based on ad impression (action_report_time=impression), are available from 1st May 2020 onwards.
Conversion Event Stats
The following conversion event metrics are available for ads that have been setup to track conversions through Snap Pixel.
Fields | Granularity | Description |
---|---|---|
conversion_purchases | Any | # of attributed "PURCHASE" conversion events |
conversion_purchases_value | Any | Value of attributed "PURCHASE" conversion events (microcurrency in Ad Account's currency) |
conversion_save | Any | # of attributed "SAVE" conversion events |
conversion_save_value | Any | Value of attributed "SAVE" conversion events (microcurrency in Ad Account's currency) |
conversion_start_checkout | Any | # of attributed "START_CHECKOUT" conversion events |
conversion_start_checkout_value | Any | Value of attributed "START_CHECKOUT" conversion events (microcurrency in Ad Account's currency) |
conversion_add_cart | Any | # of attributed "ADD_CART" conversion events |
conversion_add_cart_value | Any | Value of attributed "ADD_CART" conversion events (microcurrency in Ad Account's currency) |
conversion_view_content | Any | # of attributed "VIEW_CONTENT" conversion events |
conversion_view_content_value | Any | Value of attributed "VIEW_CONTENT" conversion events (microcurrency in Ad Account's currency) |
conversion_add_billing | Any | # of attributed "ADD_BILLING" conversion events |
conversion_add_billing_value | Any | Value of attributed "ADD_BILLING" conversion events (microcurrency in Ad Account's currency) |
conversion_sign_ups | Any | # of attributed "SIGN_UP" conversion events |
conversion_sign_ups_value | Any | Value of attributed "SIGN_UP" conversion events (microcurrency in Ad Account's currency) |
conversion_searches | Any | # of attributed "SEARCH" conversion events |
conversion_searches_value | Any | Value of attributed "SEARCH" conversion events (microcurrency in Ad Account's currency) |
conversion_level_completes | Any | # of attributed "LEVEL_COMPLETE" conversion events |
conversion_level_completes_value | Any | Value of attributed "LEVEL_COMPLETE" conversion events (microcurrency in Ad Account's currency) |
conversion_app_opens | Any | # of attributed "APP_OPEN" conversion events |
conversion_app_opens_value | Any | Value of attributed "APP_OPEN" conversion events (microcurrency in Ad Account's currency) |
conversion_page_views | Any | # of attributed "PAGE_VIEW" conversion events |
conversion_page_views_value | Any | Value of attributed "PAGE_VIEW" conversion events (microcurrency in Ad Account's currency) |
conversion_subscribe | Any | # of attributed "SUBSCRIBE" conversion events |
conversion_subscribe_value | Any | Value of attributed "SUBSCRIBE" conversion events (microcurrency in Ad Account's currency) |
conversion_ad_click | Any | # of attributed "AD_CLICK" conversion events |
conversion_ad_click_value | Any | Value of attributed "AD_CLICK" conversion events (microcurrency in Ad Account's currency) |
conversion_ad_view | Any | # of attributed "AD_VIEW" conversion events |
conversion_ad_view_value | Any | Value of attributed "AD_VIEW" conversion events (microcurrency in Ad Account's currency) |
conversion_complete_tutorial | Any | # of attributed "COMPLETE_TUTORIAL" conversion events |
conversion_complete_tutorial_value | Any | Value of attributed "COMPLETE_TUTORIAL" conversion events (microcurrency in Ad Account's currency) |
conversion_invite | Any | # of attributed "INVITE" conversion events |
conversion_invite_value | Any | Value of attributed "INVITE" conversion events (microcurrency in Ad Account's currency) |
conversion_login | Any | # of attributed "LOGIN" conversion events |
conversion_login_value | Any | Value of attributed "LOGIN" conversion events (microcurrency in Ad Account's currency) |
conversion_share | Any | # of attributed "SHARE" conversion events |
conversion_share_value | Any | Value of attributed "SHARE" conversion events (microcurrency in Ad Account's currency) |
conversion_reserve | Any | # of attributed "RESERVE" conversion events |
conversion_reserve_value | Any | Value of attributed "RESERVE" conversion events (microcurrency in Ad Account's currency) |
conversion_achievement_unlocked | Any | # of attributed "ACHIEVEMENT_UNLOCKED" conversion events |
conversion_achievement_unlocked_value | Any | Value of attributed "ACHIEVEMENT_UNLOCKED" conversion events (microcurrency in Ad Account's currency) |
conversion_add_to_wishlist | Any | # of attributed "ADD_TO_WISHLIST" conversion events |
conversion_add_to_wishlist_value | Any | Value of attributed "ADD_TO_WISHLIST" conversion events (microcurrency in Ad Account's currency) |
conversion_spend_credits | Any | # of attributed "SPENT_CREDITS" conversion events |
conversion_spend_credits_value | Any | Value of attributed "SPENT_CREDITS" conversion events (microcurrency in Ad Account's currency) |
conversion_rate | Any | # of attributed "RATE" conversion events |
conversion_rate_value | Any | Value of attributed "RATE" conversion events (microcurrency in Ad Account's currency) |
conversion_start_trial | Any | # of attributed "START_TRIAL" conversion events |
conversion_start_trial_value | Any | Value of attributed "START_TRIAL" conversion events (microcurrency in Ad Account's currency) |
conversion_list_view | Any | # of attributed "LIST_VIEW" conversion events |
conversion_list_view_value | Any | Value of attributed "LIST_VIEW" conversion events (microcurrency in Ad Account's currency) |
conversion_visit | Any | # of attributed "VISIT" conversion events |
conversion_visit_value | Any | Value of attributed "VISIT" conversion events (microcurrency in Ad Account's currency) |
custom_event_1 | Any | # of attributed "CUSTOM_EVENT_1" conversion events |
custom_event_1_value | Any | Value of attributed "CUSTOM_EVENT_1" conversion events (microcurrency in Ad Account's currency) |
custom_event_2 | Any | # of attributed "CUSTOM_EVENT_2" conversion events |
custom_event_2_value | Any | Value of attributed "CUSTOM_EVENT_2" conversion events (microcurrency in Ad Account's currency) |
custom_event_3 | Any | # of attributed "CUSTOM_EVENT_3" conversion events |
custom_event_3_value | Any | Value of attributed "CUSTOM_EVENT_3" conversion events (microcurrency in Ad Account's currency) |
custom_event_4 | Any | # of attributed "CUSTOM_EVENT_4" conversion events |
custom_event_4_value | Any | Value of attributed "CUSTOM_EVENT_4" conversion events (microcurrency in Ad Account's currency) |
custom_event_5 | Any | # of attributed "CUSTOM_EVENT_5" conversion events |
custom_event_5_value | Any | Value of attributed "CUSTOM_EVENT_5" conversion events (microcurrency in Ad Account's currency) |
Custom Conversions
If you are using Custom Conversions, metrics are available using the conversion ID.
Fetch Custom Conversion IDs
Custom conversions are created under the event source that they are reported via, for web events they will be created under the Pixel Entity. To fetch all custom conversions that have been defined under a specific pixel you should use this method.
Pattern:
GET /pixels/{pixel_id}/custom_conversions
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 Name | Custom Conversion ID | ID for reporting |
---|---|---|
kitten_sales | 0029904941 | conversion_0029904941 |
european_puppy_sales | 1828361131 | conversion_1828361131 |
The custom conversion IDs would look the following way when used to fetch reporting. This value is passed via the fields
parameter.
If you have set up your events in Conversions API v3 to use the contents attribute to pass id, quantity, item_price, and brand for each item sold in the PURCHASE
event, you can also fetch reporting on the value of the sales of each Custom Conversion. This is achieved by adding _value
to the reporting ID.
Custom Conversion Name | Custom Conversion ID | ID for reporting value |
---|---|---|
kitten_sales | 0029904941 | conversion_0029904941_value |
european_puppy_sales | 1828361131 | conversion_1828361131_value |
Pattern:
GET /adaccounts/{ad_account_id}/stats
Example 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.
Parameter | Description |
---|---|
total | All conversion events |
web | Events reported via the Snap Pixel SDK |
app | Events reported within an App |
offline | Events reported from an offline source (in-store) |
total | The combined events reported for web, app, offline, and on platform (Stores and Profiles) |
total_off_platform | The combined events reported for web, app, and offline |
total_on_platform | Events reported from a Snap platform source (Stores and Profiles) |
Conversion breakout example
curl "https://adsapi.snapchat.com/v1/adsquads/0b7e62aa-a8bc-48f6-a410-c65eee9cc9a7/stats?fields=conversion_purchases,impressions,spend,swipe_up_percent,swipes,view_completion&conversion_source_types=total,web,app"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5de004c100ff03ea1eeb1050430001737e616473617069736300016275696c642d61663733336133322d312d3330372d3000010103",
"total_stats": [
{
"sub_request_status": "SUCCESS",
"total_stat": {
"id": "0b7e62aa-a8bc-48f6-a410-c65eee9cc9a7",
"type": "AD_SQUAD",
"granularity": "TOTAL",
"stats": {
"impressions": 2337371,
"swipes": 14745,
"view_completion": 69506,
"swipe_up_percent": 0.0063,
"spend": 3449137066,
"conversion_purchases": 1141,
"conversion_purchases_web": 659,
"conversion_purchases_app": 482
},
"finalized_data_end_time": "2019-11-28T02:00:00.000-08:00"
}
}
]
}
This parameter breaks down conversions based on where the conversion occurred.
Omitting empty records example
curl "https://adsapi.snapchat.com/v1/campaigns/9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37/stats?granularity=DAY&start_time=2019-11-12T00%3A00%3A00-08%3A00&end_time=2019-11-16T00%3A00%3A00-08%3A00&&swipe_up_attribution_window=28_DAY&view_attribution_window=7_DAY&fields=conversion_purchases,impressions,swipes,spend&conversion_source_types=web,app,total"
-H "Authorization: Bearer meowmeowmeow"
An example not using omit_empty, this returns several day entries with no metrics.
{
"request_status": "SUCCESS",
"request_id": "5de0f99900ff02f49ea1540d1c0001737e616473617069736300016275696c642d61663733336133322d312d3330372d300001013c",
"timeseries_stats": [
{
"sub_request_status": "SUCCESS",
"timeseries_stat": {
"id": "9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37",
"type": "CAMPAIGN",
"granularity": "DAY",
"swipe_up_attribution_window": "28_DAY",
"view_attribution_window": "7_DAY",
"start_time": "2019-11-12T00:00:00.000-08:00",
"end_time": "2019-11-16T00:00:00.000-08:00",
"finalized_data_end_time": "2019-11-28T00:00:00.000-08:00",
"timeseries": [
{
"start_time": "2019-11-12T00:00:00.000-08:00",
"end_time": "2019-11-13T00:00:00.000-08:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"conversion_purchases": 0,
"conversion_purchases_web": 0,
"conversion_purchases_app": 0
}
},
{
"start_time": "2019-11-13T00:00:00.000-08:00",
"end_time": "2019-11-14T00:00:00.000-08:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"conversion_purchases": 0,
"conversion_purchases_web": 0,
"conversion_purchases_app": 0
}
},
{
"start_time": "2019-11-14T00:00:00.000-08:00",
"end_time": "2019-11-15T00:00:00.000-08:00",
"stats": {
"impressions": 599725,
"swipes": 3790,
"spend": 594736665,
"conversion_purchases": 62,
"conversion_purchases_web": 42,
"conversion_purchases_app": 20
}
},
{
"start_time": "2019-11-15T00:00:00.000-08:00",
"end_time": "2019-11-16T00:00:00.000-08:00",
"stats": {
"impressions": 670692,
"swipes": 4189,
"spend": 716170632,
"conversion_purchases": 125,
"conversion_purchases_web": 82,
"conversion_purchases_app": 43
}
}
]
}
}
]
}
curl "https://adsapi.snapchat.com/v1/campaigns/9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37/stats?granularity=DAY&start_time=2019-11-12T00%3A00%3A00-08%3A00&end_time=2019-11-16T00%3A00%3A00-08%3A00&&swipe_up_attribution_window=28_DAY&view_attribution_window=7_DAY&fields=conversion_purchases,impressions,swipes,spend&conversion_source_types=web,app,total&omit_empty=true"
-H "Authorization: Bearer meowmeowmeow"
An example using omit_empty, this returns only day entries with metrics:
{
"request_status": "SUCCESS",
"request_id": "5de0fa4900ff0942bb5374cb8f0001737e616473617069736300016275696c642d61663733336133322d312d3330372d300001014d",
"timeseries_stats": [
{
"sub_request_status": "SUCCESS",
"timeseries_stat": {
"id": "9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37",
"type": "CAMPAIGN",
"granularity": "DAY",
"swipe_up_attribution_window": "28_DAY",
"view_attribution_window": "7_DAY",
"start_time": "2019-11-12T00:00:00.000-08:00",
"end_time": "2019-11-16T00:00:00.000-08:00",
"finalized_data_end_time": "2019-11-28T00:00:00.000-08:00",
"timeseries": [
{
"start_time": "2019-11-14T00:00:00.000-08:00",
"end_time": "2019-11-15T00:00:00.000-08:00",
"stats": {
"impressions": 599725,
"swipes": 3790,
"spend": 594736665,
"conversion_purchases": 62,
"conversion_purchases_web": 42,
"conversion_purchases_app": 20
}
},
{
"start_time": "2019-11-15T00:00:00.000-08:00",
"end_time": "2019-11-16T00:00:00.000-08:00",
"stats": {
"impressions": 670692,
"swipes": 4189,
"spend": 716170632,
"conversion_purchases": 125,
"conversion_purchases_web": 82,
"conversion_purchases_app": 43
}
}
]
}
}
]
}
The parameter omit_empty will omit records with zero data for all metrics for a given date/entity. If there is data for any metric for a given date/entity, all metrics for that date/entity are returned.
The omit_empty parameter allows developers to speed up calculations as empty entries can be removed before the calculation is made, it also allows developers to structure an app to avoid displaying empty entries in the UI.
Metrics and supported granularities
Metric | Real time | HOUR | DAY | TOTAL | LIFETIME |
---|---|---|---|---|---|
android_installs | YES | YES. time must be of hour boundary, start_time and end_time within 7 days | YES. time must be of day boundary, start_time and end_time within 31 days | YES. time must be of day boundary, start_time and end_time must be both specified, or neither. In the latter case, it combines lifetime and realtime stats. | YES. no start_time, end_time can be specified. |
attachment_avg_view_time_millis | |||||
attachment_impressions | |||||
attachment_quartile_1 | |||||
attachment_quartile_2 | |||||
attachment_quartile_3 | |||||
attachment_total_view_time_millis | |||||
attachment_view_completion | |||||
avg_screen_time_millis | |||||
avg_view_time_millis | |||||
impressions | |||||
ios_installs | |||||
quartile_1 | |||||
quartile_2 | |||||
quartile_3 | |||||
screen_time_millis | |||||
spend | |||||
coupon_used_local | |||||
coupon_used_usd | |||||
swipe_up_percent | |||||
swipes | |||||
total_installs | |||||
landing_page_views | |||||
video_views | |||||
video_views_time_based | |||||
video_views_15s | |||||
view_completion | |||||
view_time_millis | |||||
paid_impressions | |||||
earned_impressions | |||||
total_impressions | |||||
play_time_millis | |||||
profile_clicks | |||||
shares | |||||
saves | |||||
native_leads | |||||
conversion_purchases | |||||
conversion_purchases_value | |||||
conversion_save | |||||
conversion_save_value | |||||
conversion_start_checkout | |||||
conversion_start_checkout_value | |||||
conversion_add_cart | |||||
conversion_add_cart_value | |||||
conversion_view_content | |||||
conversion_view_content_value | |||||
conversion_add_billing | |||||
conversion_add_billing_value | |||||
conversion_signups | |||||
conversion_signups_value | |||||
conversion_searches | |||||
conversion_searches_value | |||||
conversion_level_completes | |||||
conversion_level_completes_value | |||||
conversion_app_opens | |||||
conversion_app_opens_value | |||||
conversion_page_views | |||||
conversion_page_views_value | |||||
conversion_subscribe | |||||
conversion_subscribe_value | |||||
conversion_ad_click | |||||
conversion_ad_click_value | |||||
conversion_ad_view | |||||
conversion_ad_view_value | |||||
conversion_complete_tutorial | |||||
conversion_complete_tutorial_value | |||||
conversion_invite | |||||
conversion_invite_value | |||||
conversion_login | |||||
conversion_login_value | |||||
conversion_share | |||||
conversion_share_value | |||||
conversion_reserve | |||||
conversion_reserve_value | |||||
conversion_achievement_unlocked | |||||
conversion_achievement_unlocked_value | |||||
conversion_add_to_wishlist | |||||
conversion_add_to_wishlist_value | |||||
conversion_spend_credits | |||||
conversion_spend_credits_value | |||||
conversion_rate | |||||
conversion_rate_value | |||||
conversion_start_trial | |||||
conversion_start_trial_value | |||||
conversion_list_view | |||||
conversion_list_view_value | |||||
custom_event_1 | |||||
custom_event_1_value | |||||
custom_event_2 | |||||
custom_event_2_value | |||||
custom_event_3 | |||||
custom_event_3_value | |||||
custom_event_4 | |||||
custom_event_4_value | |||||
custom_event_5 | |||||
custom_event_5_value | |||||
attachment_frequency | YES | NO | YES | YES. Available from 1st January 2021 | YES |
attachment_uniques | |||||
frequency | |||||
uniques | |||||
total_reach | |||||
earned_reach |
Example for All Metrics
curl -H "Authorization: Bearer meowmeow" \
"https://adsapi.snapchat.com/v1/campaigns/2bbaa6e3-4ddb-4358-9efe-48334952f4aa/stats?breakdown=adsquad&fields=android_installs,avg_screen_time_millis,attachment_frequency,attachment_quartile_1,attachment_quartile_2,attachment_quartile_3,attachment_total_view_time_millis,attachment_uniques,attachment_view_completion,frequency,impressions,ios_installs,quartile_1,quartile_2,quartile_3,spend,swipe_up_percent,swipes,total_installs,uniques,view_completion,screen_time_millis&granularity=DAY&start_time=2016-10-24T07:00:00.000-00:00&end_time=2016-10-26T07:00:00.000-00:00"
{
"request_status": "SUCCESS",
"request_id": "5813ccf400ff07b016a837c09f0001737e616473617069736300016275696c642d65373832323966352d73746174732d322d7465737400010133",
"timeseries_stats": [
{
"sub_request_status": "SUCCESS",
"timeseries_stat": {
"id": "2bbaa6e3-4ddb-4358-9efe-48334952f4aa",
"type": "CAMPAIGN",
"start_time": "2016-10-24T07:00:00.000Z",
"end_time": "2016-10-26T07:00:00.000Z",
"breakdown_stats": {
"adsquad": [
{
"id": "134aeb99-6552-4f1d-b7a6-82b9813fd079",
"type": "AD_SQUAD",
"granularity": "DAY",
"start_time": "2016-10-24T07:00:00.000Z",
"end_time": "2016-10-26T07:00:00.000Z",
"timeseries": [
{
"start_time": "2016-10-24T07:00:00.000Z",
"end_time": "2016-10-25T07:00:00.000Z",
"stats": {
"impressions": 18294,
"swipes": 0,
"quartile_1": 7489,
"quartile_2": 2595,
"quartile_3": 1964,
"view_completion": 1635,
"attachment_quartile_1": 0,
"attachment_quartile_2": 0,
"attachment_quartile_3": 0,
"attachment_view_completion": 0,
"attachment_total_view_time_millis": 0,
"frequency": 1.0014,
"avg_screen_time_millis": 1832,
"swipe_up_percent": 0,
"attachment_frequency": 0,
"attachment_avg_view_time_millis": 0,
"uniques": 18268,
"attachment_uniques": 0,
"ios_installs": 0,
"android_installs": 0,
"total_installs": 0,
"spend": 144213617,
"screen_time_millis": 33876700
}
},
{
"start_time": "2016-10-25T07:00:00.000Z",
"end_time": "2016-10-26T07:00:00.000Z",
"stats": {
"impressions": 15377,
"swipes": 0,
"quartile_1": 6345,
"quartile_2": 2185,
"quartile_3": 1596,
"view_completion": 1324,
"attachment_quartile_1": 0,
"attachment_quartile_2": 0,
"attachment_quartile_3": 0,
"attachment_view_completion": 0,
"attachment_total_view_time_millis": 0,
"frequency": 1.0011,
"avg_screen_time_millis": 1828,
"swipe_up_percent": 0,
"attachment_frequency": 0,
"attachment_avg_view_time_millis": 0,
"uniques": 15360,
"attachment_uniques": 0,
"ios_installs": 0,
"android_installs": 0,
"total_installs": 0,
"spend": 120978178,
"screen_time_millis": 28547600
}
}
]
}
}
Get Ad Account Stats
curl "https://adsapi.snapchat.com/v1/adaccounts/22335ba6-7558-4100-9663-baca7adff5f2/stats?granularity=TOTAL&fields=spend" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b24d9c00ff0d85622341e7c60001737e616473617069736300016275676c642b34326313636139312d332d31312d390001010d",
"total_stats": [
{
"sub_request_status": "success",
"total_stat": {
"id": "22335ba6-7558-4100-9663-baca7adff5f2",
"type": "AD_ACCOUNT",
"granularity": "TOTAL",
"stats": {
"spend": 89196290
},
"finalized_data_end_time": "2019-08-29T03:00:00.000-07:00"
}
}
]
}
This endpoint retrieves the spend metric for the specified Ad Account, the spend metric is the only metric available for the ad account entity.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Get Campaign Stats
curl "https://adsapi.snapchat.com/v1/campaigns/92e1c28a-a331-45b4-8c26-fd3e0eea8c39/stats?granularity=TOTAL&fields=impressions,swipes,screen_time_millis,quartile_1,quartile_2,quartile_3,view_completion,spend" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b24d9c00ff0d85622341e7c60001737e616473617069736300016275696c642d34326333636139312d312d31312d390001010d",
"total_stats": [
{
"sub_request_status": "success",
"total_stat": {
"id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
}
}
]
}
This endpoint retrieves stats for the specified Campaign.
HTTP Request
GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/stats
Parameters
Parameter | Default | Description |
---|---|---|
campaign_id | Campaign ID |
Get Ad Squad Stats
curl "https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/stats?granularity=TOTAL&fields=impressions,swipes,screen_time_millis,quartile_1,quartile_2,quartile_3,view_completion,spend"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b24e5200ff0225cdf221e6c90001737e616473617069736300016275696c642d34326333636139312d312d31312d3900010106",
"total_stats": [
{
"sub_request_status": "success",
"total_stat": {
"id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"type": "AD_SQUAD",
"granularity": "TOTAL",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
}
}
]
}
This endpoint retrieves stats for the specified Ad Squad.
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/{adsquad_id}/stats
Parameters
Parameter | Default | Description |
---|---|---|
adsquad_id | Ad Squad ID |
Get Ad Stats
curl "https://adsapi.snapchat.com/v1/ads/e8d6217f-32ab-400f-9e54-39a86a7963e4/stats?granularity=TOTAL&fields=impressions,swipes,screen_time_millis,quartile_1,quartile_2,quartile_3,view_completion,spend"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b24ec400ff0b0a2104182f430001737e616473617069736300016275696c642d34326333636139312d312d31312d390001010f",
"total_stats": [
{
"sub_request_status": "success",
"total_stat": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"type": "AD",
"granularity": "TOTAL",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
}
}
]
}
This endpoint retrieves stats for the specified Ad.
HTTP Request
GET https://adsapi.snapchat.com/v1/ads/{ad_id}/stats
Parameters
Parameter | Default | Description |
---|---|---|
ad_id | Ad ID |
Reporting for Creatives and Media
It's possible to fetch reporting for the Creative entity and the Media entity given some restrictions.
- The available granularities for Media and Creative reporting are DAY and LIFETIME, TOTAL granularity is not available.
- Reach metrics (frequency, attachmentfrequency, uniques, attachment_uniques, total_reach) are _not available for Media and Creatives
- Reporting is only available to non-DPA Creatives
Creative | Type | Reporting availability |
---|---|---|
Snap Ad | SNAP_AD | Yes |
Snap Ad with attachment | APP_INSTALL, WEB_VIEW, DEEP_LINK | Yes |
Preview Creative | PREVIEW | No |
Media | Type | Reporting availability |
---|---|---|
Top Snap | IMAGE | Yes |
Top Snap | VIDEO | Yes |
Lens LENS | LENS_PACKAGE | Yes |
Story Tile | IMAGE | No |
Creative element | IMAGE | No |
Fetching reporting for a Creative
This endpoint retrieves stats for the specified Creative.
HTTP Request
GET https://adsapi.snapchat.com/v1/creatives/{creative_id}/stats
Parameters
Parameter | Default | Description |
---|---|---|
creative_id | Creative ID |
curl "https://adsapi.snapchat.com/v1/creatives/abc123/stats?granularity=TOTAL&fields=impressions,swipes,screen_time_millis,quartile_1,quartile_2,quartile_3,view_completion,spend"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "",
"total_stats": [
{
"sub_request_status": "success",
"total_stat": {
}
}
}
]
}
Reporting Insights and Dimensions
Delivery Insights can help you understand who viewed, engaged, and took action on your ads. These insights across demographic, location, device, and interest categories can help inform optimization and increase overall campaign efficiency. Insights can be pulled for specific campaigns, ad squads, or ads; insights can also use breakdowns for multiple campaigns, ad squads, or ads at once.
- Delivery Insights are estimated to protect user privacy. They are meant to provide directional guidance on audience performance.
- Delivery Insights are only availble on days when there are at least 30 impressions.
- Delivery Insights are only available from 1 January 2020. DAY, TOTAL, and LIFETIME granularities are supported, the HOUR granularity is not available for delivery insights. Some conversion reporting metrics are available from 1 May 2020.
- Delivery insights for the combination of Country and Operating System are available from 24 October 2022 onwards.
Dimensions
You can get reporting insights based on different geographic, demographic, interest-based, and device-based dimensions. You can only query one dimension at a time unless you are querying age & gender which may be combined. Some of the dimensions (region/dma/make) only support Delivery metrics, for these dimensions it's not possible to fetch conversion metrics.
Using the report_dimension query string parameter you can see Snapchat metrics based on a number of new dimensions
Category | API Dimension (report_dimension) | Conditions | Metrics availability |
---|---|---|---|
Geo | country | Metrics broken down by ISO country code | Delivery/Conversion |
country,os* | Metrics broken down by ISO country code and Device Operating System* | Delivery | |
region | Metrics broken down by ISO country code (US only) | Delivery | |
dma | Metrics broken down by ISO country code (US only) | Delivery | |
Demographic | gender | Metrics broken down by gender | Delivery/Conversion |
age** | Metrics broken down by age buckets** | Delivery/Conversion | |
age,gender | Metrics broken down by age and gender | Delivery/Conversion | |
Device | os | Device Operating System | Delivery/Conversion |
os,country | Metrics broken down by Device Operating System and ISO country code* | Delivery | |
make | Device Make | Delivery | |
Interest | lifestyle_category | Metrics broken down by interest category (Snapchat Lifestyle Category) | Delivery |
*Country/OS metrics breakdown is available from 24 October 2022
**Age bucket breakdown have been expanded since 28 February 2025
Metrics
You may pass these metrics as a comma separated list for the fields
query parameter. Conversion metrics support attribution windows,
swipe/view variants, and value metrics in local microcents. Note that conversion metrics are not available for the dimensions
lifestyle_category
, region
,dma
or make
.
Delivery Metrics
Metric | API field | Description |
---|---|---|
Paid Impressions | impressions | Impression Count |
Unique Impressions | uniques | Unique Impressions Count |
Swipe Ups | swipes | Swipe-Up Count |
25% Quartile | quartile_1 | Video Views to 25% |
50% Quartile | quartile_2 | Video Views to 50% |
75% Quartile | quartile_3 | Video Views to 75% |
Completions | view_completion | Video Views to completion |
Spend | spend | Amount Spent (micro-currency) |
Video Views | video_views | The total number of impressions that meet the qualifying video view criteria of at least 2 seconds of consecutive watch time or a swipe up action on the Top Snap |
Landing Page Views* | landing_page_views* | The total number of times a user loaded the ad’s landing page after a click |
Attachment Uniques | attachment_uniques | Attachment Uniques |
25% Attachment Quartile | attachment_quartile_1 | Long Form Video Views to 25% |
50% Attachment Quartile | attachment_quartile_2 | Long Form Video Views to 50% |
75% Attachment Quartile | attachment_quartile_3 | Long Form Video Views to 75% |
Attachment Completions | attachment_view_completion | Long Form Video Views to completion |
Attachment View Time | attachment_total_view_time_millis | Total Attachment View Time (milli-seconds) |
Attachment Video Views | attachment_video_views | Long Form Video Attachment Views |
Story Opens | story_opens | # of times users tapped on the ad tile in the feed to view the Story Ad |
Story Completes | story_completes | # of times users viewed through to the last Snap of your Story Ad |
Shares | shares | # of times lens/filter was shared in a Chat or Story |
Saves | saves | # of times lens/filter was saved to Memories |
*landing_page_views are available from 10 December 2024
Conversion Metrics
Metric | API field | Description |
---|---|---|
Installs | total_installs | Total # of App Installs |
Purchases | conversion_purchases | # of attributed “PURCHASE” conversion events** |
Purchase Value | conversion_purchases_value | Value of attributed “PURCHASE” conversion events (microcurrency in Ad Account’s currency)** |
Saves | conversion_save | # of attributed “SAVE” conversion events** |
Start Checkout | conversion_start_checkout | # of attributed “START_CHECKOUT” conversion events** |
Add To Cart | conversion_add_cart | # of attributed “ADD_CART” conversion events** |
View Content | conversion_view_content | # of attributed “VIEW_CONTENT” conversion events** |
Add Billing | conversion_add_billing | # of attributed “ADD_BILLING” conversion events** |
Sign Ups | conversion_sign_ups | # of attributed “SIGN_UP” conversion events** |
Searches | conversion_searches | # of attributed “SEARCH” conversion events** |
Level Completes | conversion_level_completes | # of attributed “LEVEL_COMPLETE” conversion events** |
App Opens | conversion_app_opens | # of attributed “APP_OPEN” conversion events** |
Page Views | conversion_page_views | # of attributed “PAGE_VIEW” conversion events** |
Subscribes | conversion_subscribe | # of attributed "SUBSCRIBE" conversion events++ |
Ad Clicks | conversion_ad_click | # of attributed “CONVERSION_AD_CLICK” conversion events++ |
Ad Views | conversion_ad_view | # of attributed “CONVERSION_AD_VIEW” conversion events++ |
Completed Tutorials | conversion_complete_tutorial | # of attributed “CONVERSION_COMPLETE_TUTORIAL” conversion events++ |
Invites Sent | conversion_invite | # of attributed “CONVERSION_INVITE” conversion events++ |
Logins | conversion_login | # of attributed “CONVERSION_LOGIN” conversion events++ |
Shares | conversion_share | # of attributed “CONVERSION_SHARE” conversion events++ |
Reservations | conversion_reserve | # of attributed “CONVERSION_RESERVE” conversion events++ |
Achievements Unlocked | conversion_achievement_unlocked | # of attributed “CONVERSION_ACHIEVEMENT_UNLOCKED” conversion events++ |
Adds to Wishlist | conversion_add_to_wishlist | # of attributed “CONVERSION_ADD_TO_WISHLIST” conversion events++ |
Credits Spent | conversion_spend_credits | # of attributed “CONVERSION_SPEND_CREDITS” conversion events++ |
Rates Submitted | conversion_rate | # of attributed “CONVERSION_RATE” conversion events++ |
Trial Starts | conversion_start_trial | # of attributed “CONVERSION_START_TRIAL” conversion events++ |
Lists Viewed | conversion_list_view | # of attributed “LIST_VIEW” conversion events++ |
Store Visits | conversion_visit | # of attributed “VISIT” conversion events++ |
Custom Event 1 | custom_event_1 | # of attributed “CUSTOM_EVENT_1” conversion events++ |
Custom Event 2 | custom_event_2 | # of attributed “CUSTOM_EVENT_2” conversion events++ |
Custom Event 3 | custom_event_3 | # of attributed “CUSTOM_EVENT_3” conversion events++ |
Custom Event 4 | custom_event_4 | # of attributed “CUSTOM_EVENT_4” conversion events++ |
Custom Event 5 | custom_event_5 | # of attributed “CUSTOM_EVENT_5” conversion events++ |
** This conversion metric is available from 1st January 2020 when using action_report_time=conversion and 1st May 2020 when using **action_report_time=impression**
++ This conversion metric is available from 1st of May 2020 for both action_report_time=conversion and action_report_time=impression
Insights by GEO
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats
Parameters
Parameter | Possible values | Description |
---|---|---|
ad_account_id | Ad Account ID | |
report_dimension | country,region,dma | The desired Report Dimension |
Example of Geographic Insights
This retrieves insights for country broken down to Campaign level using report_dimension=country
.
curl "https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/stats/?granularity=TOTAL&breakdown=campaign&fields=impressions,swipes,conversion_purchases&report_dimension=country&start_time=2020-01-25T00:00:00-08:00&end_time=2020-01-26T00:00:00-08:00&swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e6bee5400ff0aaf11217b24900001737e616473617069736300016275696c642d31636430373832652d312d3333342d3000010128",
"total_stats": [
{
"sub_request_status": "SUCCESS",
"total_stat": {
"id": "22225ba6-7559-4000-9663-bace8adff5f2",
"type": "AD_ACCOUNT",
"granularity": "TOTAL",
"swipe_up_attribution_window": "28_DAY",
"view_attribution_window": "1_DAY",
"start_time": "2020-01-25T00:00:00.000-08:00",
"end_time": "2020-01-26T00:00:00.000-08:00",
"finalized_data_end_time": "2020-03-13T00:00:00.000-07:00",
"breakdown_stats": {
"campaign": [
{
"id": "88821981-14be-4315-9832-278b27004d68",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"start_time": "2020-01-25T00:00:00.000-08:00",
"end_time": "2020-01-26T00:00:00.000-08:00",
"dimension_stats": [
{
"impressions": 23433,
"swipes": 141,
"country": "au",
"conversion_purchases": 3
}
]
},
{
"id": "8079bbff-8a7b-4548-8556-d726461da248",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"start_time": "2020-01-25T00:00:00.000-08:00",
"end_time": "2020-01-26T00:00:00.000-08:00",
"dimension_stats": [
{
"impressions": 19970,
"swipes": 488,
"country": "us",
"conversion_purchases": 4
}
]
},
{
"id": "828f739c-7f32-4013-9a92-58c6495e9438",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"start_time": "2020-01-25T00:00:00.000-08:00",
"end_time": "2020-01-26T00:00:00.000-08:00",
"dimension_stats": [
{
"impressions": 46068,
"swipes": 74,
"country": "fr",
"conversion_purchases": 5
}
]
}
]
},
"split_results": []
}
}
]
}
Insights by DEMO
When requesting reporting insights using demographic parameters (age/gender) the response will be broken into age buckets.
Following the introduction of the possibility to target Snapchat users aged 55+ in February 2025 we have introduced additional age buckets, this means the age buckets returned in reporting depends on the date that the campaign was live. Campaigns that ran prior to to February 2025 only have a specific set of Age buckets available.
Age buckets (age_bucket) | Age buckets (age_bucket) after 28 February 2025 | Description |
---|---|---|
13-17 | 13-17 | |
18-20 | 18-20 | |
21-24 | 21-24 | |
25-34 | 25-34 | |
35+ | 35+ | This bucket will start to return 0 from Day Month |
35-44* | New age bucket | |
45-54* | New age bucket | |
55+* | New age bucket |
*These age bucket will start to account for conversion metrics from the 27 March 2025
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats
Parameters
Parameter | Possible values | Description |
---|---|---|
ad_account_id | Ad Account ID | |
report_dimension | age,gender | The desired Report Dimension |
Example of Demographic Insights
curl "https://adsapi.snapchat.com/v1/ads/a08f3e23-735b-4cd2-b72d-0cdb4d47967b/stats?granularity=TOTAL&fields=impressions,spend,swipe_up_percent,swipes,view_completion,conversion_sign_ups&start_time=2025-02-15&end_time=2025-03-05&report_dimension=age,gender"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "0126c186-4416-4dea-8be0-2a999b54c780",
"total_stats": [
{
"sub_request_status": "SUCCESS",
"total_stat": {
"id": "a08f3e23-735b-4cd2-b72d-0cdb4d47967b",
"type": "AD",
"granularity": "TOTAL",
"swipe_up_attribution_window": "28_DAY",
"view_attribution_window": "1_DAY",
"engaged_view_attribution_window": "2_DAY",
"start_time": "2025-02-15T00:00:00.000-05:00",
"end_time": "2025-03-05T00:00:00.000-05:00",
"finalized_data_end_time": "2025-03-05T13:00:00.000Z",
"conversion_data_processed_end_time": "2025-03-05T00:00:00.000Z",
"dimension_stats": [
{
"impressions": 17461,
"swipes": 16,
"view_completion": 90,
"swipe_up_percent": 0.0027,
"spend": 362083431,
"age_bucket": "13-17",
"gender": "female",
"conversion_sign_ups": 11
},
{
"impressions": 12480,
"swipes": 26,
"view_completion": 59,
"swipe_up_percent": 0.0019,
"spend": 62093431,
"age_bucket": "13-17",
"gender": "male",
"conversion_sign_ups": 22
},
{
"impressions": 15461,
"swipes": 26,
"view_completion": 80,
"swipe_up_percent": 0.0017,
"spend": 262083431,
"age_bucket": "25-34",
"gender": "female",
"conversion_sign_ups": 11
},
{
"impressions": 2489,
"swipes": 3,
"view_completion": 10,
"swipe_up_percent": 0.0012,
"spend": 51786604,
"age_bucket": "35-44",
"gender": "female",
"conversion_sign_ups": 0
},
{
"impressions": 3379,
"swipes": 7,
"view_completion": 12,
"swipe_up_percent": 0.0021,
"spend": 70961784,
"age_bucket": "35+",
"gender": "female",
"conversion_sign_ups": 2
},
{
"impressions": 677,
"swipes": 1,
"view_completion": 2,
"swipe_up_percent": 0.0015,
"spend": 12764108,
"age_bucket": "45-54",
"gender": "female",
"conversion_sign_ups": 0
},
{
"impressions": 213,
"swipes": 3,
"view_completion": 0,
"swipe_up_percent": 0.0141,
"spend": 6410980,
"age_bucket": "55+",
"gender": "female",
"conversion_sign_ups": 0
},
{
"impressions": 2381,
"swipes": 6,
"view_completion": 6,
"swipe_up_percent": 0.0025,
"spend": 43242099,
"age_bucket": "35-44",
"gender": "male",
"conversion_sign_ups": 0
},
{
"impressions": 48007,
"swipes": 82,
"view_completion": 176,
"swipe_up_percent": 0.0017,
"spend": 536629398,
"age_bucket": "18-20",
"gender": "male",
"conversion_sign_ups": 8
},
{
"impressions": 35379,
"swipes": 59,
"view_completion": 116,
"swipe_up_percent": 0.0017,
"spend": 464316698,
"age_bucket": "21-24",
"gender": "male",
"conversion_sign_ups": 10
},
{
"impressions": 16760,
"swipes": 18,
"view_completion": 44,
"swipe_up_percent": 0.0011,
"spend": 270528840,
"age_bucket": "25-34",
"gender": "male",
"conversion_sign_ups": 3
},
{
"impressions": 3201,
"swipes": 8,
"view_completion": 9,
"swipe_up_percent": 0.0025,
"spend": 59504925,
"age_bucket": "35+",
"gender": "male",
"conversion_sign_ups": 2
},
{
"impressions": 60964,
"swipes": 85,
"view_completion": 177,
"swipe_up_percent": 0.0014,
"spend": 696182537,
"age_bucket": "18-20",
"gender": "female",
"conversion_sign_ups": 22
},
{
"impressions": 595,
"swipes": 2,
"view_completion": 1,
"swipe_up_percent": 0.0034,
"spend": 11822674,
"age_bucket": "45-54",
"gender": "male",
"conversion_sign_ups": 0
},
{
"impressions": 46007,
"swipes": 58,
"view_completion": 104,
"swipe_up_percent": 0.0013,
"spend": 583008613,
"age_bucket": "21-24",
"gender": "female",
"conversion_sign_ups": 12
},
{
"impressions": 225,
"swipes": 0,
"view_completion": 2,
"swipe_up_percent": 0.0,
"spend": 4440022,
"age_bucket": "55+",
"gender": "male",
"conversion_sign_ups": 0
}
]
}
}
]
}
This API requests retrieves insights for an Ad, broken down by age and gender by using the parameter report_dimension=gender,age
.
Reporting Insights: Dimension and Pivots
On the 20th of March 2020 we announced the deprecation of the dimension
and pivots
parameters, please ensure that you have switched to
using report_dimension
by the 20th of June 2020. After the deprecation you will still be able to use dimension
and pivots
to retrieve
data finalized prior to the 20th June 2020.
The new parameter report_dimension
is described in Reporting Insights and Dimensions.
Dimension and Pivots
You can get reporting insights based on different dimensions like GEO, DEMO, INTEREST and DEVICE by using the parameters dimension
and
pivots
. Within each dimension, data can be broken down by different pivots. You can only query one dimension at a time. For insights
breakdown, only LIFETIME granularity is supported.
Dimension | Pivot | Required/Optional | Conditions |
---|---|---|---|
GEO | country | Yes | None |
region | No | dma has to be queried with region | |
dma | No | dma has to be queried with region | |
DEMO | gender | No | At least one of gender or age_bucket has to be specified if dimension is DEMO |
age_bucket | No | At least one of gender or age_bucket has to be specified if dimension is DEMO | |
INTEREST | interest_category_id | Yes | None |
interest_category_name | No | None | |
DEVICE | operating_system | Yes | None |
make | No | model has to be queried with make | |
model | No | model has to be queried with make |
The fields that can be broken down by dimenssion and pivots are:
Field | Description |
---|---|
impressions | Impression Count |
impression_composition | The percent of impressions served to the insights category |
uniques | # of unique impressions |
unique_composition | The percent of uniques served to the insights category |
spend | Amount spent (microcurrency) |
swipes | Swipe up Count |
Attribution windows
The attribution window is the time period in which a conversion will be counted after a user sees an ad. By default, Snap's attribution windows are 28 days post-swipe, 2 day post-view for engaged views (5 seconds or longer) and 1 day post-view (views shorter than 5 seconds).
Metrics and their variants
Conversions can be broken down by the method by which they were attributed, this table outlines the variant name that should be used in reporting requests.
Metric | Swipe variant | Engaged View variant | View variant |
---|---|---|---|
total_installs | total_installs_swipe_up | total_installs_engaged_view | total_installs_view |
android_installs | android_installs_swipe_up | android_installs_engaged_view | android_installs_view |
ios_installs | ios_installs_swipe_up | ios_installs_engaged_view | ios_installs_view |
conversion_purchases | conversion_purchases_swipe_up | conversion_purchases_engaged_view | conversion_purchases_view |
conversion_purchases_value | conversion_purchases_value_swipe_up | conversion_purchases_value_engaged_view | conversion_purchases_value_view |
conversion_save | conversion_save_swipe_up | conversion_save_engaged_view | conversion_save_view |
conversion_start_checkout | conversion_start_checkout_swipe_up | conversion_start_checkout_engaged_view | conversion_start_checkout_view |
conversion_add_cart | conversion_add_cart_swipe_up | conversion_add_cart_engaged_view | conversion_add_cart_view |
conversion_view_content | conversion_view_content_swipe_up | conversion_view_content_engaged_view | conversion_view_content_view |
conversion_add_billing | conversion_add_billing_swipe_up | conversion_add_billing_engaged_view | conversion_add_billing_view |
conversion_sign_ups | conversion_sign_ups_swipe_up | conversion_sign_ups_engaged_view | conversion_sign_ups_view |
conversion_searches | conversion_searches_swipe_up | conversion_searches_engaged_view | conversion_searches_view |
conversion_level_completes | conversion_level_completes_swipe_up | conversion_level_completes_engaged_view | conversion_level_completes_view |
conversion_app_opens | conversion_app_opens_swipe_up | conversion_app_opens_engaged_view | conversion_app_opens_view |
conversion_page_views | conversion_page_views_swipe_up | conversion_page_views_engaged_view | conversion_page_views_view |
conversion_subscribe | conversion_subscribe_swipe_up | conversion_subscribe_engaged_view | conversion_subscribe_view |
conversion_ad_click | conversion_ad_click_swipe_up | conversion_ad_click_engaged_view | conversion_ad_click_view |
conversion_ad_view | conversion_ad_view_swipe_up | conversion_ad_view_engaged_view | conversion_ad_view_view |
conversion_complete_tutorial | conversion_complete_tutorial_swipe_up | conversion_complete_tutorial_engaged_view | conversion_complete_tutorial_view |
conversion_invite | conversion_invite_swipe_up | conversion_invite_engaged_view | conversion_invite_view |
conversion_login | conversion_login_swipe_up | conversion_login_engaged_view | conversion_login_view |
conversion_share | conversion_share_swipe_up | conversion_share_engaged_view | conversion_share_view |
conversion_reserve | conversion_reserve_swipe_up | conversion_reserve_engaged_view | conversion_reserve_view |
conversion_achievement_unlocked | conversion_achievement_unlocked_swipe_up | conversion_achievement_unlocked_engaged_view | conversion_achievement_unlocked_view |
conversion_add_to_wishlist | conversion_add_to_wishlist_swipe_up | conversion_add_to_wishlist_engaged_view | conversion_add_to_wishlist_view |
conversion_spend_credits | conversion_spend_credits_swipe_up | conversion_spend_credits_engaged_view | conversion_spend_credits_view |
conversion_rate | conversion_rate_swipe_up | conversion_rate_engaged_view | conversion_rate_view |
conversion_start_trial | conversion_start_trial_swipe_up | conversion_start_trial_engaged_view | conversion_start_trial_view |
conversion_list_view | conversion_list_view_swipe_up | conversion_list_view_engaged_view | conversion_list_view_view |
custom_event_1 | custom_event_1_swipe_up | custom_event_1_engaged_view | custom_event_1_view |
custom_event_2 | custom_event_2_swipe_up | custom_event_2_engaged_view | custom_event_2_view |
custom_event_3 | custom_event_3_swipe_up | custom_event_3_engaged_view | custom_event_3_view |
custom_event_4 | custom_event_4_swipe_up | custom_event_4_engaged_view | custom_event_4_view |
custom_event_5 | custom_event_5_swipe_up | custom_event_5_engaged_view | custom_event_5_view |
Allowed combinations of attribution windows
Engaged View Conversions are always available with a fixed attribution window of two days, for this reason there is no need to provide an attribution window.
View window | Swipe window 1_DAY | Swipe window 7_DAY | Swipe window 28_DAY |
---|---|---|---|
none* | Allowed | Allowed | Allowed |
1_HOUR | Allowed | Allowed | Allowed |
3_HOUR | Allowed | Allowed | Allowed |
6_HOUR | Allowed | Allowed | Allowed |
1_DAY | Allowed | Allowed | Allowed |
7_DAY | Not Allowed | Allowed | Allowed |
28_DAY | Not Allowed | Not Allowed | Allowed |
*When using view_attribution_window=none no View conversions will be returned
Attribution windows example
curl "https://adsapi.snapchat.com/v1/campaigns/04dd5e26-7156-4e07-b2b8-2911ae3aaccc/stats?granularity=DAY&fields=impressions,spend,conversion_add_cart,conversion_add_cart_swipe_up,conversion_add_cart_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 name | Description |
---|---|
product_impressions | number of impressions for a product ID |
swipes | |
spend | microcents local currency |
Report Requirements
- Reports must be 1 day in length
- Start (start_time) & End Date (end_time) must be specified
Full reports for DPA (Async)
Due to the size of reports, DPA reporting runs on Snapchat’s asynchronous API and returns a file for the full DPA breakdown. The API call to the stats endpoint for a DPA report returns a report run ID. This run ID can be used to make a subsequent call to the stats_report endpoint to check its status. Upon completion, a signed URL is generated to download the report as a CSV; this CSV has a time to live of 24 hours.
Stats request - Step 1
curl "https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats?breakdown=campaign&granularity=DAY&swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY&start_time=2023-03-17&end_time=2023-03-18&fields=product_impressions,swipes,spend&position_stats=false&platform_stats=false&report_dimension=product&omit_empty=true&async=true&async_format=csv" -H "Authorization: Bearer meowmeowmeow"
{
"request_status": "SUCCESS",
"request_id": "<ID>",
"async_stats_reports": [
{
"sub_request_status": "SUCCESS",
"async_stats_report": {
"report_run_id": "ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6"
}
}
]
}
Additional Request Parameters
These are the specific request parameters necessary to call the DPA Async report API
Attribute | Values |
---|---|
report_dimension | product |
async | true |
async_format | csv |
Response - async_stats_report Object
Attribute | Description | Values |
---|---|---|
report_run_id | the ID of your reporting task | eg: "ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6" |
async_status | The current status of the reporting task. Once this changes to COMPLETED, the result field will be populated with the URL for the report. | RUNNING, COMPLETED |
result | This contains the URL of the report file | eg: "https://data-transfer.snapads.com/async-report/dpa_full/ASYNC_STATS:0efa41e1-5087-48af-8dbc-2cf8aefasdf66e6/4a6csdf1-3234-484b-b2cf-eeb6f1a63c3f.csv" |
CSV request - Step 2
curl "https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats_report?report_run_id=ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6" -H "Authorization: Bearer meowmeowmeow"
Report is running
{
"request_status": "SUCCESS",
"request_id": "<ID>",
"async_stats_reports": [
{
"sub_request_status": "SUCCESS",
"async_stats_report": {
"report_run_id": "ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6",
"async_status": "RUNNING",
"result": ""
}
}
]
}
Report is completed
{
"request_status": "SUCCESS",
"request_id": "<ID>",
"async_stats_reports": [
{
"sub_request_status": "SUCCESS",
"async_stats_report": {
"report_run_id": "ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6",
"async_status": "COMPLETED",
"result": "https://data-transfer.snapads.com/async-report/dpa_full/ASYNC_STATS:0efa41e1-5087-48af-8dbc-2cf8aefasdf66e6/4a6csdf1-3234-484b-b2cf-eeb6f1a63c3f.csv"
}
}
]
}
Top-K report for DPA
To support UI reporting and understand the performance of DPA among products with the highest level of spend, Snapchat supports a Top-K report, which will return the top 50 products per entity by impression volume (Campaign, Ad Set, and Ad). This API is similar to the standard reporting API used for non DPA ads.
Additional Request Parameters
These are the specific request parameters necessary to call the DPA Async report API
Attribute | Values |
---|---|
report_dimension | product_topk |
curl "https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats?breakdown=campaign&granularity=TOTAL&swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY&start_time=2020-03-17T00:00:00-07:00&end_time=2020-03-25T00:00:00-07:00&fields=product_impressions,swipes,spend,total_installs,conversion_purchases&position_stats=false&platform_stats=false&report_dimension=product_topk&omit_empty=true" -H "Authorization: Bearer meowmeowmeow"
{
"request_status": "SUCCESS",
"request_id": "5fb4467d00ff07d2b1b1968d810001737e616473617069736300016275696c642d36393939316436622d312d3430332d3100010142",
"total_stats": [
{
"sub_request_status": "SUCCESS",
"total_stat": {
"id": "<ID>",
"type": "AD_ACCOUNT",
"granularity": "TOTAL",
"swipe_up_attribution_window": "28_DAY",
"view_attribution_window": "1_DAY",
"start_time": "2020-10-27T00:00:00.000-07:00",
"end_time": "2020-10-29T00:00:00.000-07:00",
"finalized_data_end_time": "2020-11-17T00:00:00.000-08:00",
"breakdown_stats": {
"campaign": [
{
"id": "<CAMPAIGN_ID>",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"start_time": "2020-10-27T00:00:00.000-07:00",
"end_time": "2020-10-29T00:00:00.000-07:00",
"dimension_stats": [
{
"product_id": "56e39d8f1b0dd675f10e0131",
"product_impressions": 84051
},
{
"product_id": "577dfc15dac4a378150ebab0",
"product_impressions": 55271
},
{
"product_id": "5694f07db06a78118dd2bbae",
"product_impressions": 47643
},
{
"product_id": "56dff400cec25a1a9e1271cd",
"product_impressions": 26599
},
{
"product_id": "56eebe757505925c618e9807",
"product_impressions": 23737
},
{
"product_id": "569cbb6f16805211bb1f7750",
"product_impressions": 21171
},
{
"product_id": "57a6fad104e0d075a6084059",
"product_impressions": 19274
},
{
"product_id": "57ab01b93999d9602c743b8e",
"product_impressions": 12256
},
{
"product_id": "57ad3c3fd227704b8bab09dc",
"product_impressions": 12248
},
{
"product_id": "57a6c97c5bd8ec7787ea328f",
"product_impressions": 11340
},
{
"product_id": "569f56793fe3625b0cf56bd9",
"product_impressions": 7433
},
{
"product_id": "56e14676ae8c93398a13a7d3",
"product_impressions": 6597
},
{
"product_id": "56f24379f5f899740ec4c0b5",
"product_impressions": 6438
},
{
"product_id": "575645a524a8f27640d3d40c",
"product_impressions": 6419
},
{
"product_id": "5700b35e5581e05ce0b4adc3",
"product_impressions": 6056
},
{
"product_id": "576130685d3faf6218fd8dac",
"product_impressions": 5701
},
{
"product_id": "579eba20a037085566e39683",
"product_impressions": 1980
},
{
"product_id": "57adae01b1ce26244dd4012c",
"product_impressions": 1707
},
{
"product_id": "57a02216e3ada7734f02b275",
"product_impressions": 1185
},
{
"product_id": "579b220904af45576fae20a3",
"product_impressions": 1083
},
{
"product_id": "56b1adcdac5bc550738df9fb",
"product_impressions": 857
},
{
"product_id": "57623c6d823409625004be5e",
"product_impressions": 736
},
{
"product_id": "57b14c09689ce95b71558fff",
"product_impressions": 671
},
{
"product_id": "5779ced99bfad279a9783889",
"product_impressions": 573
},
{
"product_id": "56c29339a3537416ae4b7822",
"product_impressions": 556
}
...
]
}
]
},
"split_results": []
}
}
]
}
Viewability Metrics
Viewability Metrics are available given the following criteria;
- Metrics are available from the 1 April 2021
- Available in all granularities (HOUR, DAY, TOTAL, LIFETIME)
- Metrics cannot be broken down by Insights
- Story Ads are not covered by these metrics
Metrics
Metric | API field | Description |
---|---|---|
Viewable Impressions | viewable_impressions | Number of impressions that were 100% viewable on a user's screen for 1 second for display ads or 2 seconds for video ads. |
Non-Viewable Impressions | non_viewable_impressions | Number of impressions that did not meet the criteria for a viewable impression |
Viewable Rate | viewable_rate | The percentage of the time that your paid Snap Ad impression met the qualifying viewable impression criteria |
Measured Impressions | measured_impressions | Number of impressions that were measured for viewability |
Gross Impressions | gross_impressions | Total impressions delivered, this includes invalid traffic which is excluded from spend & all other delivery metrics. |
Paid Impressions | paid_impressions | The total number of times your ad was served to a Snapchatter. Tracked when the ad fully renders on a device for the first time during a Snapchatter’s viewing session. These impressions are net of invalid traffic. |
Audience filters
Audience filters were deprecated on 1 February 2023, this reporting information is preserved for Audience Filters created prior to the deprecation.
Field | Description | Availability |
---|---|---|
paid_impressions | The total number of times your ad was served to a Snapchatter. Tracked when the ad fully renders on a device for the first time during a Snapchatter's viewing session | Real Time |
earned_impressions | The number of times your ad was viewed after being shared by a Snapchatter via Chat or Stories | Within 24 hours |
shares | The number of times your ad was shared via Chat or Stories | Real Time |
saves | The number of times your ad was saved to Memories | Real Time |
spend | The total spend delivered in microcurrency | Real Time |
uniques | The number of unique paid impressions | Within 24 hours |
Stats are available at the Ad, Ad Squad and Campaign levels and are supported for all granularities: HOUR, DAY, TOTAL and LIFETIME.
curl "https://adsapi.snapchat.com/v1/adsquads/419d41d7-e4d4-4c13-803c-55e140a0ec1c/stats?granularity=LIFETIME&fields=paid_impressions,shares,saves,spend,uniques,earned_impressions"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "59b9cde600ff04b518a3c18db20001737e616473617069736300016275696c642d31386433356533662d312d3130302d3100010148",
"lifetime_stats": [
{
"sub_request_status": "SUCCESS",
"lifetime_stat": {
"id": "419d41d7-e4d4-4c13-803c-55e140a0eb1c",
"type": "AD_SQUAD",
"granularity": "LIFETIME",
"stats": {
"uniques": 186219,
"spend": 247184000,
"earned_impressions": 196140,
"paid_impressions": 199290,
"shares": 5762,
"saves": 799
},
"start_time": "2016-09-26T00:00:00.000-07:00",
"end_time": "2017-09-13T00:00:00.000-07:00",
"finalized_data_end_time": "2017-09-13T00:00:00.000-07:00"
}
}
]
}
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/{adsquad-id}/stats
Parameters
Parameter | Description |
---|---|
adsquad-id | Audience filter Ad squad ID |
Create Lead Gen Report
This request initiates a lead gen report for an Ad Account given the selected start time and end time, the request returns a Report id in
the form of report_run_id
which is then used to retrieve the report itself.
Data collected via Lead Gen Ads is not stored for more than 30 days, this also means that the start time can't be more than 30 days in the past.
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/leads_report?async_format=csv&start_time=2021-12-01T00:00:00-07:00&end_time=2021-12-14T00:00:00-07:00
The above command returns a report_run_id:
{
"request_status": "SUCCESS",
"request_id": "61b8c10a00ff08449824e366290001737e616473617069736300016275696c642d38333537336364642d312d3530332d3000010159",
"async_stats_reports": [
{
"sub_request_status": "SUCCESS",
"async_stats_report": {
"report_run_id": "ASYNC_STATS:2e480f4f-0c2a-463c-a883-841f88175449",
"async_status": "STARTED"
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/leads_report
Parameters
Parameter | Default value | Description |
---|---|---|
async_format | csv | |
start_time | Start time in ISO format | |
end_time | End time in ISO format |
Fetch Lead Gen Report
This request uses the report_run_id
in order to fetch the status of a report.
If the report is ready the request returns the URL of a list of leads in CSV format, the async_status
indicates whether the report is
completed and ready to be downloaded. If the report is ready the value of the async_status
is COMPLETED, if the report is still running
the async_status
will be RUNNING.
When a report is completed the url for downloading the data is found in the result attribute. This URL is valid for 48 hours.
curl "https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/leads_report?report_run_id=ASYNC_STATS:7766eab2-643e-4117-8b58-c9ee3fe854f3" \
-H "Authorization: Bearer meowmeowmeow"
Example #1 - Report in progress
{
"request_status": "SUCCESS",
"request_id": "61b8bf2d00ff07c8f092caf50b0001737e616473617069736300016275696c642d38333537336364642d312d3530332d3000010142",
"async_stats_reports": [
{
"sub_request_status": "SUCCESS",
"async_stats_report": {
"report_run_id": "ASYNC_STATS:7766eae2-643e-4117-8b58-c9ee3fe854f3",
"async_status": "RUNNING"
}
}
]
}
curl "https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/leads_report?report_run_id=ASYNC_STATS:7766eeb2-643e-4117-8b58-c9ee3fe854f3" \
-H "Authorization: Bearer meowmeowmeow"
Example #2 - Completed report
{
"request_status": "SUCCESS",
"request_id": "61b8bf2d00ff07c8f092caf50b0001737e616473617069736300016275696c642d38333537336364642d312d3530332d3000010142",
"async_stats_reports": [
{
"sub_request_status": "SUCCESS",
"async_stats_report": {
"report_run_id": "ASYNC_STATS:7766eeb2-643e-4117-8b58-c9ee3fe854f3",
"async_status": "COMPLETED",
"result": "https://data-transfer.snapads.com/async-report/native_lead/ASYNC_STATS:7766eeb2-643e-4117-8b58-c9ee3fe854f3/00ea875b-1645-4fe8-8825-aa7a351b260b.csv"
}
}
]
}
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/leads_report
Parameters
Parameter | Default value | Description |
---|---|---|
report_run_id | Report id | The Report id returned by API request to initiate a report |
Lead Gen Report
This is a list of fields in the Lead Gen Report and their properties.
Field Name | Type | Max Length | Required? | Description | Example |
---|---|---|---|---|---|
Date | Datetime | 17 | Yes | Date that lead was submitted. The timestamp is truncated to the beginning of the local day and the time is always "00:00:00" Format: "yyyy-MM-dd 00:00:00" | 2022-05-11 00:00:00 |
Ad Account Id | String | 36 | Yes | Ad account ID associated with the ad that generated the lead. Hyphen separated UUID string. | f0d4666f-9f60-4df7-94c8-423ca55b2a17 |
Campaign Id | String | 36 | Yes | Campaign ID associated with ad that generated the lead. Hyphen separated UUID string. | 033fe5aa-59b4-423d-8ab5-b7a7cf6c5242 |
Ad Set Id | String | 36 | Yes | Ad Set ID associated with ad that generated the lead. Hyphen separated UUID string. | ebad6081-f387-4bce-b6dc-9ea4d2cbefbc |
Ad Id | String | 36 | Yes | Ad ID associated with ad that generated the lead. Hyphen separated UUID string. | ca72035c-9f8d-409b-abee-5e2e0c943f9c |
First Name | String | Yes | First name of Snapchat User | Jane | |
Last Name | String | Yes | Last name of Snapchat User | Smith | |
Phone Number | String | Yes (Either Email Address or Phone Number) | ex: 818-555-1234, +13105558765 *Not all formatted the same | 818-555-1234 +13105558765 | |
Email Address | String | Yes (Either Email Address or Phone Number) | Email address of Snapchat user | johndoe@gmail.com | |
Address Line 1 | String | No | Address of Snapchat user, Line 1 | 19330 25th Ave | |
Address Line 2 | String | No | Address of Snapchat user, Line 2 | Unit 3 | |
Address Level 1 | String | No | Address city or town | Seattle | |
Address Level 2 | String | No | Address state, province, or region | WA | |
Postal Code | String | No | Postal code of Snapchat user | 94012 | |
Birthday | Date | 10 | No | Snapchat user's birthdate. Formatted "MM/DD/YYYY" | 05/20/1998 |
Job Title | String | No | Job title | Marketing Manager | |
Company Name | String | No | Company name | Snap, Inc. | |
Custom Field 1 | String | No | Can be one of the following based on the type of Custom Question: Single-select: key-value object that contains the answer that the user selected and "true": {answer:true} Multi-select: key-value object that contains all of the answers that the user selected and "true": {answer1:true, answer2: true, answer3: true, answer4:true} Short Answer: String that contains the answer that the user entered into the form. Date Widget: The date that the user entered in the format "MM/DD/YYYY" | {Pizza:true} {Pizza:true, Sushi:true, Hamburgers:true} This is what I entered into the form 01/02/2022 | |
Custom Field 2 | String | No | " | ||
Custom Field 3 | String | No | " | ||
Custom Field 4 | String | No | " | ||
Custom Field 5 | String | No | " | ||
Custom Field 6 | String | No | " | ||
Custom Field 7 | String | No | " | ||
Custom Field 8 | String | No | " | ||
Consent 1 | String | Disclaimers: 80 Answer: 5 Total: 86 | No | Disclaimer in the consent section of the form and the user's response. Data is a key-value string in the following format: disclaimer:answer "answer" will be "true" if the user consented and "false" if they did not consent. | do you consent?:true https://www.example.com:false |
Consent 2 | String | Disclaimers: 80 Answer: 5 Total: 86 | No | Disclaimer in the consent section of the form and the user's response. Data is a key-value string in the following format: disclaimer:answer "answer" will be "true" if the user consented and "false" if they did not consent. | do you consent?:true https://www.example.com:false |
Preferred Status | String | Preferred | Non-Preferred | No | Indicates whether this lead is preferred or non-preferred based on the responses to the qualifying questions. | Preferred |
Example Lead Gen Report
Here is an example Lead Gen Report .csv file. All the sample data is made-up; no actual user data is included.