Get Aggregate Report by Ad Account Id
Returns aggregated ad campaign metrics 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"
- entity_typestring
A reporting dimension for entity-level breakdowns. This field is required if continuation_token is not set.
Example value:"AD_SET"
Allowed values:"AD"
,"AD_SET"
,"CAMPAIGN"
- 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"
- report_startstring [date-time]
The report time range start time. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset (YYYY-MM-DDTHH:MM:SSZ) and must be expressed in whole hours (0 minutes and 0 seconds). NOTE: Hours are inclusive, which means that requesting T00:00:00 – T23:00:00, for example, will return data for the full 24 hours (from T23:00:00 through T23:59:59).
Example value:"2021-01-23T00:00:00Z"
- report_endstring [date-time]
The report time range end time. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset (YYYY-MM-DDTHH:MM:SSZ) and must be expressed in whole hours (0 minutes and 0 seconds). NOTE: Hours are inclusive, which means that requesting T00:00:00 – T23:00:00, for example, will return data for the full 24 hours (from T23:00:00 through T23:59:59).
Example value:"2021-01-26T00:00:00Z"
- granularitystring
A reporting granularity for time breakdowns. Supported values are LIFETIME, DAY, HOUR. For DAY and HOUR, each row of the response for a particular entity will contain time series data within the range of report_start and report_end broken down by day or hourly, respectively.
Example value:"DAY"
Default value:"LIFETIME"
Allowed values:"DAY"
,"HOUR"
,"LIFETIME"
Supported content-type(s): - include_parent_entityboolean
If include_parent_entity=true, the report will also include information about the parent in the ad hierarchy for each returned entity. This parameter defaults to false.
Examples:
Aggregate report broken down by AD_SET, including parent CAMPAIGN information ?entity_type=AD_SET&include_parent_entity=true
Aggregate report broken down by AD, including parent AD_SET information ?entity_type=AD&include_parent_entity=true
Restrictions:
- This parameter is not valid for CAMPAIGN entity_type requests as they have no parent entity.
- This parameter is only valid for aggregate requests and not audience insight requests.
- Passing this parameter without an entity_type set is not allowed.
Example value:false
Default value:false
- 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 aggregated ad campaign report broken down by requested entity dimension.
A list of rows of reporting data. If more items exist than are returned, the continuation_token can be used to request the next page. If no more items exist, the continuation_token will be empty.
- continuation_tokenstringExample value:
"AMC-fuxpGRIqFcOUEzDEdWQsM5Iy7mkRThKFo94mEys6RF1lzeKyq1sOlWU4RsdjSsgDWR2D7An1nFgLXNBU9hocKnWQ9jRsps6kCLqKd7Q77zNEhHm_Xlb6J_Fci6kK7tXVM3U6H8OajjcTA18eFcr-kv0etZJZBWlMhtP84xj4WiVDZnPWaMo7AL3jRrHH32grJ3eRA2PAoZmhg80="
- report_startstring [date-time]
Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.
Example value:"2021-01-23T04:56:07Z"
- report_endstring [date-time]
Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.
Example value:"2021-01-26T04:56:07Z"
- granularitystring
Requested granularity. HOUR, DAY, or LIFETIME.
Example value:"HOUR"
Default value:"LIFETIME"
Allowed values:"DAY"
,"HOUR"
,"LIFETIME"
Supported content-type(s): List of aggregate report rows that contain the entity and the time series information associated with the underlying entity.
An item that contains the entity information as well as the aggregated time series information for that entity.
- entity_typestring
Type of the entity requested. This can be CAMPAIGN, AD_SET, or AD.
Example value:"AD_SET"
Allowed values:"AD"
,"AD_SET"
,"CAMPAIGN"
Supported content-type(s): - entity_idstring [uuid]
ID of the entity.
Example value:"7f4c1cc9-9a1d-4b65-b05c-46e5e33b6705"
Supported content-type(s): - entity_namestring
Name of the entity.
Example value:"My Ad Campaign"
- entity_statusstring
Status of the entity.
Example value:"ACTIVE"
Allowed values:"ACTIVE"
,"APPROVED"
,"ARCHIVED"
,"PENDING_APPROVAL"
,"REJECTED"
,"PAUSED"
,"COMPLETED"
,"READY"
,"PENDING"
Supported content-type(s): Information about the parent entity in the ad hierarchy.
- start_timestring [date-time]
Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.
Example value:"2021-01-23T04:56:07Z"
- end_timestring [date-time]
Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.
Example value:"2021-01-26T04:56:07Z"
Array of field names and their values that were requested as a part of the report.
Response sample
{ "continuation_token": "AMC-fuxpGRIqFcOUEzDEdWQsM5Iy7mkRThKFo94mEys6RF1lzeKyq1sOlWU4RsdjSsgDWR2D7An1nFgLXNBU9hocKnWQ9jRsps6kCLqKd7Q77zNEhHm_Xlb6J_Fci6kK7tXVM3U6H8OajjcTA18eFcr-kv0etZJZBWlMhtP84xj4WiVDZnPWaMo7AL3jRrHH32grJ3eRA2PAoZmhg80=", "report_start": "2021-01-23T04:56:07Z", "report_end": "2021-01-26T04:56:07Z", "granularity": "HOUR", "rows": [ { "entity_type": "AD_SET", "entity_id": "7f4c1cc9-9a1d-4b65-b05c-46e5e33b6705", "entity_name": "My Ad Set", "entity_status": "ACTIVE", "time_series": [ { "start_time": "2021-01-23T04:56:07Z", "end_time": "2021-01-26T04:56:07Z", "stats": [ { "field_type": "CLICKS", "field_value": 100 }, { "field_type": "CTR", "field_value": 0.56 } ] } ] } ]}