Skip to main content
Skip table of contents

Snapchat

Overview

Vendor/Partner

Snapchat

Version

v1

API Documentation

https://marketingapi.snapchat.com/docs/#version

Sunset Date

None as of 04/04/2024

https://marketingapi.snapchat.com/docs/#version

Channel(s)

Refresh Time (CST)

7am / Real Time

Default backfill

29 Days

Alli Data Library

(error)

Getting Started

  1. Click the Request Snapchat Access button and grant access.

  2. Select the Ad Account that you would like to run a report on from the drop-down menu.

  3. Select the report type you would like to run

Limitations

Backfilling

When backfilling data that's more than a month, the job will be split into multiple jobs. Therefore, you will have to wait until all of them are done to get all of the results that you want.

Timezones

Snapchat gets each ad account’s specific timezone to use in the report from an endpoint that supplies account information.

Quotas

Snapchat doesn’t give specific numbers to the rate limits. The only information they can give are the names and types of the header whenever you hit the limit: https://developers.snapchat.com/api/docs/#rate-limits

Selectable Accounts

Accounts that show up after authentication does not guarantee access to the client. This datasource does NOT check whether the user the necessary access to request data from Snap. Below is an example of a permission related error:

CODE
None of the requested actions [READ_CONTAINER_ENTITY, READ_AD] can be authorized. Current user principal: 489aad24-1207-4672-be7d-a1bde5a53026. Container roles: [member, audience]"

Define your Data

Ads

Dimensions

Name

Type

Table Field Name

Description

Campaign Name

string

campaignName

Unique name of the campaign

Campaign ID

string

campaignId

Unique alphanumerical ID of the campaign

Adsquad Name

string

adsquadName

Unique name of the ad squad

Adsquad ID

string

adsquadId

Unique alphanumerical ID of the adsquad

Ad Name

string

adName

Unique name of the ad

Ad ID

string

adId

Unique alphanumerical ID of the Ad

Date

date

date

The date of when the metrics were snapshot

Metrics

Name

Type

Table Field Name

Description

Impressions

number

impressions

Impression Count

Swipes

number

swipes

Swipe-Up Count

View Time (milliseconds)

number

view_time_millis

Use screen_time_millis instead. Total Time Spent on top Snap Ad (milliseconds)

Screen Time (milliseconds)

number

screen_time_millis

Total Time Spent on top Snap Ad (milliseconds)

Quartile 1

number

quartile_1

Video Views to 25%

Quartile 2

number

quartile_2

Video Views to 50%

Quartile 3

number

quartile_3

Video Views to 75%

View Completion

number

view_completion

Video Views to completion

Spend

number

spend

Amount Spent (micro-currency)

Video Views

number

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

Attachment Avg View Time
(milliseconds)

number

attachment_avg_view_time_millis

Average Attachment View Time (milli-seconds)

Attachment Frequency

number

attachment_frequency

Average # of Attachment Views per User Reached

Attachment Quartile 1

number

attachment_quartile_1

Long Form Video Views to 25%

Attachment Quartile 2

number

attachment_quartile_2

Long Form Video Views to 50%

Attachment Quartile 3

number

attachment_quartile_3

Long Form Video Views to 75%

Attachment Total View Time (milliseconds)

number

attachment_total_view_time_millis

Total Attachment View Time (milliseconds)

Attachment Uniques

number

attachment_uniques

# of unique attachment impressions

Attachment View Completion

number

attachment_view_completion

Long Form Video Views to completion

Attachment Video Views

number

attachment_video_views

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

number

avg_view_time_millis

Use avg_screen_time_millis instead. Average Top Snap View Time per User Reached

Avg Screen Time Millis

number

avg_screen_time_millis

Average Top Snap view time across all impressions

Frequency

number

frequency

Average # of Impressions per User Reached

Swipe Up Percent

number

swipe_up_percent

% of Impressions that Swiped-Up

Uniques

number

uniques

description": "# of unique impressions

Video Views Time Based

number

video_views_time_based

The total number of impressions that meet the qualifying video view criteria of at least 2 seconds, not including swipe-ups

Video Views 15s

number

video_views_15s

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

number

story_opens

# of times users tapped on the ad tile in the feed to view the Story Ad

Story Completes

number

story_completes

# of times users viewed through to the last Snap of your Story Ad

Position Impressions

number

position_impressions

# the impression number for this story ad position

Position Uniques

number

position_uniques

# the unique viewer numbers for this story ad position

Position Frequency

number

position_frequency

# the frequency for this story ad position

Position Screen Time Millis

number

position_screen_time_millis

