Get ad insights
get_ad_insightsRead-only
Retrieve performance insights for a single ad, including impressions, clicks, spend, CTR, CPC, and CPM. Sort and limit results to rank ads by key metrics.
Instructions
Retrieve performance insights for a single ad. 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 |
|---|---|---|---|
| ad_id | Yes | The ID of the ad to report on. | |
| 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. |