Skip to content
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            }          ]        }      ]    }  ]}