Ads API •References / reports / Get Aggregated Totals by Ad Account ID

Get Aggregated Totals by Ad Account ID

Returns deduplicated metrics aggregated across a set of campaigns, ad sets, or ads. Reach and frequency are deduplicated across all specified entities.

Request

ad_account_idstring [uuid]
Required
A unique identifier for an Ad Account.
Example: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a
entity_typestring
Required
The entity level to aggregate across. Supported values are CAMPAIGN, AD_SET, and AD. AD_ACCOUNT is not supported; use the getAggregateReport endpoint for account-level totals.
Allowed values: "AD", "AD_SET", "CAMPAIGN", "AD_ACCOUNT"Example: entity_type=AD_SET
entity_idsarray of strings
Required
Entity IDs to aggregate across. Maximum 50 per request.
Array length between 1 and 50Example: entity_ids=9a7b6c5d-4e3f-4b21-8c99-bf1c2a3d4e5f
granularitystring
Required
Time breakdown granularity. Supported values are LIFETIME and DAY. HOUR is not supported for aggregated totals. report_start and report_end are required when granularity is DAY, and optional when granularity is LIFETIME. When provided on LIFETIME, the returned row reflects the deduplicated total over that date range (max 90 days). When omitted on LIFETIME, the row reflects the full lifetime of the specified entities.
Default: granularity=LIFETIMEAllowed values: "DAY", "HOUR", "LIFETIME"Example: granularity=DAY
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). 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=2025-08-01T00%3A00%3A00Z
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). 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).
- LIFETIME and DAY: The end date will be inclusive, meaning that the data for the entire day of the specified end date will be included in the report. For example, if the end date is 2021-01-23T00:00:00Z, the report will include the data for the entire day of 2021-01-23 (UTC).
- HOUR: The report range must be within the last 2 weeks.
Example: report_end=2025-08-02T00%3A00%3A00Z
fieldsarray of strings
Required
Metrics to include in the response. Currently supported values: IMPRESSIONS, CLICKS, CTR, REACH, FREQUENCY. Refer to the Metrics Glossary for definitions: https://developer.spotify.com/documentation/ads-api/guides#metrics-glossary
Array minimum length: 1Example: fields=IMPRESSIONS&fields=CLICKS&fields=REACH&fields=FREQUENCY&fields=CTR
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"

Response

Aggregated totals for the specified entities and time range.

Aggregated totals collapsed across all specified entities. Note: per-day reach values will not sum to LIFETIME reach because reach is deduplicated within each day but not across days.

granularitystring
Required
TimeDimensionType describes the granularity of the data reported. For example, if DAY is selected, a report will be generated that contains daily aggregated metrics between report_start and report_end dates that are provided in the request. Please note that report_start and report_end dates are not permitted when requesting LIFETIME granularity.
Default: "LIFETIME"Allowed values: "DAY", "HOUR", "LIFETIME"Supported content-type(s): Example: "DAY"
Required
One row for LIFETIME granularity. One row per day for DAY granularity, sorted ascending.
A single row of aggregated totals collapsed across all specified entities. For LIFETIME: one row. For DAY: one row per day.
- start_timestring [date-time]
  Nullable
  Start of the time period. Present for DAY granularity only.
  Example: "2025-08-01T00:00:00Z"
- end_timestring [date-time]
  Nullable
  End of the time period. Present for DAY granularity only.
  Example: "2025-08-02T00:00:00Z"
- Required
  Requested metrics aggregated across all entities for this time period.
  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": "DAY",  "rows": [    {      "start_time": "2025-08-01T00:00:00Z",      "end_time": "2025-08-02T00:00:00Z",      "stats": [        {          "field_type": "CLICKS",          "field_value": 500        }      ]    }  ]}