Metrics

This section covers metrics for Profile Content.

These stats endpoints are also available publicly. Try prefixing them with /public (e.g., /public/v1/public_profiles/{profile_id}/stats) to see publicly available metrics.

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 "AAuthorization: Bearer <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 ]

Profile-level metrics do not update when an underlying asset is deleted. E.g., total SAVED_STORY_VIEWS on the profile will not be reduced if a saved story is deleted.

Retrieving specific Metrics If you would like to retrieve just a few specific metrics, then you can provide the fields parameter with a comma separated list of all metrics that are needed.
E.g.: 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 "AAuthorization: Bearer <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	O	Created timestamp of the story if AssetType is SNAP	Format of UTC like 2021-03-05T02:33:39.240Z
ended_at	O	Ended timestamp of the story if AssetType is SNAP	ended_at should be within 24hr range of PST if created_at is provided

We highly recommend including created_at and ended_at in the request.

To get the created_at and ended_at values, first get the profileʼs stories. In the response, each story has a created_at and ended_at timestamp, which can be used to get the storyʼs stats:

GET https://businessapi.snapchat.com/v1/public_profiles/{profile_id}/stories

{
  "request_id": "0efe011f-4f91-409b-8329-987d29769c40",
  "request_status": "SUCCESS",
  "stories": [
    {
      "sub_request_status": "SUCCESS",
      "story": {
        "id": "1ea5a405-85b7-40f0-bcc5-148a29d142c2",
        "profile_id": "{profile_id}",
        "thumbnail_url": "https://cf-st.sc-cdn.net/d/nOyACxG8CUS7VOKjUqSL1.410.IRZXSOY?uc=12",
        "created_at": "2021-03-05T02:33:39.240Z",
        "type": "PUBLIC_STORY",
        "ended_at": "2021-03-05T12:37:00.210Z"
      }
    },
    …
  ]
}

GET https://businessapi.snapchat.com/v1/public_profiles/{profile_id}/stories/{id}/stats?
    created_at=2021-03-05T02:33:39.240Z&
    ended_at=2021-03-05T12:37:00.210Z

Without created_at and ended_at, the stats request may timeout for popular profiles.

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 "AAuthorization: Bearer <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 spotlight.

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 "AAuthorization: Bearer <ACCESS_TOKEN>"

Response

{
  "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": "…"
  }
}

Snap Stats

This endpoint retrieves all available stats for a Snap by its Snap id. The creator who owns the Snap is resolved from the Snap itself, so you only need the Snap id — you do not need to know the creator's profile id.

Access is granted when any of the following holds for the caller: they own the Snap, they have a sharing policy on the Snap (pass brand_profile_id), or they have an ad partnership with the creator and the creator has enabled insights sharing.

HTTP Request

GET
https://businessapi.snapchat.com/v1/snaps/{id}/stats

The previous path GET /v1/public_profiles/{profile_id}/snaps/{id}/stats still works but is deprecated. Its {profile_id} path segment is overloaded (it could refer to either the creator who owns the Snap or the brand accessing it) and is no longer required, since the creator is resolved from the Snap. Prefer GET /v1/snaps/{id}/stats and, when accessing a Snap shared with your brand, pass the brand_profile_id query parameter. When calling the deprecated path, its {profile_id} is treated as brand_profile_id.

Parameters

Field name	Required	Description	Possible Values
id	R	The Snap id. This is provided in the URL.
brand_profile_id	O	The profile id of the brand requesting access to a Snap that was shared with it via a sharing policy. Only needed for that shared-Snap access path; omit it when accessing a Snap from a creator you have an ad partnership with, as the creator is resolved from the Snap.
assetType	O	Default value is SNAP.	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

profile_id (previously a required path segment) is deprecated in favor of brand_profile_id. It is retained only for backward compatibility with the deprecated path above.

Example

curl "https://businessapi.snapchat.com/v1/snaps/{id}/stats" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Response

