agent-ads
v0.9.0 stableRust powered CLIWorks with Claude Code

Every Ad Platform.
one CLI.

Read-only access to Meta, Google, TikTok, Pinterest, LinkedIn, and X through one CLI. Built for agents like Claude Code to safely query campaign insights across multiple platforms.

#npm install -g agent-ads
CLI-First

Use it directly.

Run queries straight from your terminal. Every command outputs JSON you can pipe, save, or inspect.

MetaSpend by age and gender
$ agent-ads meta insights query \
  --account act_12345678 \
  --fields spend,impressions,cpc,actions \
  --breakdowns age,gender \
  --date-preset last_7d
GoogleCampaign cost and conversions
$ agent-ads google gaql search \
  --customer-id 123-456-7890 \
  --query "SELECT campaign.name,
    metrics.cost_micros, metrics.conversions
    FROM campaign
    WHERE segments.date DURING LAST_30_DAYS"
TikTokCampaign-level CPA
$ agent-ads tiktok insights query \
  --advertiser-id 7012345678901234 \
  --data-level AUCTION_CAMPAIGN \
  --dimensions campaign_id \
  --metrics spend,conversion,cost_per_conversion
PinterestSpend by gender and age
$ agent-ads pinterest targeting-analytics query \
  --ad-account-id 549764106178 \
  --targeting-type GENDER,AGE_BUCKET \
  --columns SPEND,CLICKTHROUGH_1
LinkedInDaily campaign clicks and spend
$ agent-ads linkedin analytics query \
  --finder statistics \
  --account-id 1234567890 \
  --pivot CAMPAIGN \
  --time-granularity DAILY \
  --since 2026-03-01 \
  --until 2026-03-16 \
  --fields impressions,clicks,costInLocalCurrency
XCampaign engagement and billing
$ agent-ads x analytics query \
  --account-id 18ce54d4x5t \
  --entity campaign \
  --entity-id c1234567890 \
  --start-time 2026-03-01T00:00:00Z \
  --end-time 2026-03-07T00:00:00Z \
  --granularity day \
  --placement all-on-twitter \
  --metric-group engagement,billing
Agent Integration

Better with an agent.

agent-ads is built to work with coding agents like Claude Code. Ask questions in plain English — your agent picks the right command.

Meta Insights

“Break down last week's Meta spend by age and gender”

$ agent-ads meta insights query \
  --account act_12345678 \
  --fields spend,cpc,actions \
  --breakdowns age,gender \
  --date-preset last_7d
Google GAQL

“Which Google campaigns spent the most last month?”

$ agent-ads google gaql search \
  --customer-id 123-456-7890 \
  --query "SELECT campaign.name,
    metrics.cost_micros
    FROM campaign
    WHERE segments.date DURING LAST_30_DAYS
    ORDER BY metrics.cost_micros DESC"
TikTok Performance

“Show me cost per conversion for each TikTok campaign”

$ agent-ads tiktok insights query \
  --advertiser-id 7012345678901234 \
  --data-level AUCTION_CAMPAIGN \
  --metrics spend,conversion,cost_per_conversion
Pinterest Conversions

“How are my Pinterest conversions trending this week?”

$ agent-ads pinterest analytics query \
  --ad-account-id 549764106178 \
  --columns TOTAL_CONVERSIONS,TOTAL_PAGE_VISIT \
  --start-date 2026-03-15 --end-date 2026-03-22
LinkedIn Reporting

“Show daily LinkedIn campaign clicks and spend for last week”

$ agent-ads linkedin analytics query \
  --finder statistics \
  --account-id 1234567890 \
  --pivot CAMPAIGN \
  --time-granularity DAILY \
  --since 2026-03-15 \
  --until 2026-03-22 \
  --fields impressions,clicks,costInLocalCurrency
X Analytics

“Show last week's X campaign engagement and billing metrics”

$ agent-ads x analytics query \
  --account-id 18ce54d4x5t \
  --entity campaign \
  --entity-id c1234567890 \
  --start-time 2026-03-15T00:00:00Z \
  --end-time 2026-03-22T00:00:00Z \
  --granularity day \
  --placement all-on-twitter \
  --metric-group engagement,billing
Claude Code Skill

Install the skill.

agent-ads ships as a skill for Claude Code. Install the CLI, add the skill, and your agent can query any supported ad platform on your behalf.

$ npx skills add https://github.com/bengoism/agent-ads --skill agent-ads
Supported Platforms

Supported Platforms

Native integration with world-class advertising APIs.

Meta

Full Graph API integration. Fetch creative assets, campaign stats, and breakdown insights.

CampaignsCreatives

Google

Support for Google Ads Query Language (GAQL). Stream large report batches to local disk.

GAQLIRC

TikTok

Query business API for performance data. Optimized for high-volume creative asset retrieval.

PerformanceAssets

Pinterest

Ad accounts, synchronous analytics, targeting analytics, audiences, and async report runs for Pinterest Ads API.

AnalyticsReport runsAudiences

LinkedIn

Ad accounts, campaign groups, campaigns, creatives, and adAnalytics reporting for LinkedIn Marketing API.

ReportingCreativesCampaign groups

X

Inspect X Ads accounts, campaign objects, promoted tweets, and synchronous or async analytics.

AnalyticsPromoted tweetsOAuth 1.0a