Lenses
Lens AR experiences are a powerful and memorable way to connect with consumers on a massive scale using augmented reality.
Lens Implementation Details
- The advertiser will create a Lens with a target audience and a cost-per-impression bid.
- When a user opens the Lens carousel, Snapchat will run a second price auction containing all the Lenses targeting that user.
- The Lens that wins the auction will be inserted into the Lens section of the carousel.
- If the Lens is swiped on/over by the user, then the advertiser will be billed for the impression. An advertiser will only be billed once per Lens carousel session: while a user can swipe back and forth over the Lens during the session, the advertiser will only be billed for the first swipe in the session.
- If a user either posts the Lens to their story or sends the Lens in a Direct Snap, then the advertiser will not be charged for any of the resulting views.
Create a Campaign
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"campaigns": [{"name": "Lens Campaign", "ad_account_id": "3b0fbace-04b4-4f04-a425-33b5e0af1dab", "status": "ACTIVE", "start_time": "2016-08-11T22:00:00.000Z"}]}' \
"https://adsapi.snapchat.com/v1/adaccounts/3b0fbace-04b4-4f04-a425-33b5e0af1dab/campaigns"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b002ad00ff07e1f50fd2267f0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
"campaigns": [
{
"sub_request_status": "success",
"campaign": {
"id": "5b48880f-bf65-495c-9810-2f4763add4cb",
"updated_at": "2020-02-04T05:33:33.876Z",
"created_at": "2020-02-04T05:33:33.876Z",
"name": "Lens Campaign",
"ad_account_id": "3b0fbace-04b4-4f04-a425-33b5e0af1dab",
"status": "ACTIVE",
"start_time": "2020-02-01T22:00:00.000Z"
}
}
]
}
This will create a campaign within a specified ad account, note Ad Squads with the type
LENS cannot be mixed with other types of Ad Squads
(Snap Ads, Audience filters etc).
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/campaigns
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Lens Ad Squad
Attribute | Description | Required | Possible Values |
---|---|---|---|
campaign_id | Campaign ID | R | |
name | Ad Squad name | R | |
billing_event | Billing Event | R | IMPRESSION |
bid_micro | Max Bid (micro-currency) | R | |
auto_bid | Allow Snapchat to automatically set the bid to recommended amount | O (One of auto_bid, target_bid or bid_micro must be set) | true/false. |
target_bid | Allows Snapchat to adjust the bid aiming to keep your average CPA at or below the amount set by the ad set end date | O (One of auto_bid, target_bid or bid_micro must be set) | true/false. |
pixel_id | Pixel to be associated with the Ad Squad | O | |
start_time | Start time | R | |
end_time | End time | R | |
optimization_goal | Optimization Goal | R | IMPRESSIONS |
placement_v2.config | Placement | R | CUSTOM |
placement_v2.platforms | Placement | R | SNAPCHAT |
placement_v2.snapchat_positions | Placement | R | CAMERA |
status | Ad Squad status | R | ACTIVE, PAUSED |
type | Ad Squad Type | R | LENS |
targeting | Targeting spec | R | Any valid targeting options |
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adsquads": [{"name": "Lens adsquad","status": "ACTIVE","campaign_id": "5b48880f-bf65-495c-9810-2f4763add4cb","type": "LENS","placement_v2": {"config": "CUSTOM","platforms": ["SNAPCHAT"],"snapchat_positions": ["CAMERA"]},"billing_event": "IMPRESSION","bid_micro": "200000000","daily_budget_micro": "2000000000","start_time": "2020-08-15T12:16:17.444-07:00","end_time": "2020-08-19T12:16:17.444-07:00","optimization_goal": "IMPRESSIONS","targeting": {"regulated_content": "false","demographics": [{"min_age": "21","max_age": "24"}],"geos": [{"country_code": "us"}]}}]}' \
https://adsapi.snapchat.com/v1/campaigns/5b48880f-bf65-495c-9810-2f4763add4cb/adsquads
The above request returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e3c0a3d00ff077b3836beabb80001737e616473617069736300016275696c642d62343864336664332d312d3332332d3000010151",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "caff7533-52e1-4412-9ef2-18232dbcd1ba",
"updated_at": "2020-02-06T12:44:45.818Z",
"created_at": "2020-02-06T12:44:45.818Z",
"name": "Lens adsquad",
"status": "ACTIVE",
"campaign_id": "5b48880f-bf65-495c-9810-2f4763add4cb",
"type": "LENS",
"targeting": {
"regulated_content": false,
"demographics": [
{
"min_age": "21",
"max_age": "24"
}
],
"geos": [
{
"country_code": "us"
}
]
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "CUSTOM",
"platforms": ["SNAPCHAT"],
"snapchat_positions": ["CAMERA"]
},
"billing_event": "IMPRESSION",
"bid_micro": 200000000,
"auto_bid": false,
"target_bid": false,
"daily_budget_micro": 2000000000,
"start_time": "2020-08-15T19:16:17.444Z",
"end_time": "2020-08-19T19:16:17.444Z",
"optimization_goal": "IMPRESSIONS",
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD"
}
}
]
}
This creates an Ad Squad within a Campaign, note Ad Squads with the type
LENS cannot be mixed with other types of Ad Squads (Snap Ads,
Audience filters etc).
HTTP Request
POST https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads
Parameters
Parameter | Default | Description |
---|---|---|
campaign_id | Campaign ID |
Lens Media
Unlike other Creatives, the Media file for a Lens Creative is not uploaded via the API, it's instead created in Snapchat Lens Studio or Lens Web Builder and then transferred to the Ad Account via the Lens folder in Business Manager.
Lens Media Attributes
These attributes are unique to the Media type LENS_PACKAGE
Attribute | Description | Possible Values |
---|---|---|
type | The Media type | LENS_PACKAGE |
lens_package_metadata.lens_icon_media_id | Media ID of the lens icon | |
lens_package_metadata.default_camera | Default camera when lens opens | BOTH, FACE, WORLD |
Lens Preview Media
Lens preview media is sometimes available for LENS_PACKAGE media via the Lens Preview endpoint.
Create the Creative - Lens
When a Lens is created in Snapchat Lens Studio, both the Media and the Creative will automatically be set up. You can however re-use the Lens media if you wish to set up a new Creative.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
name | Creative name | R | |
top_snap_media_id | Media ID of type LENS_PACKAGE | R | |
type | Creative Type | R | LENS, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_WEB_VIEW |
ad_product | Ad product | R | LENS |
brand_name | Brand Name | R (required but not displayed) | 25 characters max |
headline | Headline | R (required but not displayed) | 34 characters max |
curl -X POST \
-d '{"creatives": [{"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1","name" : "Honey Badger Lens","type": "LENS","top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01","ad_product": "LENS","headline": "Try the Honey Badger Lens","brand_name": "Honey Badger"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f1/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e3c5e7a00ff07ac2c051bd68e0001737e616473617069736300016275696c642d62343864336664332d312d3332332d3000010118",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "0091127a-1c58-4b0b-981d-d419d65cc87c",
"updated_at": "2020-02-06T18:44:12.044Z",
"created_at": "2020-02-06T18:44:12.044Z",
"name": "Honey Badger Lens",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
"type": "LENS",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Try the Honey Badger Lens",
"brand_name": "Honey Badger",
"render_type": "STATIC",
"top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01",
"top_snap_crop_position": "MIDDLE",
"ad_product": "LENS"
}
}
]
}
This creates a new Creative of the type LENS where the attribute top_snap_media_id
is of the type LENS_PACKAGE.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create the Creative - Lens with App Install Attachment
When a Lens is created in Snapchat Lens Studio or Lens Web Builder, both the Media and the Creative will automatically be set up, you can however re-use the Lens media if you wish to set up a new Creative.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
name | Creative name | R | |
top_snap_media_id | Media ID of type LENS_PACKAGE | R | |
type | Creative Type | R | LENS_APP_INSTALL |
ad_product | Ad product | R | LENS |
brand_name | Brand Name | R (required but not displayed) | 25 characters max |
headline | Headline | R (required but not displayed) | 34 characters max |
call_to_action | Call to Action | R | Please refer to the Creative type to CTA mapping table |
Additional Attributes
The following attributes should be added to the basic creative under the property app_install_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
app_name | App name | R | |
ios_app_id | iOS App ID | R | |
android_app_url | Google Play Store ID | R | (eg "com.x.y") |
icon_media_id | Icon Media ID | R | |
product_page_id | Custom product page ID from iOS App Store. | O | 45812c9b-c296-43d3-c6a0-c5a02f74bf6e |
curl -X POST \
-d '{"creatives": [{"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1","name" : "Honey Badger Lens with App Install Attachment","type": "LENS_APP_INSTALL","top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01","ad_product": "LENS","headline": "Try the Honey Badger Lens","brand_name": "Honey Badger","call_to_action": "INSTALL_NOW","app_install_properties": {"app_name": "Bitmoji - Your Personal Emoji","ios_app_id": "868077558","android_app_url": "com.bitstrips.imoji","icon_media_id": "73b5deb6-5b2c-43b4-b60d-983bc344a4a2"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f1/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e42e3c700ff04d097d68c02810001737e616473617069736300016275696c642d63343664356339642d312d3332352d300001011a",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "1deb9eda-83bb-419d-a86c-67e2a7025385",
"updated_at": "2020-02-11T17:26:32.402Z",
"created_at": "2020-02-11T17:26:32.402Z",
"name": "Honey Badger Lens with App Install Attachment",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
"type": "LENS_APP_INSTALL",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Try the Honey Badger Lens",
"brand_name": "Honey Badger",
"call_to_action": "INSTALL_NOW",
"render_type": "STATIC",
"top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01",
"top_snap_crop_position": "MIDDLE",
"app_install_properties": {
"app_name": "Bitmoji - Your Personal Emoji",
"ios_app_id": "868077558",
"android_app_url": "com.bitstrips.imoji",
"icon_media_id": "73b5deb6-5b2c-43b4-b60d-983bc344a4a2"
},
"ad_product": "LENS"
}
}
]
}
This creates a new Creative of the type LENS_APP_INSTALL where the attribute top_snap_media_id
is of the type LENS_PACKAGE, and where the
app_install_properties
specify the attributes for the App Install Attachment.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create Lens with Deep Link Attachment
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
name | Creative name | R | |
top_snap_media_id | Media ID of type LENS_PACKAGE | R | |
type | Creative Type | R | LENS_DEEP_LINK |
ad_product | Ad product | R | LENS |
brand_name | Brand Name | R (required but not displayed) | 25 characters max |
headline | Headline | R (required but not displayed) | 34 characters max |
call_to_action | Call to Action | R | Please refer to the Creative type to CTA mapping table |
Additional Attributes
The following attributes should be added to the basic creative under the property deep_link_properties.
| Attribute | Description | Required | | --------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | ------------------------------- | | deep_link_uri | Deep Link URL | R | | app_name | App name | R | | ios_app_id | iOS App ID | Optional but one of ios_app_id or android_app_url is required | | android_app_url | Google Play Store ID | Optional but one of ios_app_id or android_app_url is required | | icon_media_id | Icon Media ID | R | | fallback_type | Type of fallback to be used when user doesn't have the app | O | APP_INSTALL (default), WEB_SITE | | web_view_fallback_url | Fallback web url to be used | O | | product_page_id | Custom Product Page ID on iOS App Store | O |
curl -X POST \
-d '{"creatives": [{"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1","name" : "A new Lens with Deep Link Attachment","type": "LENS_DEEP_LINK","top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01","ad_product": "LENS","headline": "Try the Honey Badger Lens","brand_name": "Honey Badger","call_to_action": "TRY","deep_link_properties": {"deep_link_uri": "bitmoji://home","app_name": "Bitmoji - Your Personal Emoji","ios_app_id": "868077558","android_app_url": "com.bitstrips.imoji","icon_media_id": "73b5deb6-5b2c-43b4-b60d-983bc344a4a2","fallback_type": "APP_INSTALL"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f1/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e42ff007200ff071b3da02f5e6c0001737e616473617069736300016275696c642d63343664356339642d312d3332352d3000010110",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "d1b888eb-8998-42e3-9e73-45b5b5e8938d",
"updated_at": "2020-02-11T19:24:35.553Z",
"created_at": "2020-02-11T19:24:35.553Z",
"name": "A new Lens with Deep Link Attachment",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
"type": "LENS_DEEP_LINK",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Try the Honey Badger Lens",
"brand_name": "Honey Badger",
"call_to_action": "TRY",
"render_type": "STATIC",
"top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01",
"top_snap_crop_position": "MIDDLE",
"deep_link_properties": {
"deep_link_uri": "bitmoji://home",
"app_name": "Bitmoji - Your Personal Emoji",
"ios_app_id": "868077558",
"android_app_url": "com.bitstrips.imoji",
"icon_media_id": "73b5deb6-5b2c-43b4-b60d-983bc344a4a2",
"fallback_type": "APP_INSTALL"
},
"ad_product": "LENS"
}
}
]
}
This creates a new Creative of the type LENS_APP_INSTALL where the attribute top_snap_media_id
is of the type LENS_PACKAGE, and where the
deep_link_properties
specify the attributes for the Deep link Attachment.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create Lens with Web View Attachment
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
name | Creative name | R | |
top_snap_media_id | Media ID of type LENS_PACKAGE | R | |
type | Creative Type | R | LENS_WEB_VIEW |
ad_product | Ad product | R | LENS |
brand_name | Brand Name | R (required but not displayed) | 25 characters max |
headline | Headline | R (required but not displayed) | 34 characters max |
call_to_action | Call to Action | R | Please refer to the Creative type to CTA mapping table |
Additional Attributes
The following attributes should be added to the basic creative under the property web_view_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
url | Web view URL | R | |
allow_snap_javascript_sdk | Allow Snapchat Javascript SDK to autofill form fields | O | true/false |
block_preload | Block Snapchat from preloading the web page | O | true/false |
IMPORTANT! Shopify advertisers using the Snapchat Ads App for Shopify will have their "snap_campaign_id" URL parameter set to a default, unique identifier for web view and deep link ads. This is to ensure proper attribution in the Shopify Admin Dashboard. The "snap_campaign_id" URL parameter cannot be overwritten by the Snapchat URL Macros builder or with url_macro_parameters.
curl -X POST \
-d '{"creatives": [{"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1","name" : "A new Lens with Web View Attachment","type": "LENS_WEB_VIEW","top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01","ad_product": "LENS","headline": "Try the Honey Badger Lens","brand_name": "Honey Badger","call_to_action": "GET_NOW","web_view_properties": {"url": "http://www.example.com","allow_snap_javascript_sdk": "false","block_preload": "true"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f1/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e43d97400ff00ffe6fb1765c4350001737e616473617069736300016275696c642d63343664356339642d312d3332352d3000010119",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "b8f8dfb3-7738-4765-bd8e-ff312a34740d",
"updated_at": "2020-02-12T10:54:45.363Z",
"created_at": "2020-02-12T10:54:45.363Z",
"name": "A new Lens with Web View Attachment",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
"type": "LENS_WEB_VIEW",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Try the Honey Badger Lens",
"brand_name": "Honey Badger",
"call_to_action": "GET_NOW",
"render_type": "STATIC",
"top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01",
"top_snap_crop_position": "MIDDLE",
"web_view_properties": {
"url": "http://www.example.com",
"allow_snap_javascript_sdk": false,
"use_immersive_mode": false,
"deep_link_urls": [],
"block_preload": true
},
"ad_product": "LENS"
}
}
]
}
This creates a new Creative of the type LENS_WEB_VIEW where the attribute top_snap_media_id
is of the type LENS_PACKAGE, and where the
web_view_properties
specify the attributes for the Web View Attachment.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create the Ad
This endpoint creates an Ad within an Ad Squad, note that the type
attribute should match the Creative type of the Lens.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_squad_id | Ad Squad ID | R | |
creative_id | Creative ID | R | |
name | Ad name | R | |
type | Ad type | R | LENS, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_REMOTE_WEBPAGE |
review_status | Ad Review Status | READ ONLY | PENDING, APPROVED, REJECTED |
review_status_reason | List of Ad Review Rejection Reasons | READ ONLY | if rejected, list of reasons |
status | Ad status | R | ACTIVE, PAUSED |
Ad Type <-> Creative Type Mapping
Ad Type | Allowed Creative Lens Type |
---|---|
LENS | LENS |
LENS_REMOTE_WEBPAGE | LENS_WEB_VIEW |
LENS_APP_INSTALL | LENS_APP_INSTALL |
LENS_DEEP_LINK | LENS_DEEP_LINK |
curl -X POST \
-d '{"ads":[{"ad_squad_id": "caff7533-52e1-4412-9ef2-18232dbcd1ba", "creative_id":"0091127a-1c58-4b0b-981d-d419d65cc87c", "name": "Honey Badger Ad - Lens", "type": "LENS", "status": "ACTIVE"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/caff7533-52e1-4412-9ef2-18232dbcd1ba/ads
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e41982700ff0e64c8b9dcef490001737e616473617069736300016275696c642d66646632303364612d312d3332342d310001012a",
"ads": [
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "1ab494d4-73e8-4986-8517-c2d313e63f6e",
"updated_at": "2020-02-10T17:51:38.097Z",
"created_at": "2020-02-10T17:51:38.097Z",
"name": "Honey Badger Ad - Lens",
"ad_squad_id": "caff7533-52e1-4412-9ef2-18232dbcd1ba",
"creative_id": "0091127a-1c58-4b0b-981d-d419d65cc87c",
"status": "ACTIVE",
"type": "LENS"
}
}
]
}
This creates a new Ad of the type LENS.
HTTP Request
POST https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/ads
Parameters
Parameter | Default | Description |
---|---|---|
ad_squad_id | Ad Squad ID |
Reporting
Lens Metrics
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 |
total_impressions | The total number of impressions (Paid and Earned) | Within 24 hours |
shares | The number of times your Lens ad was shared via Chat or Stories | Real Time |
saves | The number of times your Lens ad was saved to Memories | Real Time |
play_time_millis | The total amount of time in where Snapchatters interacted with your Lens in the camera (milliseconds) | Real Time |
spend | The total spend delivered in microcurrency | Real Time |
uniques | The number of unique paid impressions | Within 24 hours, LIFETIME only |
total_reach | The number of unique Snapchatters who viewed your Lens ad, either by receiving a Paid or Earned Impression. | Within 24 hours, LIFETIME only |
Stats are available at the Ad, Ad Squad and Campaign levels and are supported for all granularities: HOUR, DAY, TOTAL and LIFETIME. For
lenses with attachments you can also request swipes
and attachment specific metrics.
curl "https://adsapi.snapchat.com/v1/adsquads/21136912-6d1a-44ea-a171-8ac29cf4d75d/stats?granularity=LIFETIME&fields=spend,paid_impressions,earned_impressions,shares,saves,play_time_millis,total_impressions,total_reach,uniques"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e448f8200ff0a3c430fd301390001737e616473617069736300016275696c642d63343664356339642d312d3332352d300001011c",
"lifetime_stats": [
{
"sub_request_status": "SUCCESS",
"lifetime_stat": {
"id": "21136912-6d1a-44ea-a171-8ac29cf4d75d",
"type": "AD_SQUAD",
"granularity": "LIFETIME",
"stats": {
"uniques": 298861,
"spend": 7027120158,
"total_reach": 315925,
"total_impressions": 979631,
"earned_impressions": 29190,
"paid_impressions": 950441,
"shares": 7351,
"saves": 1784,
"play_time_millis": 6354875748
},
"start_time": "2016-09-26T08:00:00.000+01:00",
"end_time": "2020-02-12T17:00:00.000Z",
"finalized_data_end_time": "2020-02-12T17:00:00.000Z"
}
}
]
}
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/{adsquad-id}/stats
Parameters
Parameter | Description |
---|---|
adsquad-id | Lens Ad squad ID |