# the total view time in milliseconds for this story ad position

Position Swipe Up Percent

number

position_swipe_up_percent

# the swipe up rate for this story ad position

Avg Position Screen Time Millis

number

avg_position_screen_time_millis

# the average view time for this story ad position

Shares

number

shares

# of times lens/filter was shared in a Chat or Story

Saves

number

saves

# of times lens/filter was saved to Memories

Conversion Purchases

number

conversion_purchases

Number of attributed “PURCHASE” conversion events

Conversion Purchases (Swipe Up)

number

conversion_purchases_swipe_up

Number of attributed “PURCHASE” conversion events

Conversion Purchases (Ad View)

number

conversion_purchases_view

Number of attributed “PURCHASE” conversion events

Conversion Purchases Value

number

conversion_purchases_value

Value of attributed “PURCHASE” conversion events (micro currency in Ad Account’s currency)

Conversion Purchases Value (Swipe Up)

number

conversion_purchases_value_swipe_up

Value of attributed “PURCHASE” conversion events (micro currency in Ad Account’s currency)

Conversion Purchases Value (Ad View)

number

conversion_purchases_value_view

Value of attributed “PURCHASE” conversion events (micro currency in Ad Account’s currency)

Conversion Save

number

conversion_save

Number of attributed “SAVE” conversion events

Conversion Save (Swipe Up)

number

conversion_save_swipe_up

Number of attributed “SAVE” conversion events

Conversion Save (Ad View)

number

conversion_save_view

Number of attributed “SAVE” conversion events

Conversion Start Checkout

number

conversion_start_checkout

Number of attributed “START_CHECKOUT” conversion events

Conversion Start Checkout (Swipe Up)

number

conversion_start_checkout_swipe_up

Number of attributed “START_CHECKOUT” conversion events

Conversion Start Checkout (Ad View)

number

conversion_start_checkout_view

Number of attributed “START_CHECKOUT” conversion events

Conversion Add Cart

number

conversion_add_cart

Number of attributed “ADD_CART” conversion events

Conversion Add Cart (Swipe Up)

number

conversion_add_cart_swipe_up

Number of attributed “ADD_CART” conversion events

Conversion Add Cart (Ad View)

number

conversion_add_cart_view

Number of attributed “ADD_CART” conversion events

Conversion View Content

number

conversion_view_content

Number of attributed “VIEW_CONTENT” conversion events

Conversion View Content (Swipe Up)

number

conversion_view_content_swipe_up

Number of attributed “VIEW_CONTENT” conversion events

Conversion View Content (Ad View)

number

conversion_view_content_view

Number of attributed “VIEW_CONTENT” conversion events

Conversion Add Billing

number

conversion_add_billing

Number of attributed “ADD_BILLING” conversion events

Conversion Add Billing (Swipe Up)

number

conversion_add_billing_swipe_up

Number of attributed “ADD_BILLING” conversion events

Conversion Add Billing (Ad View)

number

conversion_add_billing_view

Number of attributed “ADD_BILLING” conversion events

Conversion Sign Ups

number

conversion_sign_ups

Number of attributed “SIGN_UP” conversion events

Conversion Sign Ups (Swipe Up)

number

conversion_sign_ups_swipe_up

Number of attributed “SIGN_UP” conversion events

Conversion Sign Ups (Ad View)

number

conversion_sign_ups_view

Number of attributed “SIGN_UP” conversion events

Conversion Searches

number

conversion_searches

Number of attributed “SEARCH” conversion events

Conversion Searches (Swipe Up)

number

conversion_searches_swipe_up

Number of attributed “SEARCH” conversion events

Conversion Searches (Ad View)

number

conversion_searches_view

Number of attributed “SEARCH” conversion events

Conversion Level Completes

number

conversion_level_completes

Number of attributed “LEVEL_COMPLETE” conversion events

Conversion Level Completes (Swipe Up)

number

conversion_level_completes_swipe_up

Number of attributed “LEVEL_COMPLETE” conversion events

Conversion Level Completes (Ad View)

number

conversion_level_completes_view

Number of attributed “LEVEL_COMPLETE” conversion events

Conversion App Opens

number

conversion_app_opens

Number of attributed “APP_OPEN” conversion events

Conversion App Opens (Swipe Up)

number

conversion_app_opens_swipe_up

Number of attributed “APP_OPEN” conversion events

Conversion App Opens (Ad View)

number

conversion_app_opens_view

Number of attributed “APP_OPEN” conversion events

Conversion Page Views

number

conversion_page_views

Number of attributed “PAGE_VIEW” conversion events

