Get Campaign Structure

Get campaign structure with ad groups, keywords, ads, and extensions. Supports pagination for large campaigns.

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:

User: “I want to update my campaign”
Agent: Uses list_campaigns to show all campaigns
User: Selects campaign “Summer Sale 2025”
Agent: Uses get_campaign_structure with that campaign_id
If has_more=true, agent calls again with page=2, page=3, etc.
Agent: Shows consolidated structure and asks what to update
User: “Change the headlines”
Agent: Uses update_ad_headlines with the ad_id from structure

POST

/

api

/

v1

/

tools

/

get_campaign_structure

/

execute

Get Campaign Structure

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/get_campaign_structure/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "ad_group_id": "string",
    "campaign_id": "<campaign_id>",
    "customer_id": "string",
    "include": "all",
    "page": 1,
    "page_size": 5
  }
}
'

{
  "data": {
    "quota": {
      "limit": 150,
      "period_end": "2026-05-01",
      "tier": "plus",
      "used": 42
    },
    "text": "(tool-specific textual output for get_campaign_structure)"
  },
  "success": true,
  "tool": "get_campaign_structure"
}

Authorizations

Authorization

string

header

required

API key from https://adspirer.ai/keys. Prefix sk_live_. Treat as a secret — never commit.

Headers

Idempotency-Key

string<uuid>

Client-generated UUID to make writes idempotent. Strongly recommended for write tools. A repeat call with the same key returns the cached result instead of re-executing. Example: 550e8400-e29b-41d4-a716-446655440000

Body

application/json

All tool arguments are wrapped in an arguments object. The fields accepted inside arguments are listed below — required fields are marked with a red asterisk.

arguments

object

required

Input schema for getting campaign structure with pagination

Show child attributes

Response

Tool executed successfully. data.text carries the human-readable result (markdown-friendly). data.quota shows your current usage against the plan limit. data.structured appears when the tool emits machine-parseable structured content. data.content appears for tools that return non-text blocks (images, resources).

Returned on HTTP 200. data.text is the primary human-readable output. data.quota is always present for billable calls. data.structured is set only when the tool emits machine-parseable structured content. data.content is set only when the tool emits non-text content blocks.

data

object

required

Show child attributes

success

boolean

required

tool

string

required

Echoed tool_name from the request URL.

Last modified on April 23, 2026

Get Campaign TargetingGet location/geo targeting for a Google Ads campaign. This tool retrieves READ-ONLY data. Safe to call multiple times. **Returns location targeting details:** - Targeted locations (cities, states, countries, metros the campaign targets) - Excluded locations (negative geo targets) - Bid modifiers per location (if set) - Location type (Country, State, City, Metro, etc.) - Summary counts (targeted, excluded, total) **Parameters:** - campaign_id: The campaign ID (REQUIRED - get from list_campaigns) - customer_id: Optional (uses connected account if omitted) **Execution time:** 1-3 seconds (single API query) **Use this tool when:** - User asks "where is this campaign targeting?" or "what locations?" - User wants to see geo targeting for a campaign - User asks "what countries/cities/states does my campaign target?" - Before recommending location targeting changes - To verify location setup after campaign creation **Returns for each location:** - name: Short location name (e.g., "New York") - canonical_name: Full hierarchical name (e.g., "New York,New York,United States") - country_code: ISO country code (e.g., "US") - target_type: Location type (Country, State, City, County, Metro, etc.) - is_negative: true if this location is EXCLUDED - bid_modifier: Bid adjustment for this location (null if no modifier) **Example flow:** 1. User: "What locations does my Diamond Ring campaign target?" 2. Agent: Uses get_campaign_targeting with campaign_id 3. Returns: Targeted: United States, New York, Los Angeles; Excluded: none

Get Campaign Structure

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/get_campaign_structure/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "ad_group_id": "string",
    "campaign_id": "<campaign_id>",
    "customer_id": "string",
    "include": "all",
    "page": 1,
    "page_size": 5
  }
}
'

{
  "data": {
    "quota": {
      "limit": 150,
      "period_end": "2026-05-01",
      "tier": "plus",
      "used": 42
    },
    "text": "(tool-specific textual output for get_campaign_structure)"
  },
  "success": true,
  "tool": "get_campaign_structure"
}