agent-ads
v0.9.0 stableRust powered CLIProvider-first commands

Every Ad Platform.
one CLI.

Read-only access to Meta, Google, TikTok, Pinterest, LinkedIn, and X through one CLI. Keep each command explicit with agent-ads <provider> <command>.

#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
Skill

Install the skill.

Install the public skill if you want your agent to keep provider routing explicit and jump straight to the right reference guide.

npx skills add bengoism/agent-ads
Supported Providers

Supported Providers

Read-only coverage for each supported ad provider.

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