Skip to main content
This tool retrieves READ-ONLY data. Safe to call multiple times. Returns campaign hierarchy (paginated by ad groups):
  • Campaign details (name, status, budget, bidding strategy)
  • Ad groups with their settings (paginated — default 5 per page)
  • Keywords per ad group (including match types, bids, status)
  • Ads per ad group (including RSA headlines/descriptions, ad strength)
  • Negative keywords per ad group
  • Campaign-level extensions and negative keywords (on page 1 only)
  • Pagination metadata (page, total_pages, has_more)
  • Summary counts (total ad groups, keywords, ads across ALL pages)
Parameters:
  • campaign_id: The campaign ID (REQUIRED - get from list_campaigns)
  • customer_id: Optional (uses connected account if omitted)
  • page: Page number, 1-based (default: 1)
  • page_size: Ad groups per page, 1-50 (default: 5)
  • ad_group_id: Optional — fetch only this single ad group (bypasses pagination)
  • include: What detail per ad group: ‘all’ (default), ‘summary’ (counts only), ‘keywords’, ‘ads’
⚡ PAGINATION CONTRACT (IMPORTANT FOR AI AGENTS):
  • The response includes pagination.has_more — if true, you MUST call again with page incremented
  • Continue calling until has_more is false
  • Then consolidate all pages and present the complete campaign structure to the user
  • The summary section is always included and shows total counts across ALL ad groups (not just the current page)
  • Extensions and campaign-level negative keywords are only returned on page 1
  • Use ad_group_id to drill into a single ad group when the user asks about a specific one
  • Use include='summary' for a quick overview without nested keyword/ad data
Execution time: 3-8 seconds per page (multiple API queries) Use this tool when:
  • User wants to update an existing campaign
  • User wants to see current keywords/ads
  • User wants to add extensions to existing campaign
  • User says “show me what’s in this campaign”
  • Before making any updates to a campaign
Important IDs returned:
  • campaign.id - For campaign-level updates (budget, status)
  • ad_groups[].id - For adding keywords/ads
  • keywords[].id - For keyword updates (status, bids)
  • ads[].id - For ad content updates
Example flow:
  1. User: “I want to update my campaign”
  2. Agent: Uses list_campaigns to show all campaigns
  3. User: Selects campaign “Summer Sale 2025”
  4. Agent: Uses get_campaign_structure with that campaign_id
  5. If has_more=true, agent calls again with page=2, page=3, etc.
  6. Agent: Shows consolidated structure and asks what to update
  7. User: “Change the headlines”
  8. Agent: Uses update_ad_headlines with the ad_id from structure

​
OpenAPI

/api-reference/openapi.json post /api/v1/tools/get_campaign_structure/execute