{
  "request_id": "4a7f9b8c-1234-5678-abcd-9876543210ef",
  "request_status": "SUCCESS",
  "granularity": "LIFETIME",
  "assets": [
    {
      "sub_request_status": "SUCCESS",
      "asset_type": "SNAP",
      "asset_id": "-Zz9YxRvQwU3aBmTpL2HcYgAAgYWNobmdiZG10AZdaZUW6AZdaZUCoAAAAAA",
      "timeseries": [
        {
          "end_time": "2025-09-19T21:19:51.205Z",
          "fields": [
            {
              "field": {
                "fieldName": "SAVED_STORY_FAVORITES"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "3"
                }
              ]
            },
            {
              "field": {
                "fieldName": "SPOTLIGHT_FAVORITES"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "12"
                }
              ]
            },
            {
              "field": {
                "fieldName": "STORY_FAVORITES"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "95"
                }
              ]
            },
            {
              "field": {
                "fieldName": "VIEWS"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "25841"
                }
              ]
            },
            {
              "field": {
                "fieldName": "UNIQUE_SESSIONS"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "21345"
                }
              ]
            },
            {
              "field": {
                "fieldName": "VIEWERS"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "22901"
                }
              ]
            },
            {
              "field": {
                "fieldName": "REPLIES"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "17"
                }
              ]
            },
            {
              "field": {
                "fieldName": "SCREENSHOTS"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "24"
                }
              ]
            },
            {
              "field": {
                "fieldName": "UNIQUE_SCREENSHOTS"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "19"
                }
              ]
            },
            {
              "field": {
                "fieldName": "SWIPE_UPS"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "980"
                }
              ]
            },
            {
              "field": {
                "fieldName": "SWIPE_DOWNS"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "5102"
                }
              ]
            },
            {
              "field": {
                "fieldName": "INTERACTIONS"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "23547"
                }
              ]
            },
            {
              "field": {
                "fieldName": "AVG_VIEW_TIME_MILLIS"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "3987"
                }
              ]
            },
            {
              "field": {
                "fieldName": "VIEW_TIME_MILLIS"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "78123456"
                }
              ]
            },
            {
              "field": {
                "fieldName": "SHARES"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "5"
                }
              ]
            },
            {
              "field": {
                "fieldName": "TAP_FORWARD"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "15678"
                }
              ]
            },
            {
              "field": {
                "fieldName": "TAP_BACK"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "1350"
                }
              ]
            },
            {
              "field": {
                "fieldName": "LONG_IMPRESSIONS"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "7"
                }
              ]
            },
            {
              "field": {
                "fieldName": "SNAP_PAID_VIEWS"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "35001234"
                }
              ]
            },
            {
              "field": {
                "fieldName": "SNAP_PAID_UNIQUES"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "14509876"
                }
              ]
            },
            {
              "field": {
                "fieldName": "SNAP_COMBINED_VIEWS"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "35027075"
                }
              ]
            },
            {
              "field": {
                "fieldName": "SNAP_COMBINED_UNIQUES"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "14532789"
                }
              ]
            },
            {
              "field": {
                "fieldName": "SAVED_STORY_SNAP_PAID_VIEWS"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "0"
                }
              ]
            },
            {
              "field": {
                "fieldName": "SAVED_STORY_SNAP_PAID_UNIQUES"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "0"
                }
              ]
            },
            {
              "field": {
                "fieldName": "SAVED_STORY_SNAP_COMBINED_VIEWS"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "2"
                }
              ]
            },
            {
              "field": {
                "fieldName": "SAVED_STORY_SNAP_COMBINED_UNIQUES"
              },
              "stats": [
                {
                  "dimensionBreakdown": "DEFAULT",
                  "value": "2"
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "paging": {}
}

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 occurring on 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 favorited
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

Was this page helpful?

Yes

Profile Stats​

Saved Story Stats​

Story Stats​

Spotlight Stats​

Snap Stats​

Core Metrics​

Combined Metrics​

Metrics By Asset Type​

Metrics and Supported Granularities​

Profile Stats

Saved Story Stats

Story Stats

Spotlight Stats

Snap Stats

Core Metrics

Combined Metrics

Metrics By Asset Type

Metrics and Supported Granularities