Conversion Page Views (Swipe Up)

number

conversion_page_views_swipe_up

Number of attributed “PAGE_VIEW” conversion events

Conversion Page Views (Ad View)

number

conversion_page_views_view

Number of attributed “PAGE_VIEW” conversion events

Conversion Subscribe

number

conversion_subscribe

Number of attributed “SUBSCRIBE” conversion events

Conversion Subscribe (Swipe Up)

number

conversion_subscribe_swipe_up

Number of attributed “SUBSCRIBE” conversion events

Conversion Subscribe (Ad View)

number

conversion_subscribe_view

Number of attributed “SUBSCRIBE” conversion events

Conversion Ad Click

number

conversion_ad_click

Number of attributed “AD_CLICK” conversion events

Conversion Ad Click (Swipe Up)

number

conversion_ad_click_swipe_up

Number of attributed “AD_CLICK” conversion events

Conversion Ad Click (Ad View)

number

conversion_ad_click_view

Number of attributed “AD_CLICK” conversion events

Conversion Ad View

number

conversion_ad_view

Number of attributed “AD_VIEW” conversion events

Conversion Ad View (Swipe Up)

number

conversion_ad_view_swipe_up

Number of attributed “AD_VIEW” conversion events

Conversion Ad View (Ad View)

number

conversion_ad_view_view

Number of attributed “AD_VIEW” conversion events

Conversion Complete Tutorial

number

conversion_complete_tutorial

Number of attributed “COMPLETE_TUTORIAL” conversion events

Conversion Complete Tutorial (Swipe Up)

number

conversion_complete_tutorial_swipe_up

Number of attributed “COMPLETE_TUTORIAL” conversion events

Conversion Complete Tutorial (Ad View)

number

conversion_complete_tutorial_view

Number of attributed “COMPLETE_TUTORIAL” conversion events

Conversion Invite

number

conversion_invite

Number of attributed “INVITE” conversion events

Conversion Invite (Swipe Up)

number

conversion_invite_swipe_up

Number of attributed “INVITE” conversion events

Conversion Invite (Ad View)

number

conversion_invite_view

Number of attributed “INVITE” conversion events

Conversion Login

number

conversion_login

Number of attributed “LOGIN” conversion events

Conversion Login (Swipe Up)

number

conversion_login_swipe_up

Number of attributed “LOGIN” conversion events

Conversion Login (Ad View)

number

conversion_login_view

Number of attributed “LOGIN” conversion events

Conversion Share

number

conversion_share

Number of attributed “SHARE” conversion events

Conversion Share (Swipe Up)

number

conversion_share_swipe_up

Number of attributed “SHARE” conversion events

Conversion Share (Ad View)

number

conversion_share_view

Number of attributed “SHARE” conversion events

Conversion Reserve

number

conversion_reserve

Number of attributed “RESERVE” conversion events

Conversion Reserve (Swipe Up)

number

conversion_reserve_swipe_up

Number of attributed “RESERVE” conversion events

Conversion Reserve (Ad View)

number

conversion_reserve_view

Number of attributed “RESERVE” conversion events

Conversion Achievement Unlocked

number

conversion_achievement_unlocked

Number of attributed “ACHIEVEMENT_UNLOCKED” conversion events

Conversion Achievement Unlocked (Swipe Up)

number

conversion_achievement_unlocked_swipe_up

Number of attributed “ACHIEVEMENT_UNLOCKED” conversion events

Conversion Achievement Unlocked (Ad View)

number

conversion_achievement_unlocked_view

Number of attributed “ACHIEVEMENT_UNLOCKED” conversion events

Conversion Add To Wishlist

number

conversion_add_to_wishlist

Number of attributed “ADD_TO_WISHLIST” conversion events

Conversion Spend Credits

number

conversion_spend_credits

Number of attributed “SPENT_CREDITS” conversion events

Conversion Rate

number

conversion_rate

Number of attributed “RATE” conversion events

Conversion Rate (Swipe Up)

number

conversion_rate_swipe_up

Number of attributed “RATE” conversion events

Conversion Rate (Ad View)

number

conversion_rate_view

Number of attributed “RATE” conversion events

Conversion Start Trial

number

conversion_start_trial

Number of attributed “START_TRIAL” conversion events

Conversion List View

number

conversion_list_view

Number of attributed “LIST_VIEW” conversion events

Conversion Visit

number

conversion_visit

Number of attributed “VISIT” conversion events

Conversion Visit Value

number

conversion_visit_value

Value of attributed “VISIT” conversion events (in Ad Account’s currency)

Custom Event 1

number

custom_event_1

