Search Audiences

Search for available audience segments (in-market, affinity, custom).

Use this tool to discover audience segment IDs for:

PMax campaigns: Use IDs with add_pmax_audience_signal (audience signals/hints)
Demand Gen / YouTube campaigns: Pass IDs via audience_segments parameter in create_demandgen_campaign or create_youtube_campaign (direct targeting)

Audience types:

In-market: Users actively researching products/services (e.g., “Business Software”)
Affinity: Users with long-term interests (e.g., “Technology Enthusiasts”)
Custom: Your account’s existing remarketing/customer match lists

Parameters:

query: Search term (e.g., “advertising services”, “SaaS tools”)

Execution time: 2-5 seconds

POST

api

tools

search_audiences

execute

Search Audiences

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/search_audiences/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "customer_id": "string",
    "query": "string"
  }
}
'

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

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 searching available audiences.

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

Select Google Campaign Type**USE THIS TOOL FIRST WHEN:** User wants to create a Google Ads campaign but hasn't specified the campaign type (Search, Performance Max, or YouTube). **IMPORTANT:** This tool should be called BEFORE any keyword research, asset discovery, or campaign creation when the user says things like: - "Create a Google Ads campaign" - "I want to run Google Ads" - "Set up a Google advertising campaign" - "Help me create ads on Google" - "I want to advertise on Google" - "Create a campaign" - "Run ads" This tool guides the user to select their campaign TYPE, then provides a detailed workflow for that specific type. **Campaign Types Available:** 1. **search** - Text ads in Google Search results (best for high-intent keywords, lead gen, local services) 2. **pmax** - Performance Max across all Google channels (best for ecommerce, brand awareness, multi-channel reach) 3. **youtube** - Video ads on YouTube (best for video content, brand storytelling, product demos) **Returns:** - What the campaign type is best for - Step-by-step workflow with which tools to call - Requirements (character limits, assets needed, etc.) - Natural follow-up question to start the creation flow **Do NOT use this tool if:** - User specifically asks for "search campaign" or "text ads" → go directly to research_keywords then create_search_campaign - User specifically asks for "PMax" or "Performance Max" → go directly to discover_existing_assets then create_pmax_campaign - User specifically asks for "YouTube campaign" or "video campaign" → go directly to validate_video then create_youtube_campaign - User is asking about performance/analytics → use get_campaign_performance - User is asking about existing campaigns → use list_campaigns **Parameters:** - campaign_type: 'search', 'pmax', or 'youtube' **Execution time:** Instant (no API call)

Search Audiences

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/search_audiences/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "customer_id": "string",
    "query": "string"
  }
}
'

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