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: 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.
Allowed values: "AD", "AD_SET", "CAMPAIGN", "AD_ACCOUNT"Example: entity_type=AD_SET
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: fields=IMPRESSIONS&fields=CLICKS&fields=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:

COMPLETION_RATE

COMPLETES

E_CPCL

FIRST_QUARTILES

FREQUENCY

MIDPOINTS

OFF_SPOTIFY_IMPRESSIONS

PAID_LISTENS_FREQUENCY

SKIPS

SPEND

STARTS

THIRD_QUARTILES

UNMUTES
Allowed values: "CLICKS", "COMPLETES", "COMPLETION_RATE", "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", "VIDEO_VIEWS", "VIDEO_EXPANDS", "VIDEO_EXPAND_RATE", "UNMUTES"
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). 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).

When specifying the time range for reports, please adhere to the following guidelines based on the selected granularity.
- LIFETIME: For lifetime reports, the time component will be truncated to zero. For example, 2021-01-23T22:15:15Z -> 2021-01-23T00:00:00Z. The start and end date (if specified) must also be within 90 days of each other.
- DAY: The start and end date must be within 90 days of each other. In addition, UTC midnight timestamps must be used (no hours, minutes, or seconds).
- HOUR: The report range must be within the last 2 weeks.
Example: report_start=2021-01-23T00%3A00%3A00Z
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). 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).

When specifying the time range for reports, please adhere to the following guidelines based on the selected granularity.
- LIFETIME: For lifetime reports, the time component will be truncated to zero. For example, 2021-01-23T22:15:15Z -> 2021-01-23T00:00:00Z. The start and end date (if specified) must also be within 90 days of each other.
- DAY: The start and end date must be within 90 days of each other. In addition, UTC midnight timestamps must be used (no hours, minutes, or seconds).
- HOUR: The report range must be within the last 2 weeks.
Example: report_end=2021-01-26T00%3A00%3A00Z
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.
Default: granularity=LIFETIMEAllowed values: "DAY", "HOUR", "LIFETIME"Supported content-type(s): Example: granularity=DAY
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 AD_ACCOUNT and CAMPAIGN entity_type requests, as they are already considered top-level types.
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.
Default: include_parent_entity=falseExample: include_parent_entity=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.

Aggregate Report:
- A maximum of 50 entities can be requested.
Insight Report:
- Only one ID at a time is currently supported.
Restrictions:
1. This parameter is not valid for AD_ACCOUNT entity_type requests, since the ID is derived from the ad_account_id.
Example: entity_ids=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.

When using a granularity that is not LIFETIME, entity id types must match the type of the entity requested

Restrictions:
1. This parameter is not valid for AD_ACCOUNT entity_type requests, as the ID is derived from ad_account_id and the type is always considered AD_ACCOUNT.
Allowed values: "AD", "AD_SET", "CAMPAIGN", "AD_ACCOUNT"Example: entity_ids_type=AD_SET
entity_status_type
string
The entity type of statuses contained in the statuses field. If statuses is set, this field is required. Furthermore, the only acceptable value for insight reports is AD_SET.

Restrictions:
1. This parameter is not valid for AD_ACCOUNT entity_type requests.
Allowed values: "AD", "AD_SET", "CAMPAIGN", "AD_ACCOUNT"Example: entity_status_type=AD_SET
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.

Restrictions:
1. This parameter is not valid for AD_ACCOUNT entity_type requests.
Example: statuses=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: APPROVED, ARCHIVED, PENDING, PENDING_APPROVAL, PENDING_ADVERTISER_APPROVAL, REJECTED Ad Set: ACTIVE, APPROVED, ARCHIVED, COMPLETED, PENDING_APPROVAL, PENDING_ADVERTISER_APPROVAL, READY, REJECTED Campaign: ACTIVE, ARCHIVED, PAUSED

Note: The PENDING_ADVERTISER_APPROVAL status is only available for managed service campaigns.
Allowed values: "ACTIVE", "APPROVED", "ARCHIVED", "PENDING_APPROVAL", "REJECTED", "PENDING_ADVERTISER_APPROVAL", "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: continuation_token=AMC-fuxpGRIqFcOUEzDEdWQsM5Iy7mkRThKFo94mEys6RF1lzeKyq1sOlWU4RsdjSsgDWR2D7An1nFgLXNBU9hocKnWQ9jRsps6kCLqKd7Q77zNEhHm_Xlb6J_Fci6kK7tXVM3U6H8OajjcTA18eFcr-kv0etZJZBWlMhtP84xj4WiVDZnPWaMo7AL3jRrHH32grJ3eRA2PAoZmhg80%3D
limit
integer
Limit or page size for a given response.
Default: limit=50Range: 1 - 50Example: limit=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: "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: "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: "2021-01-26T04:56:07Z"
granularity
string
Requested granularity. HOUR, DAY, or LIFETIME.
Default: "LIFETIME"Allowed values: "DAY", "HOUR", "LIFETIME"Supported content-type(s): Example: "HOUR"
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.
  Allowed values: "AD", "AD_SET", "CAMPAIGN", "AD_ACCOUNT"Supported content-type(s): Example: "AD_SET"
- entity_id
  string [uuid]
  ID of the entity.
  Supported content-type(s): Example: "7f4c1cc9-9a1d-4b65-b05c-46e5e33b6705"
- entity_name
  string
  Name of the entity.
  Example: "My Ad Campaign"
- entity_status
  string
  Status of the entity.
  Allowed values: "ACTIVE", "APPROVED", "ARCHIVED", "PENDING_APPROVAL", "REJECTED", "PENDING_ADVERTISER_APPROVAL", "PAUSED", "COMPLETED", "READY", "PENDING"Supported content-type(s): Example: "ACTIVE"
- Information about the parent entity in the ad hierarchy.
  id
  string [uuid]
  ID of the parent entity.
  Supported content-type(s): Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
  name
  string
  Name of the parent entity.
  Example: "Parent Entity Name"
  status
  string
  Status of the parent entity.
  Allowed values: "ACTIVE", "APPROVED", "ARCHIVED", "PENDING_APPROVAL", "REJECTED", "PENDING_ADVERTISER_APPROVAL", "PAUSED", "COMPLETED", "READY", "PENDING"Supported content-type(s): Example: "ACTIVE"
- 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: "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: "2021-01-26T04:56:07Z"
- Array of field names and their values that were requested as a part of the report.
  A report field type and its value.
  field_type
  string
  Type of the field that is being requested, i.e., CLICKS, CTR, IMPRESSIONS, etc.
  Allowed values: "CLICKS", "COMPLETES", "COMPLETION_RATE", "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", "VIDEO_VIEWS", "VIDEO_EXPANDS", "VIDEO_EXPAND_RATE", "UNMUTES"Supported content-type(s): Example: "CLICKS"
  field_value
  number
  The value for the specified field. This value can be an integer (CLICKS) or float (CTR).
  Example: 500

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            }          ]        }      ]    }  ]}