Number of attributed “CUSTOM_EVENT_1” conversion events

Custom Event 2

number

custom_event_2

Number of attributed “CUSTOM_EVENT_2” conversion events

Custom Event 3

number

custom_event_3

Number of attributed “CUSTOM_EVENT_3” conversion events

Custom Event 4

number

custom_event_4

Number of attributed “CUSTOM_EVENT_4” conversion events

Custom Event 5

number

custom_event_5

Number of attributed “CUSTOM_EVENT_5” conversion events

Total Installs

number

total_installs

Total # of App Installs

Android Installs

number

android_installs

# of Android App Installs

Ios Installs

number

ios_installs

# of iOS App Installs

AdAccounts Country

Dimensions

Name

Type

Table Field Name

Description

Ad ID

string

adId

Unique alphanumerical ID of an Ad

country

string

Country

Country codes for the geolocation. For example, the United States would be 'US'

Date

date

date

The date of when the metrics were snapshot

Metrics

Name

Type

Table Field Name

Description

Impressions

number

impressions

Impression Count

Swipes

number

swipes

Swipe-Up Count

Quartile 1

number

quartile_1

Video Views to 25%

Quartile 2

number

quartile_2

Video Views to 50%

Quartile 3

number

quartile_3

Video Views to 75%

View Completion

number

view_completion

Video Views to completion

Spend

number

spend

Amount Spent (micro-currency)

Video Views

number

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

Attachment Quartile 1

number

attachment_quartile_1

Long Form Video Views to 25%

Attachment Quartile 2

number

attachment_quartile_2

Long Form Video Views to 50%

Attachment Quartile 3

number

attachment_quartile_3

Long Form Video Views to 75%

Attachment Total View Time (milliseconds)

number

attachment_total_view_time_millis

Total Attachment View Time (milliseconds)

Attachment View Completion

number

attachment_view_completion

Long Form Video Views to completion

Attachment Video Views

number

attachment_video_views

Long Form Video Attachment Views, viewed for at least 10 consecutive seconds or reached 97% of the Long Form Video duration

Story Opens

number

story_opens

# of times users tapped on the ad tile in the feed to view the Story Ad

Story Completes

number

story_completes

# of times users viewed through to the last Snap of your Story Ad

Shares

number

shares

# of times lens/filter was shared in a Chat or Story

Saves

number

saves

# of times lens/filter was saved to Memories

Conversion Purchases

number

conversion_purchases

Number of attributed “PURCHASE” conversion events

Conversion Purchases Value

number

conversion_purchases_value

Value of attributed “PURCHASE” conversion events (micro currency in Ad Account’s currency)

Conversion Save

number

conversion_save

Number of attributed “SAVE” conversion events

Conversion Start Checkout

number

conversion_start_checkout

Number of attributed “START_CHECKOUT” conversion events

Conversion Add Cart

number

conversion_add_cart

Number of attributed “ADD_CART” conversion events

Conversion View Content

number

conversion_view_content

Number of attributed “VIEW_CONTENT” conversion events

Conversion Add Billing

number

conversion_add_billing

Number of attributed “ADD_BILLING” conversion events

Conversion Sign Ups

number

conversion_sign_ups

Number of attributed “SIGN_UP” conversion events

Conversion Searches

number

conversion_searches

Number of attributed “SEARCH” conversion events

Conversion Level Completes

number

conversion_level_completes

Number of attributed “LEVEL_COMPLETE” conversion events

Conversion App Opens

number

conversion_app_opens

Number of attributed “APP_OPEN” conversion events

Conversion Page Views

number

conversion_page_views

Number of attributed “PAGE_VIEW” conversion events

Conversion Subscribe

number

conversion_subscribe

Number of attributed “SUBSCRIBE” conversion events

Conversion Ad Click

number

conversion_ad_click

Number of attributed “AD_CLICK” conversion events

Conversion Ad View

number

conversion_ad_view

Number of attributed “AD_VIEW” conversion events

Conversion Complete Tutorial

number

conversion_complete_tutorial

Number of attributed “COMPLETE_TUTORIAL” conversion events

Conversion Invite

number

conversion_invite

Number of attributed “INVITE” conversion events

Conversion Login

number

conversion_login

Number of attributed “LOGIN” conversion events

Conversion Share

number

conversion_share

Number of attributed “SHARE” conversion events

Conversion Reserve

number

conversion_reserve

Number of attributed “RESERVE” conversion events

Conversion Achievement Unlocked

number

conversion_achievement_unlocked

Number of attributed “ACHIEVEMENT_UNLOCKED” conversion events

