Add Structured Snippets

Add structured snippet extensions to a campaign.

Structured snippets highlight specific aspects of your products/services.

VALID HEADERS:

AMENITIES, BRANDS, COURSES, DEGREE_PROGRAMS, DESTINATIONS
FEATURED_HOTELS, INSURANCE_COVERAGE, MODELS, NEIGHBORHOODS
SERVICE_CATALOG, SHOWS, STYLES, TYPES

RULES:

Header must be from predefined list
3-10 values required per snippet
Each value max 25 characters

EXAMPLES: For SaaS/Platform: Header: “Types” Values: [“Google Ads”, “Meta Ads”, “LinkedIn Ads”, “TikTok Ads”]

For Services: Header: “Services” (maps to SERVICE_CATALOG) Values: [“Campaign Launch”, “Analytics”, “Optimization”, “Reporting”]

For Brands: Header: “Brands” Values: [“Nike”, “Adidas”, “Puma”, “New Balance”]

Parameters:

campaign_id: The campaign ID (REQUIRED). Get from list_campaigns.
snippets: List of {header, values} objects (REQUIRED).
customer_id: Optional Google Ads customer ID

Execution time: 2-5 seconds

When to use:

User wants to add structured snippets
User asks to highlight product types, services, or brands
After creating a campaign, suggest adding snippets

Example: User: “Add structured snippets showing our ad platform types” Agent:

Uses list_campaigns to get campaign_id
Uses add_structured_snippets with header “Types” and relevant values

POST

api

tools

add_structured_snippets

execute

Add Structured Snippets

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/add_structured_snippets/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "campaign_id": "<campaign_id>",
    "customer_id": "string",
    "snippets": [
      {
        "header": "Brands",
        "values": [
          "Nike",
          "Adidas",
          "Puma"
        ]
      }
    ]
  }
}
'

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

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 adding structured snippet extensions to a campaign.

Structured snippets highlight specific aspects of your products/services.

Valid Headers: AMENITIES, BRANDS, COURSES, DEGREE_PROGRAMS, DESTINATIONS, FEATURED_HOTELS, INSURANCE_COVERAGE, MODELS, NEIGHBORHOODS, SERVICE_CATALOG, SHOWS, STYLES, TYPES

EXAMPLE for SaaS: Header: "Types" Values: ["Google Ads", "Meta Ads", "LinkedIn Ads", "TikTok Ads"]

EXAMPLE for Services: Header: "Services" (maps to SERVICE_CATALOG) Values: ["Campaign Launch", "Analytics", "Optimization", "Reporting"]

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

