Get campaign insights
get_campaign_insightsRead-only
Retrieve performance insights for an ad campaign, including impressions, clicks, spend, and derived metrics. Aggregate by day or entity, sort by any metric, and paginate through results.
Instructions
Retrieve performance insights for a single campaign. 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 |
|---|---|---|---|
| campaign_id | Yes | The ID of the campaign 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. |