Documentation Index
Fetch the complete documentation index at: https://www.adspirer.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
- MCP base image hardening — all six MCP sub-servers (hub + Google + Meta + TikTok + LinkedIn + Monitoring) pinned to
python:3.11-slim-trixie with audit-pass cryptography and authlib dependencies.
- Container scanning by digest — vulnerability scans resolve images to their content digest instead of the floating
:latest tag, so the report can’t drift between scan time and image promotion.
- Tool routing resilience — tighter input handling on Google Ads tool routing and a longer hub timeout for slow Meta calls.
- Watch Agent stability — finding classifier no longer cascades a stuck SQL transaction into a noisy false-positive.
Connect Multiple Google Logins to One Adspirer Account
A single Adspirer account can now hold multiple Google OAuth grants, each with its own non-overlapping set of Google Ads customer IDs. Agencies and consultants who manage Google Ads across separate Google identities no longer need a second Adspirer account.
- Adds a second (or third) Google login from the Connections → Google Ads → Add another Google login flow.
- Each grant tracks its own customer IDs; the agent routes tool calls to the right OAuth based on the customer you reference.
- Available on Max annual today; rolling to the rest of the paid tiers behind a feature flag.
A set of improvements to how Adspirer works with Meta Business Manager and ad-account-scoped assets.
- Business Manager-wide import — when you connect Meta, Adspirer discovers every ad account inside the Business Manager you grant access to, not just the one you happened to click during OAuth. The Manage Accounts modal lists them all so you can pick which ones to activate.
- Per-account asset scoping — image, video, and creative discovery is now scoped to the specific ad account you’re targeting. Eliminates the “this asset was discovered but Meta says it’s not in this ad account” error class.
- Opt-in auto-copy of creatives — when you reuse a creative from a sibling ad account, Adspirer offers to copy it into the target account before launching the campaign (opt-in per call) so the launch doesn’t stall on asset placement.
- Clearer “no account” error — when a tool call can’t find a Meta account, the response distinguishes a stale token from a missing-row state so you (or your AI client) know whether to reconnect or just re-select.
The active-account cap is per platform — every plan card across pricing and the Manage Accounts modal now states up front how many active accounts you get per platform (Google + Meta + LinkedIn + TikTok each counted independently). When you’re at the cap, the modal shows an inline upsell that links directly into the Adspirer plan picker.Smaller Improvements
- Sidebar rename — “Account Setup” is now Home. Same page, more accurate label for users past initial setup.
- Brief coverage — scheduled performance briefs are scoped to your selected accounts (not just the primary), with full multi-OAuth coverage so a second Google identity’s accounts no longer show up empty.
- Live-tail merge for Google Ads in the brief data fetchers so spend that hit the API after the nightly sweep still lands in your brief.
Plan Limits, Cap Rework & Connections Panel Refresh
Active-Account Caps — New Per-Tier Limits
The big change: annual plans now activate up to 5 accounts per platform, not 1. Monthly plans (except Max) still cap at 1 per platform. Full table:| Plan | Monthly | Annual |
|---|
| Free | 1 | 1 |
| Plus | 1 | 5 |
| Pro | 1 | 5 |
| Max | 5 | 5 |
- “Account” means an ad account on a single platform — Plus annual customers can activate up to 5 Google Ads accounts and 5 Meta accounts and 5 LinkedIn accounts and 5 TikTok accounts.
- Every Stripe webhook now reconciles down-tier moves automatically: if you downgrade from Max monthly to Plus monthly, excess actives demote to inactive (deterministically — primary-set-first, then most-recently-synced).
- Caps live in a new
subscription_plan_limits table so we can adjust without redeploys, and every change is written to a tier_limit_changes audit log.
- Defense in depth: the MCP hub also truncates account lists at the tier cap before returning them, so any reconciliation gap can’t accidentally let a downgraded user keep agent access to more accounts than their plan allows.
Onboarding & Connections — Smoothed Out
- Onboarding Step 5 stays put — fixed an issue where the Congrats screen would bounce users back to Step 1 if their AppUser stub hadn’t finished writing after Stripe checkout. You always land on Step 5 post-payment now.
- Connections panel — unified stacked rows — Available Platforms restyled to compact rows that match the Pipedream integration cards below. The Google Analytics + Klaviyo cards no longer hide below the fold.
- OAuth modal always opens — after a successful OAuth, the account-selection modal opens regardless of how many accounts are under your OAuth identity. No more silent auto-pick when you have multiple accounts and didn’t realize.
- Tier-aware Manage Accounts modal with an inline Edit button and a Connections-panel mirror so the active-account picker shows the same state in both surfaces.
- Admin: Plan Limits page with a dry-run preview that counts affected users before you commit a cap change.
Bug Fixes
- “Add another Google login (coming soon)” placeholder is replaced with a Max-annual upsell that explains how to unlock it today.
get_ad_accounts now filters out deselected (inactive) accounts so they stop rendering as green Active in the Connected Platforms UI.
Google Analytics & Klaviyo Integrations
Adspirer’s first non-ad-platform integrations are live. Plus, Pro, and Max users can now connect Google Analytics 4 and Klaviyo alongside their ad accounts, and the agent can read and act on those properties through chat.What You Can Do
| Integration | Tool | What it does |
|---|
| Google Analytics (GA4) | google_analytics | Read property data — sessions, conversions, traffic sources, landing-page performance — so the agent can correlate paid ad spend with site behavior. |
| Klaviyo | klaviyo | Read campaigns, flows, segments, profiles, and metrics so the agent can pull email/SMS performance alongside paid media. |
action="list_tools" first to discover what’s available, then action="execute" with the specific Pipedream tool name to call it. The agent handles this two-step automatically.How It Works
- Connect from the Connections tab at adspirer.ai — each integration has its own OAuth popup powered by Pipedream Connect.
- Gated to Plus and above. Free users see the integration card with a “Upgrade” prompt that links into the Adspirer plan picker.
- Disconnect anytime from the same panel; idle connections (>90 days) get pruned automatically to keep the integration list tidy.
Free-tier users can now ask the in-app chat widget to delete their account end-to-end — no email round-trip required. The widget confirms before executing and runs the full GDPR delete (hard-delete + pseudonymize + retain per Article 17(3)(b)).OpenClaw Plugin v2026.5.12
Bumped to expose the new integration tools plus 9 additional Google Ads tools (PMax search themes, audience signals, ad group management) and 3 monitoring tools.Watch Agent Briefs
- Conversion-tracking caveat — briefs now include a “conversion data is reported through your platforms” caveat so anomalies in conversion volume aren’t read as Adspirer numbers.
- Paused vs active classification — briefs no longer call a paused campaign “underperforming” — paused campaigns are explicitly flagged as paused.
- Account names cleaned — fixed a template placeholder that was occasionally showing up in account labels.
- Dead dashboard link replaced — the in-brief “open dashboard” link is now a copy-paste AI prompt you can run in your AI client to drill into the finding.
- Recommendations de-alarmed — toned down “URGENT” language on routine recommendations so high-severity callouts read as actually high severity.
Monitors & Alerts
create_monitor returns 409 when you try to create a duplicate alert instead of silently writing two.- Digest email values corrected — the daily digest now reports the same value the alert evaluated against, not a stale snapshot.
- Address by name — the in-app support widget greets you by name from turn 1.
- Panel state persists — the widget stays open across page navigations and refreshes, with a time-aware “welcome back” greeting when you return.
Watch Agent — Proactive Signal
The Watch Agent is a server-side AI agent that scans your connected ad accounts every 15 minutes, identifies issues, and emails you a copy-paste re-entry prompt so you can act immediately inside your AI client. No more waiting for weekly reviews to catch a broken campaign.What the Watch Agent does:
- Analyzes ROAS, CPA, CTR, spend, and conversion rate across all connected platforms
- Distinguishes true anomalies from normal variance (noise suppression built in)
- Stages pre-validated fix actions (pause campaign, adjust bid, add negatives) alongside each finding
- Sends a finding email with a ready-to-paste prompt when severity ≥ medium is detected
MCP tools for the Watch Agent:| Tool | Type | Description |
|---|
run_watch_now | Read | Trigger an on-demand Watch Agent scan immediately — don’t wait for the next scheduled run |
get_signal_briefing | Read | Pull the advisory briefing and pre-staged fixes for a specific Watch Agent finding |
apply_signal_actions | Write | Apply the pre-staged fixes from a finding — approve with one call |
list_pending_actions | Read | See all actions staged by the Watch Agent waiting for your approval |
manage_action | Write | Approve or reject an individual staged action |
"Run the watch agent on my accounts now"
→ run_watch_now
"Show me the briefing for signal abc123"
→ get_signal_briefing(signal_id="abc123")
"Apply the staged fixes"
→ apply_signal_actions(signal_id="abc123")
Monitors & Alerts — Web UI
A new Monitors page at adspirer.ai/monitors lets you create and manage performance alerts without opening your AI client. Every alert you create on the web goes to the same backend as the MCP create_monitor tool — the Watch Agent reads from one unified table regardless of which surface created the alert.What you can do on the Monitors page:
- Create alerts for CPA, ROAS, CTR, CPC, spend, conversions, impressions, clicks, cost per lead, conversion rate, or budget utilization
- Set thresholds with “goes above” or “drops below” operators
- Optional: trigger only after N consecutive days (1–14) — filter out one-off noise
- Scope to specific platforms (Google Ads, Meta, LinkedIn, TikTok) or all connected
- Edit, pause, resume, test (dry-run), and delete alerts in the dashboard
Supported alert metrics:| Metric | Example threshold |
|---|
| CPA | Alert when CPA goes above $50 |
| ROAS | Alert when ROAS drops below 2x |
| CTR | Alert when CTR drops below 1% |
| Spend | Alert when daily spend goes above $500 |
| Budget utilization | Alert when pacing exceeds 110% |
| Conversions | Alert when conversions drop below 1 |
| Clicks, Impressions | Volume monitoring |
| Tool | Type | Description |
|---|
get_monitor_history | Read | See all past trigger events for a specific alert — when it fired, what values triggered it |
test_monitor | Read | Dry-run a monitor against today’s data — see whether it would fire without waiting |
manage_scheduled_task | Write | Unified pause, resume, or delete for any brief, monitor, or scheduled task |
PDF Reports for Scheduled Briefs
Scheduled performance briefs now attach a PDF to the email. The PDF contains the same tables and charts as the email body — useful for sharing with stakeholders who don’t have Adspirer access.Monitoring tool count: 8 → 16Annual Plans & Max Quota
Annual Quota Pooling
Annual subscribers now get a single pooled allowance for the full year instead of per-month caps. No monthly resets — use your calls whenever you need them.| Plan | Annual Price | Annual Pool | Monthly Equivalent |
|---|
| Plus | $485/year | 1,800 calls | ~150/month |
| Pro | $999/year | 7,200 calls | ~600/month |
| Max | $2,000/year | 50,000 calls | ~4,167/month |
- Pool renews on your subscription anniversary date. Unused calls do not roll over.
- Annual subscribers are never charged overage — the yearly pool is your total budget for the year.
- Max annual (50,000) is intentionally higher than 12× monthly (36,000) as the upgrade incentive for high-volume months.
Max Plan: 3,000 calls/month
The Max plan monthly limit is now formalized at 3,000 calls/month (previously displayed as “unlimited”). This aligns with the Stripe product metadata and all enforcement layers. Max annual subscribers retain the 50,000/year pool with no monthly cap.See the updated Pricing & Tool Calls page.GDPR Article 17 — Right to Erasure
Account deletion requests (submitted via support@adspirer.com) now correctly pseudonymize all associated audit log rows, satisfying GDPR Article 17 right-to-erasure requirements. A bug in the deletion pipeline previously left historical audit rows intact. A one-time backfill also pseudonymized rows from prior deletion requests that had been processed without full erasure.Account deletion is handled by the Adspirer support team. To request account deletion, email support@adspirer.com. TikTok: 3 Customer-Blocking Fixes
Three bugs from live tool call logs that were causing TikTok campaign creation failures.Local Currency for Budget Floors
TikTok campaign budget pre-flight checks were using USD as the hardcoded currency regardless of the advertiser’s local currency. This caused incorrect minimum budget enforcement for non-USD accounts. The fix fetches the correct currency and timezone from TikTok’s API at OAuth connect time, and backfills existing accounts. A one-time database backfill corrected 167 of 170 affected accounts (3 had expired tokens).Disclaimer Text Format
Ad disclaimer text must be passed as a structured object ({"text": "..."}) rather than a plain string per TikTok’s API requirements. Campaigns with a disclaimer_text were silently failing at TikTok’s server even though the tool accepted the input. The fix wraps string input into the correct object format automatically. Disclaimer text is also now enforced at a max of 90 characters (TikTok’s hard limit).CTA Autocorrect & Full Whitelist
The call_to_action field on TikTok ads previously accepted stale values that TikTok’s API would reject at campaign creation time. The field is now backed by:
- 30-value authoritative whitelist extracted from TikTok’s rejection response
- 14-alias autocorrect map for commonly used old values:
| Old (accepted, now autocorrected) | New (correct) |
|---|
DOWNLOAD | DOWNLOAD_NOW |
BUY_NOW | SHOP_NOW |
INSTALL | INSTALL_NOW |
WATCH | WATCH_NOW |
GET_OFFER | GET_QUOTE |
BOOK | BOOK_NOW |
add_tiktok_ad, carousel). Invalid values that don’t map to an alias return a clear error with the full allowed list.Google Ads: Campaign Control Expansion
18 new capabilities across campaign management, search campaign creation, and asset tools, resolving the top customer-reported gaps from production.Ad Group Pause / Resume
Two new tools give you ad group-level control without touching the parent campaign:
pause_ad_group — Pause an individual ad group while leaving the campaign runningresume_ad_group — Resume a paused ad group
update_campaign — Expanded Controls
update_campaign now accepts 6 new parameters:| Parameter | What it does |
|---|
search_partners | Enable or disable the Google Search Partners network |
display_expansion | Enable or disable Display Expansion for Search campaigns |
language_codes | Replace the campaign’s language targeting (ISO-639-1 codes like "en", "es", "fr" or languageConstants/<id> resource names from list_google_languages) |
locations_to_add | Append geo targets (free-text or geoTargetConstants/<id> resource names) |
locations_to_remove | Remove geo targets by criterion resource name |
audience_targeting_mode | Set OBSERVATION (bid adjustments only) or TARGETING (targeting restriction) |
ai_max_enabled | Enable or disable AI Max for eligible Search campaigns |
create_search_campaign — Per-Keyword Match Types
Initial keywords in create_search_campaign now accept a mixed format:
- Plain strings default to BROAD (backward compatible)
- Objects like
{"text": "running shoes", "match_type": "PHRASE"} set EXACT or PHRASE on individual keywords
Previously, all initial keywords were forced to BROAD match — requiring a separate add_keywords call to set correct match types.Three new tools for attaching assets to Search campaigns:
add_business_name_asset — Attach a business name text asset (max 25 characters) at the campaign leveladd_call_asset — Attach a phone number call asset with country code. Accepts an optional call_conversion_action resource name to enable call conversion tracking.add_search_campaign_image — Attach image assets to Search campaigns (logo, landscape, square, portrait). Accepts HTTP URLs or base64-encoded data URIs.
get_campaign_structure — Expanded Fields
get_campaign_structure now surfaces network_settings (Search Partners, Display Expansion), EU political content eligibility, and geo target type for each campaign. get_campaign_targeting responses now include resource_name on each criterion row so you can pass exact IDs to locations_to_remove.Callout Extension Policy
CTA words in callout extensions (e.g., “Learn More”, “Sign Up”) were previously silently dropped. They now generate a warning in the tool response instead of being removed — giving you visibility into which callouts were affected without blocking campaign creation.Google Ads tool count: 89 → 92TikTok Ads — Full SDK Overhaul + Layer 2
The TikTok integration received its largest overhaul since launch — every customer-blocking bug from production logs was closed and the platform’s full API depth is now accessible.Phase 0 — bug fixes (all customer-blocking): Ad group spec re-architected to 86 fields; creative spec to 59 fields. Image direct-path skips base64 conversion. Slideshow (unsupported by TikTok) removed from code paths. ffmpeg added to Cloud Run for video frame extraction. 5 prod-harness-discovered bugs (pause schema, ValueError hints, image path, envelope, deletes) fixed.Phase 1 — full SDK depth: All 86 ad-group fields and 59 creative fields from TikTok’s marketing API are now surfaced through add_tiktok_ad_group and add_tiktok_ad. Previously only a subset was accessible.Layer-1 — validity matrix: 6 common error classes are now caught before the API call — saving tool call quota and eliminating confusing API rejection messages.Layer-2 — new tool and rich targeting:| Tool | Type | Description |
|---|
explain_tiktok_objective | Read | Given your goal (leads, sales, traffic, app installs), returns the correct TikTok campaign objective, recommended ad format, and validity constraints — eliminating trial-and-error |
add_tiktok_ad_group now supports interest filters, behavioral keywords, action categories, carrier/device targeting, and language filters — all available through search_tiktok_targeting.Atomic rollback: If campaign creation fails at any sub-step (ad group or ad level), previously-created resources are automatically rolled back. No more partial campaigns left in your account.Two new tools for conversion analysis — separate from the existing audit_conversion_tracking health check:| Tool | Type | Description |
|---|
list_conversion_actions | Read | List all conversion actions in your Google Ads account (purchases, form fills, phone calls, etc.) with status and tracking method |
get_conversion_action_performance | Read | Pull conversion metrics (volume, value, CPA) broken down by conversion action — see which actions are actually driving results |
get_campaign_targeting is also expanded: it now returns all criterion types (location, language, audience, device, ad schedule, topic, content label) instead of just locations and languages.Google Ads — Ad-Group Extensions
add_sitelinks, add_callout_extensions, and add_structured_snippets now accept an optional ad_group_id parameter. Extensions attached at the ad-group level override campaign-level extensions for that specific ad group — useful for ad groups targeting different products or audiences.A new middle-layer analytics tool between campaign and ad level:| Tool | Type | Description |
|---|
get_meta_adset_performance | Read | Pull spend, clicks, CTR, CPA, ROAS, and conversions broken down by ad set within a campaign — see which audience segments and placements are driving results before going to individual ad level |
Billing — Plan Management UI
The Billing page now supports plan changes without contacting support:
- Downgrades — Switch from Pro → Plus or Plus → Free directly from the billing page
- Interval switching — Toggle between monthly and annual billing mid-cycle
- Max plan visibility — Max plan capabilities and tool call limits are now shown inline on the billing page
All plan changes go through Stripe Checkout (same flow as upgrades) for consistent billing history.Reconnect now resumes metric collection
Fixed an issue where reconnecting an ad account after an authentication error wouldn’t actually resume background metric collection. Previously, if Adspirer auto-paused an account because the platform returned a 401/403 (expired token, revoked permissions), reconnecting through the connections page issued a fresh OAuth token but left metrics_collection_enabled set to false — so daily collection kept skipping the account. Customers were effectively reconnecting for nothing.Reconnect flows for Meta Ads, Google Ads, TikTok Ads, and LinkedIn Ads now automatically clear auth-error pauses on the same user and platform once the new token is saved, restoring daily metric collection without manual intervention. Admin pauses, free-tier pauses, and other auto-pause types are untouched.Sequential sub-agents for Max plan
Max plan users can now run sequential sub-agents across multiple active ad accounts in a single conversation. Instead of switching primary accounts one at a time, mark multiple accounts as active and let Adspirer fan out tool calls across each — perfect for agencies running cross-account audits, weekly briefs, or bulk optimizations from a single prompt.What’s new
- Active accounts model — Max users can have multiple ad accounts marked active per platform simultaneously. Lower tiers continue with the primary-account model.
list_connected_accounts — New system tool that returns every active account across platforms with IDs, names, and status. Reads directly from the database (zero API calls, doesn’t count against your quota).- Cross-account workflows — A single prompt like “run last week’s performance brief across all my Google Ads accounts” now triggers per-account sub-agents that aggregate into one consolidated response.
- Active set management — Add or remove accounts from your active set at adspirer.ai/connections.
Who this is for
Agencies, portfolio managers, and anyone managing 3+ ad accounts who currently bounces between primaries. See the updated Multi-Account Management guide.Google Display Ads — end-to-end CRUD
Full Google Display Network support joins Search, PMax, YouTube, and Demand Gen. Ships with 27 new MCP tools verified live against Google Ads API v21. Standard Display (full manual control) and Smart Display (Google-managed) are both supported. Display Ads guide →What’s new
create_display_campaign — Standard Display (channel=DISPLAY) and Smart Display (sub_type=DISPLAY_SMART_CAMPAIGN) with a single flag. Creates campaign + default ad group + Responsive Display Ad, all PAUSED.- 5 targeting surfaces — GET / ADD / REMOVE on each:
add_display_audiences — In-market, affinity, custom audiences, user lists, combined audiencesadd_display_topics — Google content categoriesadd_display_placements — Specific websites, apps, YouTube channels, YouTube videosadd_display_keywords — Contextual (always BROAD match on Display)update_display_demographics — Age, gender, parental status, income exclusionsremove_display_criteria — Unified removal across all 5 surfaces
- Full CRUD:
add_display_ad_group, add_display_ad, update_display_ad_creative (colors, CTA, images, videos, promo, format_setting), update_display_ad_group, update_display_campaign_schedule, update_display_frequency_caps, plus remove variants
- Geo + language resolvers —
resolve_google_locations and list_google_languages reject ambiguous inputs (“Baja” surfaces 5 candidates) instead of silently falling back to US. All Google campaign types benefit.
- RSA + RDA dispatch —
update_ad_headlines, update_ad_descriptions, and update_ad_content now dispatch on ad type. Responsive Search Ads (3–15 headlines, 2–4 descriptions) and Responsive Display Ads (1–5 headlines, 1–5 descriptions, plus long_headline) work side-by-side.
select_google_campaign_type — Now includes 'display' and 'demandgen' alongside 'search', 'pmax', and 'youtube' with full decision-tree workflows.
OpenClaw plugin update
OpenClaw bumps to v2026.4.13. Tool count goes from 95 → 119 — adds all 22 Display Ads tools + 2 helpers. OpenClaw agent guide →Regressions
None. RSA users see identical behavior plus clearer validator errors. PMax, Demand Gen, and YouTube still hit the same unchanged paths.REST API Reference now live
Every Adspirer tool is now callable over plain HTTP and documented at adspirer.com/docs/api-reference. Same 178 endpoints as the MCP server — same auth, same quota, same write-guards — but over request/response JSON so consumers that can’t speak SSE (n8n, Zapier, Make, cron jobs, GitHub Actions, your own backend) can use them.What’s included
- 178 auto-generated endpoint pages grouped by platform: Google Ads (51), Meta Ads (36), LinkedIn Ads (45), TikTok Ads (29), monitoring (13), general (3), audit (1)
- Interactive “Try it” playground — authorize once with your
sk_live_... key, call any endpoint from the browser against the real API
- REST API overview with use-case patterns for Slack ChatOps, daily account briefings, portfolio rollups, alert / auto-pause, SaaS product embedding, and headless CI
- Architecture sequence diagrams for each pattern showing how ingress → Adspirer → egress wires up
Base URLs
| |
|---|
| Endpoints | https://api.adspirer.ai/api/v1/tools/<tool_name>/execute |
| Swagger UI | api.adspirer.ai/docs |
| OpenAPI spec | api.adspirer.ai/openapi.json |
Auth
Pass your API key as Authorization: Bearer sk_live_... — same keys you already use for headless MCP. Generate one at adspirer.ai/keys. Free tier includes 15 calls / month.Idempotency
Write operations accept an Idempotency-Key header. Strongly recommended for n8n, Zapier, and any retry-prone client — a repeated call with the same key returns the cached result instead of creating duplicates.Pay-as-you-go overage for Plus subscribers
Plus plan subscribers no longer hit a hard stop at 150 tool calls. After your included calls are used, you can keep working at 0.50peradditionalcall∗∗,cappedat∗∗50/month in overage charges.How it works
- Overage billing is auto-enabled for all Plus subscribers
- Your first 150 calls are included in your $49/month subscription
- After 150 calls, each additional call is billed at $0.50 through Stripe
- Monthly overage is capped at 50—yourmaximumbillis99/month
- Disable overage anytime from your billing page to revert to the previous behavior (hard stop at 150 calls)
Usage notifications
- At 135 calls (90%): one-time notification that overage billing kicks in after 150
- At 151 calls: one-time notification that you’re now on usage-based billing
- All other overage calls: no interruptions — just keep working
Tier-specific messaging
- Plus: Minimal notifications during overage — you’re paying for usage, so no nagging
- Pro: Usage stats shown without upgrade prompts
- Max: No usage hints — high included limit, don’t worry about it
See the updated Pricing & Tool Calls page.All 29 performance and analytics tools across Google Ads, Meta Ads, LinkedIn Ads, and TikTok Ads now accept a raw_data parameter. When set to true, tools return a compact JSON code block with only raw metrics (spend, clicks, impressions, conversions, CPA, CPC, CTR, CVR, ROAS) — stripped of severity labels, suggested bids/budgets, industry benchmarks, and optimization recommendations.Default behavior is unchanged. Existing markdown output with recommendations is returned unless you explicitly pass raw_data=true.When to use raw data mode
- You run your own attribution model and want raw numbers only
- You want to minimize token usage in AI client responses
- You’re piping metrics into a spreadsheet, dashboard, or external tool
| Platform | Tools with raw_data support |
|---|
| Google Ads | get_campaign_performance, analyze_wasted_spend, optimize_budget_allocation, analyze_search_terms, explain_performance_anomaly |
| Meta Ads | analyze_meta_campaign_performance, analyze_meta_ad_performance, analyze_meta_wasted_spend, optimize_meta_budget, analyze_meta_audiences, detect_meta_creative_fatigue, optimize_meta_placements, explain_meta_anomaly, get_meta_audience_insights |
| LinkedIn | get_linkedin_campaign_performance, analyze_linkedin_engagement, get_linkedin_audience_insights, analyze_linkedin_wasted_spend, optimize_linkedin_budget, explain_linkedin_anomaly, analyze_linkedin_creative_performance |
| TikTok | get_tiktok_campaign_performance, get_tiktok_ad_performance, analyze_tiktok_wasted_spend, optimize_tiktok_budget, detect_tiktok_creative_fatigue, explain_tiktok_anomaly, get_tiktok_audience_insights, analyze_tiktok_geo_performance |
Example
"Show me last 30 days campaign performance with raw data"
{
"campaigns": [
{
"name": "Brand Search - US",
"spend": 1250.00,
"clicks": 3400,
"impressions": 45000,
"conversions": 85,
"cpa": 14.71,
"cpc": 0.37,
"ctr": 0.0756,
"roas": 4.2
}
]
}
Free tier access fix
Free-tier users who previously had a failed or paused Stripe subscription attempt were incorrectly blocked from using MCP tools. This is now fixed — free-tier users are gated only by their usage quota, as intended. TikTok Ads: correct optimization event values
The optimization_event parameter on create_tiktok_campaign, add_tiktok_ad_group, and add_tiktok_ad previously listed invalid values (SUBMIT_FORM, ADD_TO_CART, VIEW_CONTENT, COMPLETE_REGISTRATION, DOWNLOAD, CONTACT, BUTTON_CLICK) that TikTok’s API would reject.Correct values you should use:| Old (invalid) | New (correct) | Meaning |
|---|
SUBMIT_FORM | FORM | Form submission |
ADD_TO_CART | ON_WEB_CART | Add to cart |
VIEW_CONTENT | ON_WEB_DETAIL | View content / product page |
COMPLETE_REGISTRATION | ON_WEB_REGISTER | Registration |
DOWNLOAD | DOWNLOAD_FINISH | App or file download |
CONTACT | CONSULT | Contact / consultation |
BUTTON_CLICK | CLICK_LANDING_PAGE | Landing page click |
COMPLETE_PAYMENT, CONVERSION_LEADS, PAGE_VISIT, PHONE_CONNECT, SEARCH, SUBSCRIBE, INITIATE_ORDER, ON_WEB_SUBSCRIBE.If you were passing the old values and getting TikTok API errors, update to the new values above.TikTok Ads: campaign creation reliability
5 fixes to TikTok campaign creation from production testing.
- Spark Ads now work with
create_tiktok_campaign — creating campaigns with a tiktok_item_id (Spark Ads) or card_id (Carousel) no longer fails with “Unknown error”. Spark and Carousel ads are now created directly without requiring an image upload.
- All TikTok CTAs accepted — previously, only 6 call-to-action values (like LEARN_MORE and SHOP_NOW) were allowed. Now any CTA supported by TikTok works — including CONTACT_US, BOOK_NOW, GET_QUOTE, and others. TikTok validates CTAs server-side.
- Automatic placement fix — campaigns using automatic placement no longer fail with “Missing required field(s): placements.”
- TikTok page URL detection — passing a TikTok page URL (e.g.,
https://tiktok.com/@user/video/123) as a video URL now returns a clear error explaining you should use tiktok_item_id for Spark Ads or provide a direct MP4/MOV link.
- CTA auto-default — when creating an ad with a
landing_page_url but no call_to_action, Adspirer now defaults to LEARN_MORE instead of failing with “External_URL and Call_to_action must exist together.”
When connecting your Meta Ads account, you now see a disclaimer checkbox after entering your email. You must accept the disclaimer — confirming you understand that Adspirer operates independently from Meta’s account enforcement systems — before the Connect button becomes available. Acceptance is recorded for compliance purposes. See Connecting Meta Ads.The Meta Ads page and Security page also now confirm Adspirer has Meta approved Ads Management Standard Access, so users know the app is verified by Meta to use the Marketing API.New users now accept Platform Terms & Conditions as part of onboarding before connecting ad accounts. The terms cover account authorization requirements, rate limit safeguards, platform enforcement policies, financial responsibility, and liability. This replaces the previous per-platform disclaimer prompts with a single, comprehensive agreement.Faster email support
Email support response time improved from 1 business day to 2–4 hours (San Francisco / PST). Reach us at support@adspirer.com.Meta Ads now has 36 tools (up from 21), covering the full campaign lifecycle — from browsing and creation to ad set management, creative rotation, and lead form submissions.
- Ad set & ad management:
add_meta_ad_set, add_meta_ad, update_meta_ad_set, update_meta_ad, list_meta_ad_sets, list_meta_ads
- Campaign management:
list_meta_campaigns, get_meta_campaign_details, duplicate_meta_campaign, resume_meta_campaign
- Creative & lead gen:
create_meta_dco_ad (Dynamic Creative Optimization), get_meta_ad_creatives, list_meta_lead_forms, get_meta_lead_form_submissions
- Account discovery:
list_meta_instagram_accounts, list_meta_pixels
- Analytics:
analyze_meta_wasted_spend, get_meta_audience_insights
Monitoring improvements
create_monitor now lists all 15 supported metrics (roas, ctr, cpc, cpa, cpm, cpv, spend, conversions, impressions, clicks, cost_per_lead, conversion_rate, budget_utilization, video_views, engagement_rate)- Advanced monitoring: AND/OR logic across multiple conditions, consecutive-day triggers, relative thresholds, percentage change detection, campaign-level targeting, and auto-actions (pause campaign, adjust budget)
When adding ad sets to existing Meta campaigns, you can now use the same parameters that were previously only available at campaign creation:
- Lifetime budgets — set
budget_lifetime on individual ad sets
- End dates — set
end_time on ad sets (required when using lifetime budgets)
- Multi-advertiser opt-out — control
multi_advertiser per ad set
- Granular placements — set
publisher_platforms, facebook_positions, and instagram_positions per ad set
Custom conversion tracking fix
custom_conversion_id is now properly decomposed into its underlying pixel and event configuration before being sent to Meta. Previously, passing a custom conversion ID could cause a Meta API error on campaign or ad set creation. Adspirer now automatically resolves the conversion via the Meta API and applies the correct pixel ID and event type.
- Timeout increased from 30 seconds to 90 seconds — accounts with 1,000+ audiences no longer time out
- Audience status now displays as clean labels (“Active”, “Paused”) instead of raw SDK objects
8 new performance analytics tools bring TikTok to parity with Google and Meta for campaign analysis. Total TikTok tools: 4 → 31.| Tool | Description |
|---|
get_tiktok_campaign_performance | Campaign summary with TikTok-specific video and engagement metrics |
get_tiktok_ad_performance | Ad-level analysis with hook rate, video completion, and engagement |
analyze_tiktok_wasted_spend | ROAS-based waste detection with campaign status awareness |
optimize_tiktok_budget | LP-based budget allocation recommendations |
detect_tiktok_creative_fatigue | Hook rate decline as the primary fatigue signal |
explain_tiktok_anomaly | Statistical deviation detection with TikTok-specific metrics |
get_tiktok_audience_insights | Age/gender breakdown with CPA ranking |
analyze_tiktok_geo_performance | Country-level performance analysis |
TikTok now fully available
TikTok Ads is no longer marked “Coming Soon” during onboarding. You can connect your TikTok Ads account directly from the setup flow. TikTok campaign management and creation
19 new tools for full campaign lifecycle management on TikTok — from campaign creation through ad group and ad management, including Spark Ads, Carousel, and APP_PROMOTION support.
list_tiktok_campaigns — List all campaigns with status, objective, and budgetget_tiktok_campaign_details — Detailed campaign infopause_tiktok_campaign / resume_tiktok_campaign — Control campaign statusupdate_tiktok_campaign — Update name, budget, budget modelist_tiktok_ad_groups / pause_tiktok_ad_group / resume_tiktok_ad_group / update_tiktok_ad_group — Full ad group managementlist_tiktok_ads / pause_tiktok_ad / resume_tiktok_ad — Ad-level management
add_tiktok_ad_group — Add ad groups with full targeting to existing campaignsadd_tiktok_ad — Add ads to existing ad groups (image, video, Spark Ads, Carousel)create_tiktok_carousel_card — Create carousel cards from multiple imagesupload_tiktok_images — Upload images to TikTok Asset Librarysearch_tiktok_targeting — Search interests, keywords, regions, languages, action categories, carriers, and device models
- Spark Ads — Boost existing TikTok organic posts as ads
- Carousel Ads — Multi-image carousel format
- APP_PROMOTION — App install campaign objective with app ID configuration
Campaign Budget Optimization (CBO)
TikTok campaigns now support budget_optimize_on for campaign-level budget optimization. TikTok CBO is on by default — set to false to manage budgets per ad group manually.Google Ads fixes
get_campaign_targeting — New tool to view location targeting on existing campaignsget_campaign_structure — Now paginated for large accountsanalyze_search_terms — New raw_report mode shows actual search terms users type into Google- Keyword removal now validates IDs before attempting deletion, with per-keyword error reporting
LinkedIn campaign hierarchy and targeting
Complete overhaul of LinkedIn campaign tools with campaign group support, rollback logic, and 14 new targeting facets.
- Campaign groups —
campaign_group_id and campaign_group_name on all create tools. New add_linkedin_campaign_to_group tool for adding campaigns to existing groups.
- Carousel creatives — New
add_linkedin_carousel_creative tool
- Creative naming —
creative_name field added to all 4 campaign creation tools
- 14 new targeting facets — skills, job functions, interests, degrees, fields of study, employers, groups, age ranges, genders, schools, member behaviors, years of experience, followed companies, and buyer groups. All facets work on both create and update.
- Video discovery — Now finds videos uploaded via LinkedIn Campaign Manager UI, not just API uploads
- Rollback logic — Failed campaigns are automatically archived to prevent duplicates on retry
- Campaign filtering —
list_linkedin_campaigns now filters by campaign group
- Lifetime budgets — Set
budget_lifetime at campaign creation (mutually exclusive with daily budget)
- End dates —
end_time support on campaigns and ad sets
- Custom audiences — New
list_meta_custom_audiences tool for viewing database lists, lookalikes, website, and engagement audiences
- Granular placements — Control
publisher_platforms, facebook_positions, and instagram_positions at campaign creation
- Multi-advertiser opt-out — New
multi_advertiser field to opt out of Meta’s multi-advertiser ads
- Custom conversion tracking — Fixed
custom_conversion_id being silently dropped on image and carousel campaigns
Monitoring
- New
delete_monitor tool — Previously, deleting monitors required knowing about manage_scheduled_task, which AI clients couldn’t discover
Gemini CLI Extension
Adspirer is now available on the Gemini CLI Extensions Gallery. Google’s terminal-based AI tool can now manage your ad campaigns across all 4 platforms.Install
gemini extensions install https://github.com/amekala/ads-mcp
What’s Included
- MCP Server — 100+ tools across Google Ads, Meta Ads, LinkedIn Ads, and TikTok Ads
- 5 Slash Commands —
/adspirer:setup, /adspirer:performance-review, /adspirer:write-ad-copy, /adspirer:wasted-spend, /adspirer:refresh
- OAuth authentication — browser opens automatically on first use
See the full Gemini CLI Setup Guide.Official Claude Plugin
Adspirer is now an official plugin in the Claude plugin marketplace (claude-plugins-official). Available on both Claude Code and Claude Cowork.What Changed
- No more custom marketplace setup. Previously, you had to manually add the
amekala/ads-mcp marketplace before installing. Now just search for “adspirer” in the plugin browser.
- Claude Code: Type
/plugin, search “adspirer”, and install adspirer-ads-agent directly. Or run /plugin install adspirer-ads-agent.
- Claude Cowork: Go to Customize → Browse Plugins and search for “adspirer” — install with one click.
- Plugin page: claude.com/plugins/adspirer-ads-agent
What’s Included
The official plugin bundles everything in a single install:
- MCP Server — 100+ tools across Google Ads, Meta Ads, LinkedIn Ads, and TikTok Ads
- 5 Slash Commands —
/setup, /performance-review, /write-ad-copy, /wasted-spend, /refresh-brand-context
- 2 Skills — Ad campaign management and best practices
- 1 Agent — Performance marketing agent with safety rules
Updated setup guides for Claude Code and Claude Cowork to reflect the simplified installation flow.Lead Gen Campaign Support
Full lead generation support across Google Ads and Meta Ads — performance analysis, wasted spend, and audience tools now handle lead gen campaigns correctly.Google Ads Lead Gen
- Performance analysis, wasted spend, and audience tools now work for campaigns optimized for leads. Previously, tools could crash or show incorrect metrics for lead gen campaigns.
- Conversion metrics now use primary conversions only (
metrics.conversions), matching what you see in the Google Ads UI. Previously, Adspirer reported all conversions including secondary actions, which inflated numbers.
- PMax search themes now correctly apply to the specified asset group, not the first one found.
- All performance tools —
analyze_meta_campaign_performance, analyze_meta_ad_performance, get_meta_wasted_spend, and audience analysis — now support lead gen campaigns (OUTCOME_LEADS optimization).
- CPA calculation now uses the ad set’s optimization event instead of dividing by total conversions. If you’re optimizing for leads, CPA reflects cost-per-lead, not cost-per-all-actions.
- Audience CPA sort order now shows lowest CPA first for lead gen campaigns.
Audience Search Fix
search_audiences now returns results for multi-word queries (e.g., “digital marketing” or “home improvement”). Previously, multi-word searches returned zero results, causing AI clients to fabricate audience IDs.- DemandGen and YouTube tools now validate audience segment IDs against the API instead of accepting AI-generated IDs that don’t exist.
OpenClaw Plugin Fix
Fixed empty-argument bug affecting all 143 tools. The OpenClaw plugin now ships complete input schemas, so tools receive the parameters you provide instead of empty objects.
- Google Ads account list cached in Redis (3-minute TTL) — subsequent tool calls skip the account discovery API call.
- All Google Ads data cache TTLs increased to 10 minutes — repeat queries (e.g., checking campaign performance twice) return instantly from cache.
Google Ads Rate Limit Fix & MCC Reliability
Rate Limit Resolution (P0)
Fixed a critical issue where Google Ads API rate limits (HTTP 429) could block all users — not just the affected account. The system now caches account list responses and includes an emergency recovery endpoint. Users who were seeing “Resource has been exhausted” errors should no longer be affected by other accounts’ API usage.MCC Account Fixes
- Child accounts under MCC (My Client Center) manager accounts now correctly resolve their
login_customer_id during onboarding and tool calls. Previously, some MCC child accounts would fail with “The caller does not have permission” errors.
- Direct (non-MCC) accounts are no longer incorrectly mapped to an MCC manager, which caused “customer not found” errors for users with standalone ad accounts.
login_customer_id is now stored in the database, eliminating a ListAccessibleCustomers API call on every tool call — faster and more reliable.
CPA for Meta campaigns now uses the ad set’s optimization event (e.g., cost per lead, cost per purchase) instead of dividing spend by total conversions. This was especially inaccurate for lead gen campaigns where secondary events inflated the denominator.Google Ads Error Messages
- Centralized error parsing across all 18 Google Ads write operations. Errors now show the specific field and issue (e.g., “headline exceeds 30 characters”) instead of raw API codes.
add_keywords now detects policy violations (trademark, restricted content) and provides specific guidance.update_bid_strategy returns actionable error details when a strategy change fails, instead of just the strategy name.
LinkedIn Improvements
search_linkedin_targeting now uses LinkedIn’s typeahead API for better, faster targeting search results. Facet names (job title, company, industry) are correctly mapped to LinkedIn’s API format.- Fixed parameter mismatches, null handling, and error parsing across LinkedIn Ads tools.
add_meta_ad and add_meta_ad_set now honor the name you provide. Previously, the user-provided name was silently ignored.add_keywords routing fix — calls now use the correct code path with policy violation detection.
OAuth Fix
Fixed a 500 error on the OAuth authorization page. Users connecting via ChatGPT or Claude would see a server error instead of the consent screen.LinkedIn Creatives & Campaign Enhancements
LinkedIn Creatives
- Fixed
list_linkedin_creatives returning empty results for large accounts (22,000+ creatives). Pagination now handles all account sizes correctly.
- Fixed duplicate creatives appearing in results due to pagination overlap.
- Rewrote creative filtering to use LinkedIn’s server-side FINDER API, eliminating timeouts on campaign-level creative lookups.
- Fixed LinkedIn metrics silently dropping to zero, MCP timeout on large result sets, and pagination breaking on no-match scenarios.
Google Ads Campaign Extensions
- Added
MAXIMIZE_CONVERSION_VALUE as a supported bidding strategy for all campaign types.
- Extensions (sitelinks, callouts, snippets) are now added in a single batch operation instead of individually, reducing API calls and errors.
- Automatic retry on
CONCURRENT_MODIFICATION errors when multiple operations target the same campaign.
PMax, Demand Gen & YouTube
Your business logo is now automatically injected into PMax, Demand Gen, and YouTube campaigns during creation — no need to provide it manually if one exists at the account level.Monitoring
Fixed create_monitor using a 30-minute default check interval, which was below the API minimum of 1,440 minutes (24 hours). Monitors now default to a valid interval.Perplexity Computer Support
New AI Client: Perplexity
Adspirer now supports Perplexity as an AI client via MCP connector. Connect Adspirer to Perplexity Computer — the autonomous AI agent — and combine real-time web research with 100+ advertising tools.
- OAuth setup — Add Adspirer as a custom connector in Perplexity Computer → Connectors. OAuth auto-discovery means zero configuration beyond the URL.
- Search + ads — Perplexity’s native web search lets you research competitors and market trends, then immediately act on that research using Adspirer tools. No other client combines real-time search with ad management this seamlessly.
- Perplexity Computer — Max subscribers get autonomous multi-step workflows: research → create → optimize, all from a single prompt.
- Requires Perplexity Pro (20/mo),Max(200/mo), or Enterprise.
Updated all documentation pages, Knowledge Base, and cross-references to include Perplexity as a supported AI client.Audience Targeting Fixes for Demand Gen, YouTube & PMax
Custom Interest Audiences Now Work in Demand Gen & YouTube
Custom interest audiences (custom segments) were not being applied when creating Demand Gen or YouTube campaigns — even though the tool response showed them as set up. Remarketing audiences worked correctly, but custom interest targeting was silently dropped. This is now fixed. All audience segment types (in-market, affinity, custom audiences, and remarketing lists) work consistently across PMax, Demand Gen, and YouTube campaigns.When creating a PMax campaign with only remarketing audiences and no search themes, the system was auto-generating search themes from your ad headlines. If you only ask for audience targeting, search themes will no longer be added automatically.Stable MCP Sessions
No More Intermittent “Invalid Token” Errors
Fixed an issue where some tool calls would randomly fail with “Invalid or expired token” — especially after being idle for a while. Sessions are now resilient to Clerk session expiry. If a session token becomes stale, the system automatically recovers without requiring you to reconnect.Billing & Onboarding UX
Billing Page
- Fixed pricing display and plan comparison layout
- Fixed broken navigation between billing sections
- Improved upgrade/downgrade CTA logic
Onboarding
- Fixed layout and scroll issues on onboarding screens
- Plan tier messaging now accurately reflects current pricing
- Save badge visibility fixed
Scheduled briefs, monitoring alerts, and on-demand reports now work correctly for all platforms — Meta Ads, LinkedIn Ads, and TikTok Ads. Previously, automation tools only worked reliably for Google Ads. Monitors set to track “all platforms” were silently resolving to zero accounts. Persistent MCP Sessions & Faster Auth
No More Frequent Reconnects
MCP access tokens now last 1 week instead of 1 hour. Claude, ChatGPT, Codex, and Cursor sessions stay authenticated much longer — no more “Error occurred during tool execution” after stepping away for an hour.Diagnostic tools (get_usage_status, get_connections_status) remain available even when your quota is exhausted, so you can always check your account status.Added an in-process auth cache that eliminates repeated token verification overhead. Subsequent tool calls in the same session resolve authentication instantly instead of re-verifying on every request.Manus AI Client Support
New setup guide for connecting Adspirer to Manus — the autonomous AI agent. Manus connects via API key authentication with Streamable HTTP transport. Import Adspirer skills directly from GitHub for campaign management workflows.Meta tools now always pass the correct connected ad account ID. Previously, some Meta tools could fail with “No ad account found” even when an account was connected.LinkedIn Ads Fix
Fixed currency formatting for LinkedIn campaign metrics. Campaigns with non-USD currencies now display correctly instead of showing raw API values.Faster Google Ads Account Loading
Google Ads account connections now load with lazy pagination and parallel processing. The connections page loads instantly instead of waiting for all accounts to resolve.Quota Experience & Error Clarity
Completely overhauled how Adspirer communicates quota limits and errors across all AI clients.Usage Warnings Before You Hit the Wall
Tool responses now include a visible usage footer when you’re approaching your quota limit:
- 75%+ usage —
📊 12/15 free calls used (80%) — 3 remaining. Upgrade: ...
- 90%+ usage —
🚨 2 calls remaining! Upgrade now to avoid interruption: ...
Previously, usage warnings were only visible in ChatGPT’s widget. Now they appear on all clients — Claude, Claude Code, Cursor, Codex, and ChatGPT.get_usage_status, get_connections_status, and echo_test now work even when your quota is exhausted. You can always check your usage and connection status regardless of your remaining calls. These tools don’t count against your quota.Clear Error Messages
- Quota exceeded — shows a clean upgrade message with pricing and payment link (previously showed a generic “Error occurred during tool execution” on Claude)
- Session expired — now tells you exactly what happened and how to reconnect (previously showed the same generic error)
- Server errors — include the actual error details and retry guidance
Demand Gen: Multi-Region Ad Groups
Add ad groups to existing Demand Gen campaigns with add_demandgen_ad_group:
- Each ad group can target different locations (e.g., US cities vs India cities vs UAE cities)
- Each ad group can have its own audience signals (in-market + affinity segments)
- Reuse existing account images and YouTube videos across ad groups
- Different creative variations per ad group
- City-level targeting — target specific cities in Meta campaigns with
search_meta_targeting
- Placement-specific creatives — upload different images for Feed, Stories, and Reels placements
- Emoji support — use emoji in Meta ad headlines and descriptions
Adspirer now handles common input mistakes from AI clients automatically:
- JSON strings sent as text instead of objects are auto-parsed
- Integer IDs sent instead of strings are auto-coerced
- Extra whitespace and unknown fields are silently handled
- Works across all 100+ tools — no more validation errors from formatting issues
PMax: Multiple Asset Groups & Bidding Control
- Multiple asset groups per campaign — create campaigns with distinct asset groups for different product lines or audiences
- Bidding strategy control — your explicit bidding choice (Maximize Conversions, Target ROAS, etc.) is now always honored
- Auto-derived search themes — search themes are automatically suggested from your headlines and descriptions
- Post-creation nudge — after creating a PMax campaign, you’re prompted to add search themes and audience signals
Demand Gen Campaign Creation
Full support for Google Demand Gen campaigns — reach users across YouTube, Discover, Gmail, Display, and Maps from a single campaign.Create Demand Gen campaigns with create_demandgen_campaign:
- Multi-asset format — landscape, square, and portrait images with headlines and descriptions
- Video responsive format — YouTube videos with text overlays
- Automatic sitelink, callout, and structured snippet extensions
- Location and language targeting at the campaign level
- All bidding strategies supported: Maximize Clicks, Maximize Conversions, Target CPA, Target ROAS
Audience Targeting
- In-market and affinity audience segments via
search_audiences
- Reuse existing audiences from Google Ads UI
- Per-ad-group audience customization
- Fixed lead form handling for OUTCOME_LEADS and OUTCOME_ENGAGEMENT campaigns
- Fixed Meta page and Instagram account lookup for business accounts
- Wasted spend analysis now respects learning phase and minimum spend thresholds
PMax Search Themes & Audience Signals
Added 7 new tools for managing search themes and audience signals on Google Ads Performance Max campaigns. These PMax-only features give you direct control over how Google’s automation targets search queries and audience segments.| Tool | Type | Description |
|---|
add_pmax_search_themes | Write | Add search themes to guide PMax targeting (max 50 per asset group) |
get_pmax_search_themes | Read | View current search themes on a PMax campaign |
remove_pmax_search_themes | Write | Remove specific search themes |
add_pmax_audience_signal | Write | Add audience signal combining in-market, affinity, custom audiences, and user lists |
get_pmax_audience_signals | Read | View current audience signals |
remove_pmax_audience_signal | Write | Remove an audience signal |
search_audiences | Read | Search for audiences by keyword across all Google Ads audience types |
Search Themes
Short phrases (max 50 per asset group) that tell Google which search queries your PMax campaign should target. They supplement Google’s automated targeting with explicit intent signals. Supports add and remove operations — to update, remove and re-add.Audience Signals
Tell Google which audience segments are most likely to convert. Combine multiple segment types in a single signal:
- In-market audiences — users actively researching products in a category
- Affinity audiences — users with sustained interests and habits
- Custom audiences — account-level custom audience segments
- User lists — first-party data (website visitors, customer lists, CRM uploads)
Only one audience signal per asset group. Signals are suggestions, not hard targeting — Google uses them as starting points and expands.Agent Skills Updated
The Ad Campaign Management skill and Performance Marketing Agent now include search themes and audience signals in the PMax campaign creation workflow (steps 9-10). The agent will automatically recommend search themes based on keyword research and suggest relevant audience segments.Bug Fixes
- Fixed GAQL query syntax for asset group signals (
campaign.id instead of asset_group.campaign.id)
- Fixed audience search returning zero results (replaced case-sensitive GAQL LIKE with client-side filtering +
taxonomy_type enum)
- Added
user_list_ids support for remarketing lists in audience signals
- Increased max search themes from 25 to 50 (Google’s actual limit)
API Key Authentication (Personal Access Tokens)
Adspirer now supports Personal Access Tokens for headless and remote server authentication. Generate API keys from the dashboard and use them on remote servers, Docker containers, and CI/CD pipelines where browser-based OAuth isn’t available.What’s New
- API Key Management UI — Generate, name, and revoke API keys from adspirer.ai/keys
- OpenClaw
--token flag — openclaw adspirer login --token sk_live_... for headless authentication
ADSPIRER_API_KEY env var — Set the environment variable for zero-config server authentication- Tier-based key limits — Free: 2 keys, Plus: 5, Pro: 10, Max: 20
- Key expiration — Optional expiration (30 days, 90 days, 1 year, or never)
- Admin controls — Admin dashboard for API key analytics, per-user key management, and emergency revocation
- Auth method tracking — Tool call logs now track whether each call used OAuth or an API key
Security
- Keys use
sk_live_ prefix for easy identification
- SHA-256 hashed storage — raw tokens never stored server-side
- Instant revocation with audit trail
- Keys cannot be used to create other keys (prevents privilege escalation)
Documentation
Claude Cowork Setup Guide
New documentation page with step-by-step visual guide for connecting Adspirer to Claude Cowork. Includes 9 annotated screenshots covering the full flow: plugin install from marketplace, connector setup, OAuth authentication, and brand folder workspace.Claude Connector Simplified
Claude Chat setup no longer requires manual OAuth configuration. Just paste the URL — Claude auto-discovers the server name and authentication settings.ChatGPT Setup Updated
ChatGPT setup updated to match current UI: new field names, OAuth advanced settings callout, “I understand and want to continue” checkbox, and the new Reference memories and chats preferences screen.LinkedIn Exhaustive Campaign Features
Extended LinkedIn campaign tools with exhaustive targeting and management capabilities. Fixed Google list_campaign_extensions returning incorrect data.Phase 1 database performance improvements for faster query execution across campaign metrics and user analytics.Documentation: Agent Pages & Support
Added 8 new documentation pages:Pricing V2
Updated pricing across all tiers:| Plan | Price | Tool Calls |
|---|
| Free | $0/mo | 15/month |
| Plus | $49/mo | 150/month |
| Pro | $99/mo | 600/month |
| Max | $199/mo | 3,000/month |
- Annual pricing option now available with savings
- Tool call counter resets to 0 on tier upgrade
- Fixed subscription cancellation on upgrade to prevent double-billing
- Stripe webhook handlers now sync quota correctly
MCC/Manager Account Warnings
Connections page now warns users attempting to connect MCC (Google) or Business Manager (Meta) accounts instead of individual ad accounts.OpenClaw Plugin Updates
openclaw adspirer uninstall CLI command added- OAuth retry logic improved
- Skill metadata updated with security section and privacy policy
Added 2 new pages to the Agent Skills section:
- Skill Reference — Complete reference for all 5 Adspirer skills with invocation commands per IDE (Claude Code, Cursor, Codex), step-by-step execution details, and example prompts
- Performance Marketing Agent — How the agent orchestrates skills with brand knowledge, strategy persistence, and memory across sessions
Strategy-Aware Execution
Skills now read STRATEGY.md before executing — a persistent file where strategic decisions (AVOID, PREFER, CONSTRAINT, REQUIRE directives) survive across sessions:
- Campaign creation loads strategy directives at Step 0 and flags conflicts with research results
- Keyword research cross-references results against AVOID/PREFER directives
- Performance review flags “Strategy Drift” when campaigns violate active directives
- Wasted spend prioritizes campaigns violating strategy as waste sources
Agent Documentation Highlights
- Mermaid architecture diagram showing Agent → Context + Strategy + Memory → Skills → Tools → Platforms
- IDE comparison table for agent features across Claude Code, Cursor, and Codex
- Brand Workspace setup flow and context file structure
- Cursor Rules and Codex Safety Rules explained with before/after examples
Asset Discovery & PMax Validation
- Fixed asset discovery across platforms
- YouTube logo upload support for PMax campaigns
- Mandatory extensions enforcement for Google Ads
- PMax logo validation improvements
CLI OAuth Fix
Resolved OAuth failures for CLI clients (Claude Code, Codex). Loopback redirect now correctly routes web vs CLI authentication flows.Cross-Domain Attribution
Added referrer-based UTM fallback for cross-domain tracking between adspirer.com and adspirer.ai.Help & Contact Page
Added in-app Help page with documentation link and contact options.YouTube Ads Campaign Support
Added YouTube Ads campaign creation to the Google Ads toolset. Create video ad campaigns targeting YouTube viewers with budget controls and audience targeting.Launched 8 automation tools:
- Scheduled briefs — automated performance summaries on a recurring schedule
- Performance monitors — alerts when campaigns cross KPI thresholds
- Cross-platform reports — unified reporting across Google, Meta, and LinkedIn
UI Redesign
Mobile dropdown and desktop tab redesign for the main app. Removed trial language from onboarding flow.Documentation Updates
- Enhanced Mintlify components: Frame, Badge, Check, Info, Tooltip across all pages
- Tabbed install methods for Claude Code setup
- Resend-style navbar redesign
- GA4 tracking added to docs site
- 6 new Knowledge Base articles, MCP explainer page, Mermaid workflow diagrams
- UTM tracking on all CTA links
Expanded Onboarding Setup Guides
Onboarding now includes 6 platform-specific setup tabs with step-by-step instructions for connecting Adspirer to each AI client.OpenClaw Plugin v0.3.0
Fixed OpenClaw OAuth client registration and plugin authentication flow.Documentation Site Launch
Launched comprehensive documentation at adspirer.com/docs with 24 pages covering all AI clients, ad platforms, agent skills, and in-depth guides.
- AI client guides for ChatGPT, Claude, Claude Code, Cursor, Codex, OpenClaw, and Windsurf
- Ad platform guides for Google Ads (39 tools), Meta Ads (20 tools), LinkedIn Ads (28 tools), and TikTok Ads (4 tools)
- Agent skills documentation with workflows, tool catalog, and safety rules
- 7 in-depth guides covering keyword research, automation, and strategy
- Auto-generated
llms.txt, llms-full.txt, and skill.md for AI agent discovery
- Contextual sharing to ChatGPT, Claude, Cursor, and VS Code
ChatGPT MCP Connector
Added native MCP connector support for ChatGPT Plus and Pro users. Connect Adspirer directly in ChatGPT Settings with OAuth 2.1 authentication.Claude MCP Connector
Added native MCP connector for Claude Pro, Max, Team, and Enterprise. Includes progress streaming for real-time updates during campaign creation.Codex Agent Support
Added autonomous agent setup for OpenAI Codex with YAML configuration and skill files.OpenClaw Plugin
Released zero-configuration OpenClaw plugin with bundled 14.4KB skill file. Install with openclaw plugins install openclaw-adspirer.ChatGPT MCP Connector Fix
Fixed dynamic client registration to correctly detect Claude vs ChatGPT during OAuth. Claude clients now receive the correct redirect URIs instead of ChatGPT credentials.OpenAI Apps SDK Integration
Added domain verification, OAuth protected resource endpoints, MCP annotations for tool hints, and OpenAI Platform redirect URI for app submission.LinkedIn Campaign Fixes
Fixed LinkedIn campaign creation and update workflows. Resolved API version errors.Conversion Tracking
Set up end-to-end conversion tracking infrastructure for measuring signup-to-paid funnel. Multiple fixes to Google Ads metrics accuracy.Onboarding Revamp
Redesigned onboarding flow with mobile-responsive screens, auto-completion logic, and MCP OAuth gating to prevent onboarding bypass.Enterprise Readiness
Account lifecycle management, metrics pause for inactive accounts, and sign-in/sign-up page revamp.Added Meta video and carousel campaign creation, ad management workflows, and traffic management tools.GTM Cross-Domain Tracking
Added Google Tag Manager (GTM-PQGBFK5Q) to frontend. GA4 sessions now persist across domains via the _gl parameter.LinkedIn Ads Full Integration
Complete LinkedIn Ads integration across 8 phases:
- LinkedIn account setup and OAuth
- Single image sponsored content campaigns
- Campaign performance analytics
- Unified tools for cross-platform management
Added video campaign creation and carousel ad support for Meta Ads.Local Currency Support
Fixed currency handling across all MCP tools and backend APIs. Campaigns now display metrics in the user’s local currency.Smart Metric Collection
Automated background metric collection for historical performance tracking.Asset Reuse & PMax Improvements
- Smart asset discovery and reuse for Performance Max campaigns
- Domain filtering for sitelinks
- Location targeting fix for MCP/ADK PMax campaigns
Account Tier System
Account tier infrastructure with 120-day metric backfill for new users. Accurate daily metrics via segments.date in queries.In-app quota widget and account management tools for ChatGPT users. OAuth improvements for API routes.Custom GPT Support
Added ChatGPT Actions support with OAuth compatibility for Custom GPT configurations.MCP Protocol Improvements
- Progress streaming (MCP 2025-03-26) for real-time updates during campaign creation
- False success message elimination
- OAuth token rotation on reconnect
- JWT expiry fix and performance routing improvements
TikTok Ads Integration
Complete TikTok Ads platform integration:
- OAuth setup and multi-platform architecture
- In-feed video campaign creation
- Image upload and asset validation
- Session handling and location targeting
MCP Server Launch
Initial MCP server deployment at mcp.adspirer.com:
- OAuth 2.1 with PKCE authentication
- Complete PMax campaign creation via ChatGPT
- Modular architecture for multi-platform support
Creative Canvas
Multi-image upload UX improvements and character limit enforcement for PMax campaigns.Adspirer Launch
Initial release with 100+ tools across Google Ads and Meta Ads.
- Keyword research with real CPC data from Google Keyword Planner
- Search and Performance Max campaign creation
- Wasted spend analysis, budget optimization, and ad extensions
- Asset discovery, validation, and ad copy generation
- Image, video, and carousel campaign creation
- Audience targeting and creative fatigue detection
- Placement optimization and performance analysis
Core Features
- OAuth 2.1 authentication with PKCE
- Multi-platform account management
- Agent skills system with SKILL.md instruction files