Analyze Search TermsDiscover keyword opportunities and optimize match types by analyzing actual search terms. ⚠️ IMPORTANT: This tool retrieves READ-ONLY data. Safe to call multiple times. Google Ads only - NOT available for TikTok. 🎯 **What This Tool Does (Performance Agent - Phase 1 Feature 3):** - Identifies OPPORTUNITY keywords: Converting search terms NOT in your keyword list - Identifies NEGATIVE keywords: Expensive terms with zero conversions - Analyzes MATCH TYPE performance: Exact vs Phrase vs Broad efficiency - Provides specific recommendations with suggested bids and match types - Ranks opportunities by profit potential (not just ROAS) **Returns comprehensive keyword intelligence:** - Top 20 opportunity keywords with suggested bids and match types - Top 20 negative keyword candidates with wasted cost breakdown - Match type performance comparison (Exact/Phrase/Broad) - Broad→Exact conversion recommendations - Total opportunity value and wasted spend amounts - Actionable recommendations for immediate implementation 🔍 **What Search Term Mining Reveals:** **Opportunity Keywords (Money Left on Table):** - Search terms that ARE converting but you're NOT bidding on them directly - These are queries triggering your ads via Broad/Phrase match, but should be added as Exact keywords - Example: User searches "enterprise security software pricing" → converts → but you only have "security software" as keyword - **Action:** Add high-converting search terms as new keywords with suggested bids **Negative Keywords (Money Wasted):** - Search terms costing >$10 with ZERO conversions - Low-intent queries like "free", "download", "crack", "how to" - Example: "free security software download" → 120 clicks, $540 spent, 0 conversions - **Action:** Add as negative keywords to stop wasting budget **Match Type Optimization:** - Compares performance of Exact vs Phrase vs Broad match - Identifies Broad keywords that should be converted to Exact for better control - Example: Broad "security software" has 45% wasted spend, but top search terms have 20x ROAS - **Action:** Convert high-performing Broad keywords to Exact match **Parameters:** - lookback_days: 7, 30, 60, 90, or 120 days (default: 30) - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - analysis_type: 'opportunities', 'negatives', 'match_types', 'all', or **'raw_report'** (default: 'all') - Use **'raw_report'** when the user wants to SEE their actual search terms — the words customers type into Google - force_refresh: true to trigger immediate API collection (default: false, uses cached data) - customer_id: Optional (uses connected account if omitted) - **campaign_id**: Optional — filter search terms to a specific campaign (get from list_campaigns) - **page**: Page number for raw_report pagination (default: 1) - **page_size**: Results per page for raw_report (1-100, default: 50) - **sort_by**: Sort for raw_report: 'cost' (default), 'clicks', 'impressions', 'conversions' - **min_clicks**: Minimum clicks filter for raw_report (default: 0) **Execution time:** 1-3 seconds (cached database query) **Data source:** search_term_daily_metrics table (updated nightly, 120-day retention) **⚡ RAW REPORT PAGINATION CONTRACT:** - When using analysis_type='raw_report', results are paginated - Check `pagination.has_more` — if true, call again with next `page` - Continue until `has_more` is false, then present consolidated results - Use `campaign_id` to focus on a specific campaign's search terms **Use this tool when:** - User asks "what keywords should I add?" - User wants to find wasted spend at keyword level - User asks "what should I add as negative keywords?" - User wants to improve match type efficiency - User asks "which Broad keywords should be Exact?" - User wants to discover hidden keyword opportunities - **User asks "show me my search terms" or "what are people searching for?"** → use analysis_type='raw_report' - **User asks "show me search terms for campaign X"** → use analysis_type='raw_report' with campaign_id ⚠️ **Platform Limitation:** This tool ONLY works for Google Ads. TikTok Ads does not provide search term data due to privacy restrictions. 📊 **AFTER calling this tool, help the user understand:** **Opportunity Keywords:** - **What it means:** These are winning search terms you're missing - **Profit potential:** Shows expected additional profit if added - **Suggested action:** Add as new keywords with recommended bid and match type - **Priority:** Start with highest opportunity_value (profit potential) **Example:** Search term: "enterprise security software pricing" - 8 conversions, $240 cost, $4,800 value - Opportunity Value: $4,560 profit potential - Suggested Bid: $6.00 (based on current CPC and ROAS) - Suggested Match Type: EXACT (high intent, proven converter) - **Action:** Add this as an Exact match keyword with $6 bid **Negative Keywords:** - **What it means:** These queries waste money and never convert - **Cost:** Total wasted spend on non-converting terms - **Common patterns:** "free", "download", "crack", "review", "how to" - **Action:** Add as negative keywords (campaign or account level) **Example:** Search term: "free security software" - 120 clicks, $540 wasted, 0 conversions - Reason: Low purchase intent (free) - **Action:** Add "free" as negative keyword at campaign level **Match Type Performance:** - **Exact:** Tightest control, lowest waste, highest ROAS (recommended) - **Phrase:** Moderate flexibility, some waste, decent ROAS - **Broad:** Most volume, highest waste, lowest ROAS (use sparingly) **Example Analysis:** - Exact: 450 keywords, ROAS 4.8x, 2% wasted spend ✅ - Phrase: 280 keywords, ROAS 3.2x, 8% wasted spend ⚠️ - Broad: 120 keywords, ROAS 1.8x, 45% wasted spend 🔴 **Quick Actions:** 1. Add top 5 opportunity keywords as Exact match 2. Block top 10 negative keywords at campaign level 3. Convert high-performing Broad keywords to Exact 4. Review Phrase keywords with >10% wasted spend **Visualization Tip:** For opportunity keywords, suggest creating a scatter plot (x=ROAS, y=Spend, size=conversions) to visualize profit potential. **Implementation Steps:** 1. Review top opportunities and negatives 2. Start with 5-10 new keywords (don't overwhelm account) 3. Add negatives in batches (test impact over 7 days) 4. Convert Broad→Exact gradually (monitor volume drop) 5. Re-run analysis monthly to discover new opportunities **Best Practices:** - Focus on opportunity_value (profit) not just ROAS - Start with Exact match for all new keywords (tightest control) - Add negatives at campaign level first (easier to undo than account level) - Monitor match type distribution: Aim for 60%+ Exact, 30% Phrase, 10% Broad - Review search terms every 2 weeks during active optimization 💬 **Community**: For keyword optimization discussions, visit our Discord: https://discord.gg/dH3Qt4YS

Add Structured Snippets

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/add_structured_snippets/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "campaign_id": "<campaign_id>",
    "customer_id": "string",
    "snippets": [
      {
        "header": "Brands",
        "values": [
          "Nike",
          "Adidas",
          "Puma"
        ]
      }
    ]
  }
}
'

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