Get Insight Report by Ad Account Id
Returns ad campaign metrics broken out by audience (i.e., targeting) insights based on requested fields and dimensions.
Request
- ad_account_idstring [uuid]Required
A unique identifier for an Ad Account.
Example value:"ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- insight_dimensionstring
A reporting dimension for insight breakdowns. This field is required if continuation_token is not set.
Example value:"GENRE"
Allowed values:"AGE"
,"COUNTRY"
,"GENDER"
,"GENRE"
,"PLATFORM"
- fieldsarray of strings
A list of fields requested in the report. This field is required if continuation_token is not set. Refer to the Metrics Glossary for definitions: https://developer.spotify.com/documentation/ads-api/guides#metrics-glossary
Example value:["IMPRESSIONS","CLICKS","SPEND"]
Users can define a set of fields that they would like populated in the report. This enum defines the global list of available fields. However, not all fields are applicable to both report types. This is validated at request time. The following fields are not allowed for insight reports:
- COMPLETES
- E_CPCL
- FIRST_QUARTILES
- FREQUENCY
- MIDPOINTS
- OFF_SPOTIFY_IMPRESSIONS
- PAID_LISTENS_FREQUENCY
- SKIPS
- SPEND
- STARTS
- THIRD_QUARTILES
Allowed values:"CLICKS"
,"COMPLETES"
,"CONVERSION_RATE"
,"CTR"
,"E_CPM"
,"E_CPCL"
,"FIRST_QUARTILES"
,"FREQUENCY"
,"IMPRESSIONS"
,"INTENT_RATE"
,"LISTENERS"
,"MIDPOINTS"
,"NEW_LISTENERS"
,"NEW_LISTENER_CONVERSION_RATE"
,"NEW_LISTENER_STREAMS"
,"OFF_SPOTIFY_IMPRESSIONS"
,"PAID_LISTENS"
,"PAID_LISTENS_FREQUENCY"
,"PAID_LISTENS_REACH"
,"REACH"
,"SKIPS"
,"SPEND"
,"STARTS"
,"STREAMS"
,"STREAMS_PER_NEW_LISTENER"
,"STREAMS_PER_USER"
,"THIRD_QUARTILES"
- entity_idsarray of strings
A list of one or more campaign, ad set, or ad IDs by which to filter reporting. If this field is set, the entity_ids_type field is required. Note: for the insight reports endpoint, only one ID at a time is currently supported.
Example value:["ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"]
- entity_ids_typestring
The entity type of IDs contained in the entity_ids field. If entity_ids is set, this field is required. Furthermore, the only acceptable value for insight reports is AD_SET.
Example value:"AD_SET"
Allowed values:"AD"
,"AD_SET"
,"CAMPAIGN"
- entity_status_typestring
The entity type of statuses contained in the entity_statuses field. If entity_statuses is set, this field is required. Furthermore, the only acceptable value for insight reports is AD_SET.
Example value:"AD_SET"
Allowed values:"AD"
,"AD_SET"
,"CAMPAIGN"
- statusesarray of strings
A list of one or more campaign, ad set, or ad statuses by which to filter reporting. If this field is set, the entity_status_type field is required.
Example value:["ACTIVE"]
Ad, Ad Set, and Campaign statuses that are used in report requests as well as responses. Not every status is valid for each entity type. The valid statuses for each entity are the following: Ad: ACTIVE, APPROVED, ARCHIVED, PENDING, PENDING_APPROVAL, REJECTED Ad Set: ACTIVE, APPROVED, ARCHIVED, COMPLETED, PENDING_APPROVAL, READY, REJECTED Campaign: ACTIVE, ARCHIVED, PAUSED
Allowed values:"ACTIVE"
,"APPROVED"
,"ARCHIVED"
,"PENDING_APPROVAL"
,"REJECTED"
,"PAUSED"
,"COMPLETED"
,"READY"
,"PENDING"
- continuation_tokenstringNullable
A base64 encoded and encrypted string used for paging. If null, no more pages are available.
Example value:"AMC-fuxpGRIqFcOUEzDEdWQsM5Iy7mkRThKFo94mEys6RF1lzeKyq1sOlWU4RsdjSsgDWR2D7An1nFgLXNBU9hocKnWQ9jRsps6kCLqKd7Q77zNEhHm_Xlb6J_Fci6kK7tXVM3U6H8OajjcTA18eFcr-kv0etZJZBWlMhtP84xj4WiVDZnPWaMo7AL3jRrHH32grJ3eRA2PAoZmhg80="
- limitinteger
Limit or page size for a given response.
Example value:50
Default value:50
Range:1
-50
Response
An ad campaign report broken down by requested dimensions.
- continuation_tokenstringExample value:
"AMC-fuxpGRIqFcOUEzDEdWQsM5Iy7mkRThKFo94mEys6RF1lzeKyq1sOlWU4RsdjSsgDWR2D7An1nFgLXNBU9hocKnWQ9jRsps6kCLqKd7Q77zNEhHm_Xlb6J_Fci6kK7tXVM3U6H8OajjcTA18eFcr-kv0etZJZBWlMhtP84xj4WiVDZnPWaMo7AL3jRrHH32grJ3eRA2PAoZmhg80="
- granularitystringExample value:
"LIFETIME"
- entitystring
EntityDimensionType describes the top-level entity in the ad hierarchy that a particular report will be based off of. Both Aggregate and Insight Reports require an EntityDimensionType.
Example value:"AD_SET"
Allowed values:"AD"
,"AD_SET"
,"CAMPAIGN"
- insightstring
InsightDimensionType describes the "second-level" insight that a particular report request is interested in. For example, passing the PLATFORM parameter in a request will generate a LIFETIME report of all requested metrics across IOS, ANDROID, and WEB.
Example value:"PLATFORM"
Allowed values:"AGE"
,"COUNTRY"
,"GENDER"
,"GENRE"
,"PLATFORM"
- namestring
The name associated with the ad set.
Example value:"My First Ad Set"
- idstring [uuid]
ID of the ad set.
Example value:"7f4c1cc9-9a1d-4b65-b05c-46e5e33b6705"
Supported content-type(s): - statusstring
Status of the ad set.
Example value:"ACTIVE"
Allowed values:"ACTIVE"
,"APPROVED"
,"ARCHIVED"
,"PENDING_APPROVAL"
,"REJECTED"
,"PAUSED"
,"COMPLETED"
,"READY"
,"PENDING"
Supported content-type(s): - insight_valuestring
Value of the insight associated with this row. For example, if the requested insight is AGE, then a potential value is "18-25"; alternatively, if COUNTRY was requested, a value could be "US".
Example value:"IOS"
Array of Report Fields that were requested for this particular insight value. Note: the report fields in this array are LIFETIME values.
Response sample
{ "continuation_token": "AMC-fuxpGRIqFcOUEzDEdWQsM5Iy7mkRThKFo94mEys6RF1lzeKyq1sOlWU4RsdjSsgDWR2D7An1nFgLXNBU9hocKnWQ9jRsps6kCLqKd7Q77zNEhHm_Xlb6J_Fci6kK7tXVM3U6H8OajjcTA18eFcr-kv0etZJZBWlMhtP84xj4WiVDZnPWaMo7AL3jRrHH32grJ3eRA2PAoZmhg80=", "granularity": "LIFETIME", "entity": "AD_SET", "insight": "PLATFORM", "rows": [ { "name": "Ad Set One", "id": "7f4c1cc9-9a1d-4b65-b05c-46e5e33b6705", "status": "ACTIVE", "insight_value": "IOS", "stats": [ { "field_type": "CLICKS", "field_value": 100 }, { "field_type": "CTR", "field_value": 0.56 } ] } ]}