Conversion Add To Wishlist

number

conversion_add_to_wishlist

Number of attributed “ADD_TO_WISHLIST” conversion events

Conversion Spend Credits

number

conversion_spend_credits

Number of attributed “SPENT_CREDITS” conversion events

Conversion Rate

number

conversion_rate

Number of attributed “RATE” conversion events

Conversion Start Trial

number

conversion_start_trial

Number of attributed “START_TRIAL” conversion events

Conversion List View

number

conversion_list_view

Number of attributed “LIST_VIEW” conversion events

Conversion Visit

number

conversion_visit

Number of attributed “VISIT” conversion events

Custom Event 1

number

custom_event_1

Number of attributed “CUSTOM_EVENT_1” conversion events

Custom Event 2

number

custom_event_2

Number of attributed “CUSTOM_EVENT_2” conversion events

Custom Event 3

number

custom_event_3

Number of attributed “CUSTOM_EVENT_3” conversion events

Custom Event 4

number

custom_event_4

Number of attributed “CUSTOM_EVENT_4” conversion events

Custom Event 5

number

custom_event_5

Number of attributed “CUSTOM_EVENT_5” conversion events

Total Installs

number

total_installs

Total # of App Installs

AdAccounts Region

Dimensions

Name

Type

Table Field Name

Description

Ad ID

string

adId

Unique alphanumerical ID of an Ad

region

string

Region

ID of the region Location

Date

date

date

The date of when the metrics were snapshot

Metrics

Name

Type

Table Field Name

Description

Impressions

number

impressions

Impression Count

Swipes

number

swipes

Swipe-Up Count

Quartile 1

number

quartile_1

Video Views to 25%

Quartile 2

number

quartile_2

Video Views to 50%

Quartile 3

number

quartile_3

Video Views to 75%

View Completion

number

view_completion

Video Views to completion

Spend

number

spend

Amount Spent (micro-currency)

Video Views

number

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

Attachment Quartile 1

number

attachment_quartile_1

Long Form Video Views to 25%

Attachment Quartile 2

number

attachment_quartile_2

Long Form Video Views to 50%

Attachment Quartile 3

number

attachment_quartile_3

Long Form Video Views to 75%

Attachment Total View Time (milliseconds)

number

attachment_total_view_time_millis

Total Attachment View Time (milliseconds)

Attachment View Completion

number

attachment_view_completion

Long Form Video Views to completion

Attachment Video Views

number

attachment_video_views

Long Form Video Attachment Views, viewed for at least 10 consecutive seconds or reached 97% of the Long Form Video duration

Story Opens

number

story_opens

# of times users tapped on the ad tile in the feed to view the Story Ad

Story Completes

number

story_completes

# of times users viewed through to the last Snap of your Story Ad

Shares

number

shares

# of times lens/filter was shared in a Chat or Story

Saves

number

saves

# of times lens/filter was saved to Memories

AdAccounts DMA

Dimensions

Name

Type

Table Field Name

Description

Ad ID

string

adId

Unique alphanumerical ID of an Ad

dma

string

DMA

The DMA (city/ geographical location) of user

Date

date

date

The date of when the metrics were snapshot

Metrics

Name

Type

Table Field Name

Description

Impressions

number

impressions

Impression Count

Swipes

number

swipes

Swipe-Up Count

Quartile 1

number

quartile_1

Video Views to 25%

Quartile 2

number

quartile_2

Video Views to 50%

Quartile 3

number

quartile_3

Video Views to 75%

View Completion

number

view_completion

Video Views to completion

Spend

number

spend

Amount Spent (micro-currency)

Video Views

number

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

Attachment Quartile 1

number

attachment_quartile_1

Long Form Video Views to 25%

Attachment Quartile 2

number

attachment_quartile_2

Long Form Video Views to 50%

Attachment Quartile 3

number

attachment_quartile_3

Long Form Video Views to 75%

Attachment Total View Time (milliseconds)

number

attachment_total_view_time_millis

Total Attachment View Time (milliseconds)

Attachment View Completion

number

attachment_view_completion

Long Form Video Views to completion

Attachment Video Views

number

attachment_video_views

Long Form Video Attachment Views, viewed for at least 10 consecutive seconds or reached 97% of the Long Form Video duration

Story Opens

number

story_opens

# of times users tapped on the ad tile in the feed to view the Story Ad

Story Completes

number

story_completes

# of times users viewed through to the last Snap of your Story Ad

Shares

number

shares

# of times lens/filter was shared in a Chat or Story

Saves

number

saves

# of times lens/filter was saved to Memories

Endpoints

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.