Get ad account insights
get_account_insightsRead-only
Retrieve aggregated ad account performance insights across campaigns, ad groups, or ads. Filter by date range, sort by metrics like clicks or spend, and page through results.
Instructions
Retrieve performance insights aggregated across the entire ad account. Returns a list response (data[] with first_id/last_id/has_more for paging). Each row carries id, start_time, end_time, plus the projected fields such as impressions, clicks, spend, ctr, cpc, cpm, readable_time, campaign_name, ad_group_name, and ad_name. Combine aggregation_level, sort, and limit to rank entities (e.g. the top ad by clicks). Monetary metrics (spend, cpc, cpm) are in the account's currency as decimal values, not micros.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| since | No | Start date of the reporting window (inclusive), YYYY-MM-DD. Combined with `until` into a date_range time filter. | |
| until | No | End date of the reporting window (inclusive), YYYY-MM-DD. Combined with `since` into a date_range time filter. | |
| time_granularity | No | Aggregation bucket size: 'daily' for one row per day, or 'none' for a single aggregated row over the whole window. | |
| aggregation_level | No | Scope each row is aggregated to (e.g. 'ad' to break results out per ad even when querying a campaign). Combine with `sort` + `limit` to rank entities. | |
| fields | No | Fields to project in each row, e.g. ['ad_id','ad_name','campaign_name','readable_time','impressions','clicks','spend','ctr','cpc','cpm']. | |
| sort | No | Sort expressions applied in order, e.g. [{ "field": "clicks", "direction": "desc" }] to rank by most clicks. | |
| filters | No | Advanced filter expressions, passed through to the API as-is. | |
| limit | No | Maximum number of rows to return (1-10000). | |
| after | No | Pagination cursor: pass `last_id` from a previous page to fetch the next page. | |
| before | No | Pagination cursor: pass `first_id` from a previous page to fetch the previous page. |