Ads API •References / reports / Get Insight Report by Ad Account ID

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: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a
insight_dimensionstring
A reporting dimension for insight breakdowns. This field is required if continuation_token is not set.
Allowed values: "ACT_AND_SET", "AGE", "AUDIENCE", "COUNTRY", "FORMAT", "GENDER", "GENRE", "INTERESTS", "PLATFORM", "TONE"Example: insight_dimension=GENRE
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: fields=IMPRESSIONS&fields=STREAMED_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:

E_CPCL

FREQUENCY

OFF_SPOTIFY_IMPRESSIONS

PAID_LISTENS_FREQUENCY

SKIPS

SPEND

STARTS

UNMUTES
Allowed values: "CLICKS", "COMPLETES", "COMPLETION_RATE", "CONVERSION_RATE", "CTR", "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", "PAGE_VIEWS", "LEADS", "ADD_TO_CART", "PURCHASES", "REVENUE", "AVERAGE_ORDER_VALUE", "RETURN_ON_AD_SPEND", "CUSTOMER_ACQUISITION_COST", "COST_PER_LEAD", "START_CHECKOUT", "PRODUCTS", "SIGN_UPS", "CUSTOM_EVENT_1", "CUSTOM_EVENT_2", "CUSTOM_EVENT_3", "CUSTOM_EVENT_4", "CUSTOM_EVENT_5", "STREAMED_IMPRESSIONS"
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.

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=9a7b6c5d-4e3f-4b21-8c99-bf1c2a3d4e5f
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.

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_typestring
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
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.

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"

Response

An ad campaign report broken down by requested dimensions.

granularitystring
Example: "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.
Allowed values: "AD", "AD_SET", "CAMPAIGN", "AD_ACCOUNT"Example: "AD_SET"
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.
Allowed values: "ACT_AND_SET", "AGE", "AUDIENCE", "COUNTRY", "FORMAT", "GENDER", "GENRE", "INTERESTS", "PLATFORM", "TONE"Example: "PLATFORM"
- namestring
  The name associated with the ad set.
  Example: "My First Ad Set"
- idstring [uuid]
  ID of the ad set.
  Supported content-type(s): Example: "7f4c1cc9-9a1d-4b65-b05c-46e5e33b6705"
- statusstring
  Status of the ad set.
  Allowed values: "ACTIVE", "APPROVED", "ARCHIVED", "PENDING_APPROVAL", "REJECTED", "PENDING_ADVERTISER_APPROVAL", "PAUSED", "COMPLETED", "READY", "PENDING"Supported content-type(s): Example: "ACTIVE"
- 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: "IOS"
- Array of Report Fields that were requested for this particular insight value. Note: the report fields in this array are LIFETIME values.
  A report field type and its value.
  field_typestring
  Type of the field that is being requested, i.e., CLICKS, CTR, IMPRESSIONS, etc.
  Allowed values: "CLICKS", "COMPLETES", "COMPLETION_RATE", "CONVERSION_RATE", "CTR", "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", "PAGE_VIEWS", "LEADS", "ADD_TO_CART", "PURCHASES", "REVENUE", "AVERAGE_ORDER_VALUE", "RETURN_ON_AD_SPEND", "CUSTOMER_ACQUISITION_COST", "COST_PER_LEAD", "START_CHECKOUT", "PRODUCTS", "SIGN_UPS", "CUSTOM_EVENT_1", "CUSTOM_EVENT_2", "CUSTOM_EVENT_3", "CUSTOM_EVENT_4", "CUSTOM_EVENT_5", "STREAMED_IMPRESSIONS"Supported content-type(s): Example: "CLICKS"
  field_valuenumber
  The value for the specified field. This value can be an integer (CLICKS) or float (CTR). To protect user privacy, we present conversion counts as -5 whenever the actual number of conversions is less than 5 and greater than 0.
  Example: 500

Response sample

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