Metrics
Metrics for Profile Content
Profile Stats
The profile stats endpoint is a single endpoint to retrieve stats for all assets related to a profile. This includes the Profile, Lenses, Stories and Saved Stories. The API can also retrieve stats for different granularities and supports multiple different breakdowns. This endpoint retrieves all available stats for a profile.
HTTP Request
GET https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/stats
Parameters
Field name | Required | Description | Possible Values | |||
---|---|---|---|---|---|---|
profile_id | R | This is provided in the URL. This is a required field. | ||||
assetType | O | Default value is PROFILE. Providing an asset type other than PROFILE returns stats of all assets of the specified type under the profile. | PROFILE, STORY, SAVED_STORY, LENS, SPOTLIGHT | |||
fields | O | A comma separated list of the fields for which stats are required. If this parameter is not specified in the request then stats of all fields supported by the asset type are provided in the response. Request Validation : If a requested field is not available for the requested asset type, then a validation exception will be thrown. | All possible values can be found in the metrics table below | |||
granularity | O | Granularity of the stats. Default Value is LIFETIME. | DAY, TOTAL, LIFETIME. | |||
startTime | O | Start time of the stats. Required if granularity is not LIFETIME Input format : yyyy-mm-ddT00:00:00 Request Validation : String Should be in UTC yyyy-mm-ddT00:00:00 Start time must be within the past 90 days. end_time - start_time should be greater than 0 | ||||
endTime | O | End time of the stats Required if granularity is not LIFETIME Input format : yyyy-mm-ddT00:00:00 Request Validation : String Should be in UTC yyyy-mm-ddT00:00:00 End time must be within the past 90 days. end_time - start_time should be greater than 0 | ||||
breakdownDimensions | O | A comma separated list of breakdown dimensions Breaks down the stats over the provided dimensions. Request Validation : PRODUCT breakdown is only available when Asset Type is Lens. PLACEMENT breakdown is only available for the SUBSCRIBERS metric field. | AGE, GENDER, COUNTRY, REGION, OS, SUBSCRIPTION, AGE_GENDER,COUNTRY_GENDER, COUNTRY_AGE, COUNTRY_SUBSCRIPTION | |||
limit | O | Number of assets per page. This is useful when asset type is not PROFILE. | 10 - 1000 | |||
cursor | O | This can be provided to fetch the next page of stats. Its value would be the next_page_id received in the previous response. |
HTTP Response
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
request_id | A UUID to identify this request. | |||||
request_status | SUCCESS / PARTIAL | |||||
granularity | The requested level of granularity. | LIFETIME, TOTAL, DAY | ||||
assets | List of all assets Each entry represents stats for an asset | Refer to assets table below | ||||
page | Information about the next page of response. If there is a next page available then this will contain the next_page_id and the next_page_link. |
Assets
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
sub_request_status | SUCCESS / ERROR | |||||
error_message | If there was an error then the error message will be present | |||||
asset_type | The type of the asset for which stats are being provided. | PROFILE, STORY, SAVED_STORY, LENS | ||||
asset_id | Id of the asset | |||||
timeseries | An array of stats. Each entry represents an asset’s Daily, Total or Lifetime stats. If the requested granularity is DAY, then this array can contain more than one entry. | Refer to timeseries table below |
TimeSeries
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
start_time | Start time of metrics time bucket in UTC yyyy-mm-ddThh:mm:ss | |||||
end_time | End time of metrics time bucket in UTC yyyy-mm-ddThh:mm:ss | |||||
fields | Array of all stats fields that were requested. | Refer to fields table below |
Fields
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
field | Contains the field name and the breakdown dimension. | Refer to field table below | ||||
stats | List of stats for this field. If no breakdown was requested then this list will contain only one entry. | Refer to stats table below |
Field
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
field_name | The field’s name | |||||
report_dimension | The requested breakdown dimension. If no breakdown was requested then this field’s value would be DEFAULT. |
Stats
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
dimension_breakdown | A string representing the value of the breakdown. For example if the dimension breakdown for AGE was requested then this string could be “AGE_13_17” or “AGE_35_UP” e.t.c If no dimension breakdown was requested then this field will not be available in the response. | |||||
value | The stats value. | |||||
percentage_value | If dimension breakdown was requested then this value represents the percent of the total field value this breakdown makes. |
Example
curl "https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/stats"
-H "Authorization: <ACCESS_TOKEN>
Response
{
"request_id": "ecfe244d-0b1b-4787-9919-4ee7dd275a0a",
"request_status": "SUCCESS",
"granularity": "DAY",
"assets": [
{
"sub_request_status": "SUCCESS",
"asset_type": "PROFILE",
"asset_id": "6cbe6ba5-9ee8-43f3-9a2d-dbe3e6aa8f21",
"timeseries": [
{
"start_time": "2021-11-10T00:00:00Z",
"end_time": "2021-11-11T00:00:00Z",
"fields": [
{
"field":
{
"field_name": "STORY_VIEWS",
"report_dimension": "AGE"
},
"stats": [
{
"dimension_breakdown": "AGE_UNKNOWN",
"value": "0"
},
{
"dimension_breakdown": "AGE_13_17",
"value": "20"
}, ….]
},
{
"field":
{
"field_name": "VIEWS",
"report_dimension": "AGE"
},
"stats": [….]
}]
},
{
"start_time": "2021-11-11T00:00:00Z",
"end_time": "2021-11-12T00:00:00Z",
"fields": [….]
}, ….]
}],
"paging":
{
"next_page_id": "... ",
"next_page_link": "..."
}
}
API Usage This API can be used to
- Read lifetime stats of a profile : https://businessapi.snapchat.com/v1/public_profiles/{profile_Id}/stats
- Read lifetime stats of all assets of a specific type under a profile by specifying the assetType parameter. For example, if assetType=LENS is specified in the request, then the response contains stats of all the lenses under the profile : https://businessapi.snapchat.com/v1/public_profiles/{profile_Id}/stats?assetType=[ LENS /STORY / SAVED_STORY ]
- Get daily or total stats within a specified start and end date. If granularity=DAY is provided in the request, then the response contains separate stats for each day : https://businessapi.snapchat.com/v1/public_profiles/{profile_Id}/stats?startTime=yyyy-mm-ddT00:00:00Z&endTime=yyyy-mm-ddT00:00:00Z&granularity=[ TOTAL / DAY ]
Retrieving specific Metrics
If you would like to retrive just a few specific metrics, then you can provide the fields parameter with a comma separated list of all metrics that are needed.
Eg: https://businessapi.snapchat.com/v1/public_profiles/{profile_Id}/stats?fields=VIEWS,STORY_VIEWS,LENS_UNIQUES
Please refer to the Metrics section for all the fields, their descriptions and supported asset types for each metric.
Breakdown Dimensions Stats can be broken down into dimensions using the breakdownDimensions parameter. The breakdownDimensions parameter accepts a comma separated list of dimensions. Example : https://businessapi.snapchat.com/v1/public_profiles/{profile_Id}/stats?breakdownDimensions=AGE,AGE_GENDER,COUNTRY
If you want the audience breakdown by country you can provide "breakdown_dimensions=country" in the request. Http Request curl -v https://businessapi.snapchat.com/v1/public_profiles/{profile_id}/stats?fields="STORY_VIEWS&breakdown_dimensions=country
Pagination The API supports paginating over assets, if the assetType parameter is specified in the request, and a limit is also specified, then the response may be split into multiple pages. Each response will contain the next page’s id.
Example: If we have a profile with 4 lenses in it. We can get stats for those lenses in 2 pages by making the following request :
https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/stats?assetType=LENS&limit=2 The response from the above request will contain the stats for the first 2 lenses and a next_page_id (“next_page_id”:“c9dd5567-975a-4e1e-9415-559b821d7ba9”).
The next page of lens stats can be requested by specifying the cursor parameter in the request : https://businessapi.snapchat.com/v1/public_profiles/{profile_Id}/stats?assetType=LENS&limit=2&cursor=c9dd5567-975a-4e1e-9415-559b821d7ba9
Saved Story Stats
This endpoint retrieves all available stats for a saved story.
HTTP Request
GET https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/saved_stories/{id}/stats
Parameters
Field name | Required | Description | Possible Values | |||
---|---|---|---|---|---|---|
profile_id | R | This is provided in the URL. This is a required field. | ||||
id | R | The story id. This is provided in the URL. | ||||
assetType | O | Default value is SAVED_STORY. Providing SNAP as the assetType returns stats of the snaps in the story. | SAVED_STORY, SNAP | |||
fields | O | A comma separated list of the fields for which stats are required. If this parameter is not specified in the request then stats of all fields supported by the asset type are provided in the response. Request Validation : If a requested field is not available for the requested asset type, then a validation exception will be thrown. | All possible values can be found in the metrics section. | |||
granularity | O | Default Value is LIFETIME. Granularity of the stats. | DAY, TOTAL, LIFETIME. | |||
startTime | O | Start time of the stats. Required if granularity is not LIFETIME Input format : yyyy-mm-ddT00:00:00Z Request Validation : String Should be in UTC yyyy-mm-ddT00:00:00Z Start time must be within the past 90 days. end_time - start_time should be greater than 0 | ||||
endTime | O | End time of the stats Required if granularity is not LIFETIME Input format : yyyy-mm-ddT00:00:00Z Request Validation : String Should be in UTC yyyy-mm-ddT00:00:00Z End time must be within the past 90 days. end_time - start_time should be greater than 0 | ||||
breakdownDimensions | O | A comma separated list of breakdown dimensions Breaks down the stats over the provided dimensions. Request Validation : PRODUCT breakdown is only available when Asset Type is Lens. PLACEMENT breakdown is only available for the SUBSCRIBERS metric field. | AGE_GENDER COUNTRY INTEREST_CATEGORY_ID OS PLACEMENT PLATFORM PRODUCT PRODUCT_CATEGORY REGION SDK_VERSION SPONSOR_TYPE | |||
limit | O | Number of assets per page. This is useful when asset type is not PROFILE. | 10 - 1000 | |||
cursor | O | This can be provided to fetch the next page of stats. Its value would be the next_page_id received in the previous response. |
HTTP Response
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
request_id | A UUID to identify this request. | |||||
request_status | SUCCESS / PARTIAL | |||||
granularity | The requested level of granularity. | LIFETIME, TOTAL, DAY | ||||
assets | List of all assets Each entry represents stats for an asset | |||||
error_code | If an error occurs then an error code will be present in this field. | |||||
debug_message | An error message in case an error occurs. | |||||
paging | Information about the next page of response. If there is a next page available then this object will contain the next_page_id and the next_page_link fields. |
Assets
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
sub_request_status | SUCCESS / ERROR | |||||
error_code | If an error occurs then an error code will be present in this field. | |||||
debug_message | If there was an error then the debug message will be present | |||||
asset_type | The type of the asset for which stats are being provided. | SAVED_STORY, SNAP | ||||
asset_id | Id of the asset | |||||
timeseries | An array of stats. Each entry represents an asset’s Daily, Total or Lifetime stats. If the requested granularity is DAY, then this array can contain more than one entry. |
TimeSeries
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
start_time | Start time of metrics time bucket in UTC yyyy-mm-ddThh:mm:ss | |||||
end_time | End time of metrics time bucket in UTC yyyy-mm-ddThh:mm:ss | |||||
fields | Array of all stats fields that were requested. | Refer to fields table below |
Fields
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
field | Contains the field name and the breakdown dimension. | Refer to field table below | ||||
stats | List of stats for this field. If no breakdown was requested then this list will contain only one entry. | Refer to stats table below |
Field
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
field_name | The field’s name | |||||
report_dimension | The requested breakdown dimension. If no breakdown was requested then this field’s value would be DEFAULT. |
Stats
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
dimension_breakdown | A string representing the value of the breakdown. For example if the dimension breakdown for AGE was requested then this string could be “AGE_13_17” or “AGE_35_UP” e.t.c If no dimension breakdown was requested then this field will not be available in the response. | |||||
value | The stats value. | |||||
percentage_value | If dimension breakdown was requested then this value represents the percent of the total field value this breakdown makes. |
Example
curl "https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/saved_stories/{id}/stats"
-H "Authorization: <ACCESS_TOKEN>"
Response
{
"request_id": "ecfe244d-0b1b-4787-9919-4ee7dd275a0a",
"request_status": "SUCCESS",
"granularity": "DAY",
"assets": [
{
"sub_request_status": "SUCCESS",
"asset_type": "SAVED_STORY",
"asset_id": "6cbe6ba5-9ee8-43f3-9a2d-dbe3e6aa8f21",
"timeseries": [
{
"start_time": "2021-11-10T00:00:00Z",
"end_time": "2021-11-11T00:00:00Z",
"fields": [
{
"field":
{
"field_name": "SAVED_STORY_VIEWS",
"report_dimension": "AGE"
},
"stats": [
{
"dimension_breakdown": "AGE_UNKNOWN",
"value": "0"
},
{
"dimension_breakdown": "AGE_13_17",
"value": "20"
}, ….]
},
{
"field":
{
"field_name": "SAVED_STORY_SUBSCRIBES",
"report_dimension": "AGE"
},
"stats": [….]
}]
},
{
"start_time": "2021-11-11T00:00:00Z",
"end_time": "2021-11-12T00:00:00Z",
"fields": [….]
}, ….]
}],
"paging":
{
"next_page_id”: “...”,
“next_page_link”: “...”
}
}
Story Stats
This endpoint retrieves all available stats for a story.
HTTP Request
GET https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/stories/{id}/stats
Parameters
Field name | Required | Description | Possible Values | |||
---|---|---|---|---|---|---|
profile_id | R | This is provided in the URL. This is a required field. | ||||
id | R | The story id. This is provided in the URL. | ||||
assetType | O | Default value is STORY. Providing SNAP as the assetType returns stats of the snaps in the story. | STORY, SNAP | |||
fields | O | A comma separated list of the fields for which stats are required. If this parameter is not specified in the request then stats of all fields supported by the asset type are provided in the response. Request Validation : If a requested field is not available for the requested asset type, then a validation exception will be thrown. | All possible values can be found in the metrics section. | |||
granularity | O | Default Value is LIFETIME. Granularity of the stats. | DAY, TOTAL, LIFETIME. | |||
startTime | O | Start time of the stats. Required if granularity is not LIFETIME Input format : yyyy-mm-ddT00:00:00 Request Validation : String Should be in UTC yyyy-mm-ddT00:00:00 Start time must be within the past 90 days. end_time - start_time should be greater than 0 | ||||
endTime | O | End time of the stats Required if granularity is not LIFETIME Input format : yyyy-mm-ddT00:00:00 Request Validation : String Should be in UTC yyyy-mm-ddT00:00:00 End time must be within the past 90 days. end_time - start_time should be greater than 0 | ||||
breakdownDimensions | O | A comma separated list of breakdown dimensions Breaks down the stats over the provided dimensions. Request Validation : PRODUCT breakdown is only available when Asset Type is Lens. PLACEMENT breakdown is only available for the SUBSCRIBERS metric field. | AGE_GENDER COUNTRY INTEREST_CATEGORY_ID OS PLACEMENT PLATFORM PRODUCT PRODUCT_CATEGORY REGION SDK_VERSION SPONSOR_TYPE | |||
limit | O | Number of assets per page. This is useful when asset type is not PROFILE. | 10 - 1000 | |||
cursor | O | This can be provided to fetch the next page of stats. Its value would be the next_page_id received in the previous response. | ||||
created_at | No | Created timestamp of the story if AssetType is SNAP | Format of UTC like 2021-03-05T02:33:39.240Z | |||
ended_at | No | Ended timestamp of the story if AssetType is SNAP | ended_at should be within 24hr range of PST if created_at is provided |
HTTP Response
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
request_id | A UUID to identify this request. | |||||
request_status | SUCCESS / PARTIAL | |||||
granularity | The requested level of granularity. | LIFETIME, TOTAL, DAY | ||||
assets | List of all assets Each entry represents stats for an asset | |||||
error_code | If an error occurs then an error code will be present in this field. | |||||
debug_message | An error message in case an error occurs. | |||||
paging | Information about the next page of response. If there is a next page available then this object will contain the next_page_id and the next_page_link fields. |
Assets
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
sub_request_status | SUCCESS / ERROR | |||||
error_code | If an error occurs then an error code will be present in this field. | |||||
debug_message | If there was an error then the debug message will be present | |||||
asset_type | The type of the asset for which stats are being provided. | SAVED_STORY, SNAP | ||||
asset_id | Id of the asset | |||||
timeseries | An array of stats. Each entry represents an asset’s Daily, Total or Lifetime stats. If the requested granularity is DAY, then this array can contain more than one entry. |
TimeSeries
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
start_time | Start time of metrics time bucket in UTC yyyy-mm-ddThh:mm:ss | |||||
end_time | End time of metrics time bucket in UTC yyyy-mm-ddThh:mm:ss | |||||
fields | Array of all stats fields that were requested. | Refer to fields table below |
Fields
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
field | Contains the field name and the breakdown dimension. | Refer to field table below | ||||
stats | List of stats for this field. If no breakdown was requested then this list will contain only one entry. | Refer to stats table below |
Field
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
field_name | The field’s name | |||||
report_dimension | The requested breakdown dimension. If no breakdown was requested then this field’s value would be DEFAULT. |
Stats
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
dimension_breakdown | A string representing the value of the breakdown. For example if the dimension breakdown for AGE was requested then this string could be “AGE_13_17” or “AGE_35_UP” e.t.c If no dimension breakdown was requested then this field will not be available in the response. | |||||
value | The stats value. | |||||
percentage_value | If dimension breakdown was requested then this value represents the percent of the total field value this breakdown makes. |
Example
curl "https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/stories/{id}/stats"
-H "Authorization: <ACCESS_TOKEN>"
Response
{
"request_id": "ecfe244d-0b1b-4787-9919-4ee7dd275a0a",
"request_status": "SUCCESS",
"granularity": "DAY",
"assets": [
{
"sub_request_status": "SUCCESS",
"asset_type": "STORY",
"asset_id": "6cbe6ba5-9ee8-43f3-9a2d-dbe3e6aa8f21",
"timeseries": [
{
"start_time": "2021-11-10T00:00:00Z",
"end_time": "2021-11-11T00:00:00Z",
"fields": [
{
"field": {
"field_name": "STORY_VIEWS",
"report_dimension": "AGE"
},
"stats": [
{
"dimension_breakdown": "AGE_UNKNOWN",
"value": "0"
},
{
"dimension_breakdown": "AGE_13_17",
"value": "20"
},
….
]
},
{
"field": {
"field_name": "STORY_SUBSCRIBES",
"report_dimension": "AGE"
},
"stats": [
….
]
}
]
},
{
"start_time": "2021-11-11T00:00:00Z",
"end_time": "2021-11-12T00:00:00Z",
"fields": [
….
]
},
….
]
}
],
"paging": {
“next_page_id” : “...”,
“next_page_link” : “...”,
}
}
Spotlight Stats
This endpoint retrieves all available stats for a profile.
HTTP Request
GET https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/spotlights/{id}/stats
Parameters
Field name | Required | Description | Possible Values | |||
---|---|---|---|---|---|---|
profile_id | R | This is provided in the URL. This is a required field. | ||||
id | R | The spotlight id. This is provided in the URL. | ||||
assetType | O | Default value is SPOTLIGHT. | SPOTLIGHT | |||
fields | O | A comma separated list of the fields for which stats are required. If this parameter is not specified in the request then stats of all fields supported by the asset type are provided in the response. Request Validation : If a requested field is not available for the requested asset type, then a validation exception will be thrown. | All possible values can be found in the metrics section. | |||
granularity | O | Default Value is LIFETIME. Granularity of the stats. | DAY, TOTAL, LIFETIME. | |||
startTime | O | Start time of the stats. Required if granularity is not LIFETIME Input format : yyyy-mm-ddT00:00:00 Request Validation : String Should be in UTC yyyy-mm-ddT00:00:00 Start time must be within the past 90 days. end_time - start_time should be greater than 0 | ||||
endTime | O | End time of the stats Required if granularity is not LIFETIME Input format : yyyy-mm-ddT00:00:00 Request Validation : String Should be in UTC yyyy-mm-ddT00:00:00 End time must be within the past 90 days. end_time - start_time should be greater than 0 | ||||
breakdownDimensions | O | A comma separated list of breakdown dimensions Breaks down the stats over the provided dimensions. Request Validation : PRODUCT breakdown is only available when Asset Type is Lens. PLACEMENT breakdown is only available for the SUBSCRIBERS metric field. | AGE_GENDER COUNTRY INTEREST_CATEGORY_ID OS PLACEMENT PLATFORM PRODUCT PRODUCT_CATEGORY REGION SDK_VERSION SPONSOR_TYPE | |||
limit | O | Number of assets per page. This is useful when asset type is not PROFILE. | 10 - 1000 | |||
cursor | O | This can be provided to fetch the next page of stats. Its value would be the next_page_id received in the previous response. |
HTTP Response
Name | Description | Possible Values | ||||
request_id | A UUID to identify this request. | |||||
request_status | SUCCESS / PARTIAL | |||||
granularity | The requested level of granularity. | LIFETIME, TOTAL, DAY | ||||
assets | List of all assets Each entry represents stats for an asset | |||||
error_code | If an error occurs then an error code will be present in this field. | |||||
debug_message | An error message in case an error occurs. | |||||
paging | Information about the next page of response. If there is a next page available then this object will contain the next_page_id and the next_page_link fields. |
Assets
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
sub_request_status | SUCCESS / ERROR | |||||
error_code | If an error occurs then an error code will be present in this field. | |||||
debug_message | If there was an error then the debug message will be present | |||||
asset_type | The type of the asset for which stats are being provided. | SPOTLIGHT | ||||
asset_id | Id of the asset | |||||
timeseries | An array of stats. Each entry represents an asset’s Daily, Total or Lifetime stats. If the requested granularity is DAY, then this array can contain more than one entry. |
TimeSeries
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
start_time | Start time of metrics time bucket in UTC yyyy-mm-ddThh:mm:ss | |||||
end_time | End time of metrics time bucket in UTC yyyy-mm-ddThh:mm:ss | |||||
fields | Array of all stats fields that were requested. | Refer to fields table below |
Fields
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
field | Contains the field name and the breakdown dimension. | Refer to field table below | ||||
stats | List of stats for this field. If no breakdown was requested then this list will contain only one entry. | Refer to stats table below |
Field
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
field_name | The field’s name | |||||
report_dimension | The requested breakdown dimension. If no breakdown was requested then this field’s value would be DEFAULT. |
Stats
Name | Description | Possible Values | ||||
---|---|---|---|---|---|---|
dimension_breakdown | A string representing the value of the breakdown. For example if the dimension breakdown for AGE was requested then this string could be “AGE_13_17” or “AGE_35_UP” e.t.c If no dimension breakdown was requested then this field will not be available in the response. | |||||
value | The stats value. | |||||
percentage_value | If dimension breakdown was requested then this value represents the percent of the total field value this breakdown makes. |
Example
curl "https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/spotlights/{id}/stats"
-H "Authorization: <ACCESS_TOKEN>”
Response
The above command returns JSON structured like this:
{
"request_id": "ecfe244d-0b1b-4787-9919-4ee7dd275a0a",
"request_status": "SUCCESS",
"granularity": "DAY",
"assets": [
{
"sub_request_status": "SUCCESS",
"asset_type": "SPOTLIGHT",
"asset_id": "W7_EDlXWTBiXAEEniNoMPwAAYcGV3eGF4aXVnAX5Pn720AX5Pn7ufAAAAAA",
"timeseries": [
{
"start_time": "2021-11-10T00:00:00Z",
"end_time": "2021-11-11T00:00:00Z",
"fields": [
{
"field":
{
"field_name": "SPOTLIGHT_VIEWS",
"report_dimension": "AGE"
},
"stats": [
{
"dimension_breakdown": "AGE_UNKNOWN",
"value": "0"
},
{
"dimension_breakdown": "AGE_13_17",
"value": "20"
}, ….]
},
{
"field":
{
"field_name": "SPOTLIGHT_SUBSCRIBES",
"report_dimension": "AGE"
},
"stats": [….]
}]
},
{
"start_time": "2021-11-11T00:00:00Z",
"end_time": "2021-11-12T00:00:00Z",
"fields": [….]
}, ….]
}],
"paging":
{“
next_page_id”: “...”,
“next_page_link”: “...”,
}
}
Core Metrics
Field Name | Is Public | Field Description | ||
---|---|---|---|---|
METRIC_FIELD_UNSET | Placeholder if the field is not set. | |||
VIEWS | Number of times an asset has been viewed | |||
STORY_FAVORITES | Number of times an asset has been liked | |||
STORY_VIEWS | Views for Story container | |||
STORY_UNIQUES | Unique users who have viewed a story / snap within a story | |||
STORY_VIEW_TIME_MILLIS | Milliseconds a story & snap in story asset has been viewed | |||
STORY_AVG_VIEW_TIME_MILLIS | calculated field: STORY_VIEW_TIME_MILLIS / STORY_UNIQUES | |||
STORY_SUBSCRIBES | Number of subscribe events occurringon story asset | |||
SAVED_STORY_FAVORITES | Number of times an asset has been liked | |||
SAVED_STORY_VIEWS | Views for Saved Stories | |||
SAVED_STORY_UNIQUES | Unique users who have viewed a saved story / snap within a saved story | |||
SAVED_STORY_VIEW_TIME_MILLIS | milliseconds a saved story has been viewed | |||
SAVED_STORY_SUBSCRIBES | Number of subscribe events occurring on a saved story | |||
SAVED_STORY_AVG_VIEW_TIME_MILLIS | calculated field : SAVED_STORY_VIEW_TIME_MILLIS/SAVED_STORY_VIEWS | |||
SPOTLIGHT_AVG_VIEW_TIME_MILLIS | calculated field : SPOTLIGHT_VIEW_TIME_MILLIS/SPOTLIGHT_VIEWS | |||
SPOTLIGHT_VIEWS | Y | Views for Spotlight container | ||
SPOTLIGHT_UNIQUES | Unique users who have viewed a spotlight asset | |||
SPOTLIGHT_VIEW_TIME_MILLIS | Milliseconds a spotlight asset has been viewed | |||
SPOTLIGHT_SUBSCRIBES | Number of subscribe events occurring on spotlight asset | |||
LENS_VIEWS | Views for lens | |||
LENS_UNIQUES | Unique users who have viewed a lens asset | |||
LENS_VIEW_TIME_MILLIS | milliseconds a lens asset has been viewed | |||
LENS_SUBSCRIBES | Number of subscribe events occurring on lens asset | |||
LENS_AVG_VIEW_TIME_MILLIS | calculated field: LENS_VIEW_TIME_MILLIS / LENS_VIEWS | |||
UNIQUE_SESSIONS | Number of unique sessions an asset has been engaged in | |||
VIEWERS | Number of unique users who have viewed an asset | |||
REPLIES | Number of replies to a snap or story | |||
SCREENSHOTS | Number of screenshots of a snap | |||
UNIQUE_SCREENSHOTS | Number of users who have taken a screenshot of a snap | |||
SWIPE_UPS | Number of swipe ups on an asset | |||
SWIPE_DOWNS | Number of swipe downs on an asset | |||
INTERACTIONS | Number of times a user interacted with an asset. These include: tap forwards/backwards, swipe-away | |||
AVG_VIEW_TIME_MILLIS | **calculated fields, not aggregation VIEW_TIME_MILLIS/VIEWS | |||
VIEW_TIME_MILLIS | milliseconds an asset has been viewed | |||
SHARES | Number of times an asset has been shared | |||
LENS_PLAYS | number of plays on a lens | |||
PLAY_TIME_MILLIS | lens play time, only available for lens | |||
SUBSCRIBES | Number of subscribe events | |||
UNSUBSCRIBES | Number of unsubscribe events | |||
FAVORITES | Number of times an asset has been favorited | |||
SUBSCRIBERS_GAINED | Incremental subscribers gained - only available at TOTAL & DAILY granularity- PLACEMENT LEVEL ONLY INSIGHTS ONLY AVAILABLE AT PROFILE/USER ENTITY | |||
SUBSCRIBERS | Y | Unique subscribers ONLY AVAILABLE AT PROFILE/USER ENTITY | ||
SCANS | A Lens’s total scans by scanning its Snapcode, opening the Lens from Snapcode Scan History, or opening the Lens by tapping on its Lens link on their mobile device. | |||
SOCIAL_UNLOCKS | Number of Unlocks from social context card | |||
LENS_DAU_OVER_WAU | t[0, 1)/t[-7,0) (these are date ranges for lens uniques) | |||
LENS_DAU_OVER_MAU | t[0, 1)/t[-28,0) (these are date ranges for lens uniques) | |||
TAP_FORWARD | Number of times a user taps forward on an asset | |||
TAP_BACK | Number of times a user taps backward on an asset | |||
LONG_IMPRESSIONS | The total number of times a tile was viewed at least 1.2 seconds and viewed at least 25% of the tile on Snapchat within selected time range. | |||
PRODUCT_PLAYS | Number of times a user has played with a lens for a specific product variant | |||
PRODUCT_SWIPES | Number of times a user has swiped/click on a lens for a specific product variant | |||
PRODUCT_SHARES | Number of times a user has shared a lens for a specific product variant | |||
PRODUCT_PLAY_TIME_MILLIS | Milliseconds a lens asset has been viewed | |||
PRODUCT_AVG_PLAY_TIME_MILLIS | calculated fields: PRODUCT_PLAYTIME_MILLIS/PRODUCT_PLAYS | |||
CAMERA_PLAY_TIME_MILLIS | The total amount of time a Lens is used by Snap Camera users | |||
LENS_SHARES | Number of times a lens has been shared | |||
COMPLETES | Number of times an asset is finished (story complete, stories & saved stories) | |||
LENS_SUBSCRIBERS_GAINED | Incremental lens subscribers gained - only available at TOTAL & DAILY granularity- PLACEMENT LEVEL ONLY INSIGHTS ONLY AVAILABLE AT PROFILE/USER ENTITY | |||
LENS_SUBSCRIBERS | Unique lens subscribers ONLY AVAILABLE AT PROFILE/USER ENTITY | |||
STORY_SUBSCRIBERS_GAINED | Incremental story subscribers gained - only available at TOTAL & DAILY granularity- PLACEMENT LEVEL ONLY INSIGHTS ONLY AVAILABLE AT PROFILE/USER ENTITY | |||
STORY_SUBSCRIBERS | Unique story subscribers ONLY AVAILABLE AT PROFILE/USER ENTITY | |||
PROFILE_VIEWS | Number of views for a Profile | |||
SPOTLIGHT_SCREENSHOTS | Number of screenshots of a snap in spotlight | |||
SPOTLIGHT_FAVORITES | Number of times a spotlight has been liked | |||
SPOTLIGHT_SHARES | Y | Number of times a spotlight has been shared | ||
SPOTLIGHT_SUBSCRIBERS_GAINED | Incremental spotlight subscribers gained - only available at TOTAL & DAILY granularity - PLACEMENT LEVEL ONLY INSIGHTS |
Combined Metrics
Metric Name | Description |
---|---|
ADS_SUBSCRIBES | Number of subscribe events resulting from SnapPromote Ads |
PROFILE_PAID_VIEWS | Number of clicks to a profile on ads |
SNAP_PAID_VIEWS | The sum of paid impression for ads promoting the snaps within the Public Story |
SNAP_PAID_UNIQUES | The sum of paid uniques for ads promoting the snaps within the Public Story |
SNAP_COMBINED_VIEWS | The combined value of SNAP_PAID_VIEWS and SNAP_VIEWS |
SNAP_COMBINED_UNIQUES | The combined value of SNAP_PAID_UNIQUES + STORY_UNIQUES |
SPOTLIGHT_PAID_VIEWS | The sum of paid impression for ads promoting the snaps within the Spotlight |
SPOTLIGHT_PAID_UNIQUES | The sum of paid uniques for ads promoting the snaps within the Spotlight |
SPOTLIGHT_COMBINED_VIEWS | The combined value of SPOTLIGHT_PAID_VIEWS and SPOTLIGHT_VIEWS |
SPOTLIGHT_COMBINED_UNIQUES | The combined value of SPOTLIGHT_PAID_UNIQUES and SPOTLIGHT_UNIQUES |
SAVED_STORY_SNAP_PAID_VIEWS | The sum of paid impression for ads promoting the snaps within the Saved Story |
SAVED_STORY_SNAP_PAID_UNIQUES | The sum of paid uniques for ads promoting the snaps within the Saved Story |
SAVED_STORY_SNAP_COMBINED_VIEWS | The combined value of SAVED_STORY_SNAP_PAID_VIEWS and SAVED_STORY_SNAP_VIEWS |
SAVED_STORY_SNAP_COMBINED_UNIQUES | The combined value of SAVED_STORY_SNAP_PAID_UNIQUES and SAVED_STORY_UNIQUES |
Metrics By Asset Type
Field Name | PROFILE | STORY | SAVED_STORY | SNAP | LENS | SPOTLIGHT |
---|---|---|---|---|---|---|
ADS_SUBSCRIBES | x | |||||
PROFILE_PAID_VIEWS | x | |||||
VIEWS | x | X | X | X | X | X |
STORY_FAVORITES | x | X | ||||
STORY_VIEWS | x | X | ||||
STORY_UNIQUES | x | X | ||||
STORY_VIEW_TIME_MILLIS | x | X | ||||
STORY_AVG_VIEW_TIME_MILLIS | x | X | ||||
STORY_SUBSCRIBES | x | X | ||||
SNAP_PAID_VIEWS | x | X | X | |||
SNAP_PAID_UNIQUES | x | X | X | |||
SNAP_COMBINED_VIEWS | x | X | X | |||
SNAP_COMBINED_UNIQUES | x | X | X | |||
SAVED_STORY_FAVORITES | x | X | ||||
SAVED_STORY_VIEWS | x | X | ||||
SAVED_STORY_UNIQUES | x | X | ||||
SAVED_STORY_VIEW_TIME_MILLIS | x | X | ||||
SAVED_STORY_SUBSCRIBES | x | X | ||||
SAVED_STORY_AVG_VIEW_TIME_MILLIS | x | X | ||||
SAVED_STORY_SNAP_PAID_VIEWS | x | X | ||||
SAVED_STORY_SNAP_PAID_UNIQUES | x | X | ||||
SAVED_STORY_SNAP_COMBINED_VIEWS | x | X | ||||
SAVED_STORY_SNAP_COMBINED_UNIQUES | x | X | ||||
SPOTLIGHT_AVG_VIEW_TIME_MILLIS | x | X | ||||
SPOTLIGHT_VIEWS | x | X | ||||
SPOTLIGHT_UNIQUES | x | X | ||||
SPOTLIGHT_VIEW_TIME_MILLIS | x | X | ||||
SPOTLIGHT_SUBSCRIBES | x | X | ||||
SPOTLIGHT_PAID_VIEWS | x | X | ||||
SPOTLIGHT_PAID_UNIQUES | x | X | ||||
SPOTLIGHT_COMBINED_VIEWS | x | X | ||||
SPOTLIGHT_COMBINED_UNIQUES | x | X | ||||
LENS_VIEWS | x | X | ||||
LENS_UNIQUES | x | X | ||||
LENS_VIEW_TIME_MILLIS | x | X | ||||
LENS_SUBSCRIBES | x | X | ||||
LENS_AVG_VIEW_TIME_MILLIS | x | X | ||||
UNIQUE_SESSIONS | X | X | X | X | X | X |
VIEWERS | X | X | X | X | X | X |
REPLIES | X | X | X | X | ||
SCREENSHOTS | X | X | ||||
UNIQUE_SCREENSHOTS | X | X | ||||
SWIPE_UPS | X | X | X | X | X | X |
SWIPE_DOWNS | X | X | X | X | X | X |
INTERACTIONS | X | X | X | X | X | X |
AVG_VIEW_TIME_MILLIS | X | X | X | X | X | X |
VIEW_TIME_MILLIS | X | X | X | X | X | X |
SHARES | X | X | X | X | X | X |
LENS_PLAYS | X | X | ||||
PLAY_TIME_MILLIS | X | X | ||||
SUBSCRIBES | X | |||||
UNSUBSCRIBES | X | |||||
FAVORITES | X | X | X | X | ||
SUBSCRIBERS_GAINED | X | |||||
SUBSCRIBERS | X | |||||
SCANS | X | X | ||||
SOCIAL_UNLOCKS | X | X | ||||
LENS_DAU_OVER_WAU | X | X | ||||
LENS_DAU_OVER_MAU | X | X | ||||
TAP_FORWARD | X | |||||
TAP_BACK | X | |||||
LONG_IMPRESSIONS | X | |||||
PRODUCT_PLAYS | X | |||||
PRODUCT_SWIPES | X | |||||
PRODUCT_SHARES | X | |||||
PRODUCT_PLAY_TIME_MILLIS | X | |||||
PRODUCT_AVG_PLAY_TIME_MILLIS | X | |||||
CAMERA_PLAY_TIME_MILLIS | X | |||||
LENS_SHARES | X | |||||
COMPLETES | X | X | ||||
LENS_SUBSCRIBERS_GAINED | X | |||||
LENS_SUBSCRIBERS | X | |||||
STORY_SUBSCRIBERS_GAINED | X | |||||
STORY_SUBSCRIBERS | X | |||||
PROFILE_VIEWS | X | |||||
SPOTLIGHT_SCREENSHOTS | X | X | ||||
SPOTLIGHT_FAVORITES | X | X | ||||
SPOTLIGHT_SHARES | X | X | ||||
SPOTLIGHT_SUBSCRIBERS_GAINED | X | X |
Metrics and Supported Granularities
The following table lists any metric not supported with a particular granularity.
Granularity | Unsupported Metrics | |||||
---|---|---|---|---|---|---|
DAY | ||||||
TOTAL | LENS_DAU_OVER_WAU, LENS_DAU_OVER_MAU | |||||
LIFETIME | SUBSCRIBERS_GAINED, STORY_SUBSCRIBERS_GAINED, LENS_SUBSCRIBERS_GAINED, SPOTLIGHT_SUBSCRIBERS_GAINED, LENS_DAU_OVER_WAU, LENS_DAU_OVER_MAU |