Insights Tools
Retrieve Google Ads performance metrics at customer, campaign, ad group, or ad level.
Insights Tools
Tools for retrieving Google Ads performance metrics. The get_insights tool supports four reporting levels (customer, campaign, ad group, ad), a configurable metric list, and optional segment breakdowns.
get_insights
Retrieve Google Ads performance metrics at a chosen reporting level. Requires a date range. Returns the requested metrics with optional segment breakdowns. Values stored in micros (cost, average CPC, average CPM) are also returned converted to the account's currency.
Parameters
| Prop | Type | Default |
|---|---|---|
customer_id | string | - |
login_customer_id | string | undefined | - |
level | "customer" | "campaign" | "ad_group" | "ad" | - |
date_range | { start_date: string, end_date: string } | - |
metrics | InsightMetric[] | - |
segments | InsightSegment[] | undefined | - |
campaign_ids | string[] | undefined | - |
ad_group_ids | string[] | undefined | - |
ad_ids | string[] | undefined | - |
order_by_metric | InsightMetric | undefined | - |
order_desc | boolean | - |
page_token | string | undefined | - |
limit | number | undefined | - |
Supported metrics
Pass any subset as metrics:
impressions, clicks, cost_micros, conversions, conversions_value, ctr, average_cpc, average_cpm, all_conversions, all_conversions_value, view_through_conversions, video_views, engagements
Supported segments
Pass any subset as segments to break down rows:
date, device, day_of_week, ad_network_type, click_type, geo_target_country, hour, month, week, quarter, year
Filter / level rules
ad_group_idsis only valid at levelad_grouporadad_idsis only valid at leveladorder_by_metricmust also appear in themetricslist
Examples
Response
Returns a list of metric rows. Cost-related fields are returned both as micros (raw API value) and as the account's currency (converted). Segments selected via segments appear as additional fields on each row.