Ads API •References / reports / Get Aggregate Report by Ad Account Id

Get Aggregate Report by Ad Account Id

Returns aggregated ad campaign metrics based on requested fields and dimensions.

Request

ad_account_id
string [uuid]
Required
A unique identifier for an Ad Account.
Example value: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
entity_type
string
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"
fields
array 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_start
string [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_end
string [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"
granularity
string
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_entity
boolean
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:
1. This parameter is not valid for CAMPAIGN entity_type requests as they have no parent entity.
2. This parameter is only valid for aggregate requests and not audience insight requests.
3. Passing this parameter without an entity_type set is not allowed.
Example value: falseDefault value: false
entity_ids
array 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_type
string
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_type
string
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"
statuses
array 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_token
string
Nullable
A base64 encoded and encrypted string used for paging. If null, no more pages are available.
Example value: "AMC-fuxpGRIqFcOUEzDEdWQsM5Iy7mkRThKFo94mEys6RF1lzeKyq1sOlWU4RsdjSsgDWR2D7An1nFgLXNBU9hocKnWQ9jRsps6kCLqKd7Q77zNEhHm_Xlb6J_Fci6kK7tXVM3U6H8OajjcTA18eFcr-kv0etZJZBWlMhtP84xj4WiVDZnPWaMo7AL3jRrHH32grJ3eRA2PAoZmhg80="
limit
integer
Limit or page size for a given response.
Example value: 50Default value: 50Range: 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_token
string
Example value: "AMC-fuxpGRIqFcOUEzDEdWQsM5Iy7mkRThKFo94mEys6RF1lzeKyq1sOlWU4RsdjSsgDWR2D7An1nFgLXNBU9hocKnWQ9jRsps6kCLqKd7Q77zNEhHm_Xlb6J_Fci6kK7tXVM3U6H8OajjcTA18eFcr-kv0etZJZBWlMhtP84xj4WiVDZnPWaMo7AL3jRrHH32grJ3eRA2PAoZmhg80="
report_start
string [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_end
string [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"
granularity
string
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_type
  string
  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_id
  string [uuid]
  ID of the entity.
  Example value: "7f4c1cc9-9a1d-4b65-b05c-46e5e33b6705"Supported content-type(s):
- entity_name
  string
  Name of the entity.
  Example value: "My Ad Campaign"
- entity_status
  string
  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_time
  string [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_time
  string [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            }          ]        }      ]    }  ]}