gads_auction_insights
Retrieve auction insights comparing impression share, overlap rate, outranking share, top-of-page percentage, and absolute top percentage against competitors. Optionally filter by campaign.
Instructions
Auction Insights report: impression share, overlap rate, outranking share, top-of-page %, and absolute top % vs competitors. Optional campaign filter.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | No | Override GOOGLE_ADS_CUSTOMER_ID for this call | |
| start_date | No | Start date: YYYY-MM-DD, NdaysAgo, yesterday, or today | 28daysAgo |
| end_date | No | End date: YYYY-MM-DD, NdaysAgo, yesterday, or today | yesterday |
| campaign_id | No | Filter to a specific campaign ID |
Implementation Reference
- src/index.ts:204-209 (registration)Registers the 'gads_auction_insights' tool on the MCP server, linking it to auctionInsightsSchema and the auctionInsights handler function.
server.tool( "gads_auction_insights", "Auction Insights report: impression share, overlap rate, outranking share, top-of-page %, and absolute top % vs competitors. Optional campaign filter.", auctionInsightsSchema, async (args) => { try { return ok(await auctionInsights(args)); } catch (e) { return err(e); } } ); - src/tools/performance.ts:105-108 (schema)Defines auctionInsightsSchema with base args (customer_id, start_date, end_date) and optional campaign_id filter.
export const auctionInsightsSchema = { ...baseArgs, campaign_id: z.string().optional().describe("Filter to a specific campaign ID"), }; - src/tools/performance.ts:110-134 (handler)Implements auctionInsights handler, executing a GAQL query against the auction_insight view to return competitor auction metrics (domain, impression share, overlap rate, outranking share, top/absolute top %).
export async function auctionInsights(args: z.infer<z.ZodObject<typeof auctionInsightsSchema>>) { const customer = getCustomer(args.customer_id); const start = resolveDate(args.start_date); const end = resolveDate(args.end_date); const campaignClause = args.campaign_id ? `AND campaign.id = ${args.campaign_id}` : ""; const rows = await customer.query(` SELECT auction_insight.domain, segments.auction_insight_domain, campaign.id, campaign.name, metrics.auction_insight_search_impression_share, metrics.auction_insight_search_overlap_rate, metrics.auction_insight_search_outranking_share, metrics.auction_insight_search_position_above_rate, metrics.auction_insight_search_top_impression_percentage, metrics.auction_insight_search_absolute_top_impression_percentage FROM auction_insight WHERE segments.date BETWEEN '${start}' AND '${end}' ${campaignClause} ORDER BY metrics.auction_insight_search_impression_share DESC LIMIT 200 `); return { rowCount: rows.length, rows }; } - src/index.ts:29-31 (helper)Imports auctionInsights and auctionInsightsSchema from src/tools/performance.ts.
import { auctionInsights, auctionInsightsSchema,