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
| Parameter | Type | Description |
|---|---|---|
customer_id |
string |
Google Ads customer ID. Accepts dashed (123-456-7890) or digits-only (1234567890) format. Required. |
login_customer_id |
string | undefined |
Manager (MCC) customer ID for the login-customer-id header. |
level |
"customer" | "campaign" | "ad_group" | "ad" |
Reporting level. Maps to the GAQL FROM clause. Use "customer" for account totals; "campaign", "ad_group", or "ad" for per-entity rows. Default: "customer". |
date_range |
{ start_date: string, end_date: string } |
Inclusive date range, YYYY-MM-DD. Required. |
metrics |
InsightMetric[] |
Subset of metrics.* fields to include. Default: impressions, clicks, cost_micros, conversions, conversions_value, ctr, average_cpc. Only request what you need, because extra metrics inflate the query. |
segments |
InsightSegment[] | undefined |
Optional segments.* breakdowns. Each segment multiplies rows (e.g., "date" gives one row per day). |
campaign_ids |
string[] | undefined |
Optional campaign IDs to restrict results. Valid at any level. |
ad_group_ids |
string[] | undefined |
Optional ad group IDs. Valid at levels "ad_group" and "ad". |
ad_ids |
string[] | undefined |
Optional ad IDs. Valid only at level "ad". |
order_by_metric |
InsightMetric | undefined |
Optional metric to ORDER BY. Must also appear in metrics. |
order_desc |
boolean |
When ordering, sort descending. Default: true. |
page_token |
string | undefined |
Pagination token from a previous response. |
limit |
number | undefined |
Optional row cap (applied in GAQL). |
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
Natural Language
What's my Google Ads spend and conversions for the last 30 days?
Top 10 campaigns by ROAS in customer 123-456-7890 last month
Daily impressions and clicks per device for campaign 22334455 in November
Account totals
{
"tool": "get_insights",
"arguments": {
"customer_id": "123-456-7890",
"level": "customer",
"date_range": {
"start_date": "2026-04-01",
"end_date": "2026-04-30"
},
"metrics": ["impressions", "clicks", "cost_micros", "conversions"]
}
}
Per-campaign breakdown
{
"tool": "get_insights",
"arguments": {
"customer_id": "123-456-7890",
"level": "campaign",
"date_range": {
"start_date": "2026-04-01",
"end_date": "2026-04-30"
},
"metrics": ["cost_micros", "conversions", "conversions_value"],
"order_by_metric": "conversions_value",
"order_desc": true,
"limit": 10
}
}
Daily ad-group device breakdown
{
"tool": "get_insights",
"arguments": {
"customer_id": "123-456-7890",
"level": "ad_group",
"date_range": {
"start_date": "2026-04-01",
"end_date": "2026-04-07"
},
"metrics": ["impressions", "clicks", "ctr"],
"segments": ["date", "device"],
"campaign_ids": ["22334455"]
}
}
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.
Related
- list_ad_accounts Discover customer IDs to query
- list_campaigns Find campaign IDs to scope insights to