snapchat-ads-cli

name

snapchat-ads-cli

description

Snapchat Ads data analysis and reporting via snapchat-ads-cli. Use when the user wants to check Snapchat ad performance, pull campaign/ad squad/ad stats, explore ad account structure, inspect creatives, analyze audiences, debug delivery issues, estimate bids and audience size, manage AR lenses, or retrieve billing information. Triggers: "Snapchat Ads", "Snap Ads", "snapchat ad performance", "snapchat campaign stats", "snapchat ad spend", "snapchat pixel", "snapchat audience", "snapchat creatives", "snapchat ad account", "ad squad performance", "snapchat delivery status", "snapchat lenses", "snapchat bid estimate", "snapchat audience size", "snapchat billing".

Snapchat Ads CLI Skill

You have access to snapchat-ads-cli, a read-only CLI for the Snapchat Marketing API (v1). Use it to query organizations and ad accounts, pull performance stats with attribution windows, inspect creatives, debug delivery issues, estimate bids and audience sizes, manage AR lenses, and retrieve billing information.

Quick start

# Check if the CLI is available
snapchat-ads-cli --help

# List organizations
snapchat-ads-cli organizations

# List ad accounts for an organization
snapchat-ads-cli accounts ORG_ID

If the CLI is not installed, install it:

npm install -g snapchat-ads-cli

Authentication

The CLI requires a Snapchat OAuth2 access token. Credentials are resolved in this order:

1. --credentials <path> flag (per-command)
2. Environment variable: SNAPCHAT_ADS_ACCESS_TOKEN
3. Auto-detected file: ~/.config/snapchat-ads-cli/credentials.json

The credentials file format:

{
  "access_token": "YOUR_ACCESS_TOKEN"
}

Before running any command, verify credentials are configured by running snapchat-ads-cli organizations. If it fails with a credentials error, ask the user to set up authentication.

Entity hierarchy

Organization
 +-- Ad Account
      +-- Campaign
      |    +-- Ad Squad (= ad group)
      |         +-- Ad -> Creative
      +-- Creative (managed at ad account level)

Most list commands require the parent entity ID. Start with organizations to find the org, then accounts <org-id> to find ad accounts, and drill down from there.

Monetary values

Snapchat uses micro-currency: 1 dollar = 1,000,000 micro. All spend values in stats and budgets are in micro-currency. Divide by 1,000,000 to get the actual dollar amount.

Output format

All commands output pretty-printed JSON by default. Use --format compact for single-line JSON (useful for piping).

Listing commands that support pagination use --limit <n> to control page size (default 50).

Commands reference

Organization discovery

# List all organizations the user has access to
snapchat-ads-cli organizations

# Get a specific organization
snapchat-ads-cli organization ORG_ID

Note: organizations does not support --limit pagination. organization fetches a single entity by ID.

Ad accounts

# List ad accounts for an organization
snapchat-ads-cli accounts ORG_ID
snapchat-ads-cli accounts ORG_ID --limit 100

# Get a specific ad account
snapchat-ads-cli account ACCOUNT_ID

Options for accounts: --limit <n> (default 50)

Funding & billing centers

# List funding sources for an organization
snapchat-ads-cli funding-sources ORG_ID
snapchat-ads-cli funding-sources ORG_ID --limit 100

# List billing centers for an organization
snapchat-ads-cli billing-centers ORG_ID
snapchat-ads-cli billing-centers ORG_ID --limit 100

Both support --limit <n> (default 50).

Campaigns

# List campaigns for an ad account
snapchat-ads-cli campaigns ACCOUNT_ID
snapchat-ads-cli campaigns ACCOUNT_ID --limit 100

# Get a specific campaign
snapchat-ads-cli campaign CAMPAIGN_ID

Options for campaigns: --limit <n> (default 50)

Ad squads

# List ad squads for a campaign
snapchat-ads-cli adsquads CAMPAIGN_ID
snapchat-ads-cli adsquads CAMPAIGN_ID --limit 100

# Get a specific ad squad
snapchat-ads-cli adsquad ADSQUAD_ID

Options for adsquads: --limit <n> (default 50)

Ads

# List ads for an ad squad
snapchat-ads-cli ads ADSQUAD_ID
snapchat-ads-cli ads ADSQUAD_ID --limit 100

# Get a specific ad
snapchat-ads-cli ad AD_ID

Options for ads: --limit <n> (default 50)

Creatives

# List creatives for an ad account
snapchat-ads-cli creatives ACCOUNT_ID
snapchat-ads-cli creatives ACCOUNT_ID --limit 100

# Get a specific creative
snapchat-ads-cli creative CREATIVE_ID

Options for creatives: --limit <n> (default 50)

Audiences & pixel

# List custom audience segments for an ad account
snapchat-ads-cli audiences ACCOUNT_ID
snapchat-ads-cli audiences ACCOUNT_ID --limit 100

# Get a specific audience segment
snapchat-ads-cli audience SEGMENT_ID

# Get the Snap Pixel for an ad account
snapchat-ads-cli pixel ACCOUNT_ID

Options for audiences: --limit <n> (default 50). audience and pixel do not support --limit.

Members & roles

# List members of an organization
snapchat-ads-cli members ORG_ID
snapchat-ads-cli members ORG_ID --limit 100

# List roles for an organization
snapchat-ads-cli roles ORG_ID
snapchat-ads-cli roles ORG_ID --limit 100

Both support --limit <n> (default 50).

Billing

# List invoices for an ad account
snapchat-ads-cli invoices ACCOUNT_ID
snapchat-ads-cli invoices ACCOUNT_ID --limit 100

# List transactions for an organization
snapchat-ads-cli transactions ORG_ID
snapchat-ads-cli transactions ORG_ID --limit 100

Both support --limit <n> (default 50).

Performance stats

Stats commands work on campaigns, ad squads, and ads. All three share the same options.

# Campaign stats (daily granularity)
snapchat-ads-cli campaign-stats CAMPAIGN_ID \
  --start-time 2026-03-01T00:00:00.000Z \
  --end-time 2026-03-15T00:00:00.000Z \
  --granularity DAY

# Ad squad stats (total granularity, default)
snapchat-ads-cli adsquad-stats ADSQUAD_ID \
  --start-time 2026-03-01T00:00:00.000Z \
  --end-time 2026-03-15T00:00:00.000Z

# Ad stats (hourly granularity with attribution windows)
snapchat-ads-cli ad-stats AD_ID \
  --start-time 2026-03-01T00:00:00.000Z \
  --end-time 2026-03-15T00:00:00.000Z \
  --granularity HOUR \
  --swipe-up-attribution-window 28_DAY \
  --view-attribution-window 7_DAY

# Campaign stats with specific fields and conversion sources
snapchat-ads-cli campaign-stats CAMPAIGN_ID \
  --start-time 2026-03-01T00:00:00.000Z \
  --end-time 2026-03-15T00:00:00.000Z \
  --fields spend,impressions,swipes \
  --conversion-source-types web,app

Stats options

Option	Required	Description	Default
--start-time <time>	Yes	Start time in ISO 8601 format	--
--end-time <time>	Yes	End time in ISO 8601 format	--
--granularity <gran>	No	TOTAL, DAY, or HOUR	TOTAL
--fields <fields>	No	Stat fields to include (comma-separated)	all default fields
--swipe-up-attribution-window <window>	No	1_DAY, 7_DAY, 28_DAY	--
--view-attribution-window <window>	No	1_HOUR, 3_HOUR, 6_HOUR, 1_DAY, 7_DAY, 28_DAY	--
--conversion-source-types <types>	No	Comma-separated: web, app, total	--

The CLI passes --fields values directly to the Snapchat Marketing API without validation. When --fields is omitted, the API returns its default set. Use --fields spend,impressions,swipes to request specific fields. Refer to the Snapchat Measurement API docs for the full list of available fields.

Delivery debugging

# Get delivery status for a campaign
snapchat-ads-cli delivery-status campaigns CAMPAIGN_ID

# Get delivery status for an ad squad
snapchat-ads-cli delivery-status adsquads ADSQUAD_ID

# Get delivery status for an ad
snapchat-ads-cli delivery-status ads AD_ID

The entity-type argument must be one of: campaigns, adsquads, ads.

Targeting & insights

# Get targeting insights for an ad account (POST request)
snapchat-ads-cli audience-insights ACCOUNT_ID

# List custom conversions for a pixel
snapchat-ads-cli custom-conversions PIXEL_ID
snapchat-ads-cli custom-conversions PIXEL_ID --limit 100

Options for custom-conversions: --limit <n> (default 50). audience-insights does not support --limit.

Audit logs

# List external changelogs for an entity
snapchat-ads-cli audit-logs campaigns CAMPAIGN_ID
snapchat-ads-cli audit-logs adsquads ADSQUAD_ID
snapchat-ads-cli audit-logs ads AD_ID
snapchat-ads-cli audit-logs campaigns CAMPAIGN_ID --limit 100

The entity-type argument is passed directly to the API path. Common values: organizations, adaccounts, campaigns, adsquads, ads, creatives. Supports --limit <n> (default 50).

Media & lenses

# List media files for an ad account
snapchat-ads-cli media ACCOUNT_ID
snapchat-ads-cli media ACCOUNT_ID --limit 100

# List AR lenses for an organization
snapchat-ads-cli lenses ORG_ID
snapchat-ads-cli lenses ORG_ID --limit 100

Both support --limit <n> (default 50).

Estimates

# Get bid estimate for an ad account
snapchat-ads-cli bid-estimate ACCOUNT_ID --optimization-goal IMPRESSIONS

# Get estimated audience size for an ad account
snapchat-ads-cli audience-size ACCOUNT_ID

# Get event quality scores for a pixel
snapchat-ads-cli signal-readiness PIXEL_ID

# Get ad squad outcome configuration
snapchat-ads-cli ad-outcomes ADSQUAD_ID

bid-estimate has one optional option: --optimization-goal <goal> (e.g., IMPRESSIONS, SWIPES, APP_INSTALLS, VIDEO_VIEWS). The other estimate commands have no additional options.

Workflow guidance

When the user asks for a quick overview

1. Run snapchat-ads-cli organizations to find accessible organizations
2. Run snapchat-ads-cli accounts ORG_ID to list ad accounts
3. Use campaign-stats with a recent date range for a performance snapshot
4. Remember: divide all monetary values by 1,000,000 (micro-currency)

When the user asks for deep analysis

1. Start with campaign-stats at --granularity TOTAL for overall performance
2. Switch to --granularity DAY to spot daily trends
3. Drill down with adsquad-stats and ad-stats for underperforming entities
4. Use --fields to focus on specific metrics
5. Add attribution windows (--swipe-up-attribution-window, --view-attribution-window) for conversion analysis
6. Cross-reference with creatives to review creative content

When the user asks about delivery issues

1. Run delivery-status campaigns CAMPAIGN_ID to check campaign delivery
2. Drill into delivery-status adsquads ADSQUAD_ID for ad squad level issues
3. Check delivery-status ads AD_ID for ad-level problems
4. Review the ad squad and ad configurations with adsquad and ad

When the user asks about audiences

1. Use audiences ACCOUNT_ID to list custom audience segments
2. Use audience-size ACCOUNT_ID for reach estimation
3. Use audience-insights ACCOUNT_ID for targeting insights
4. Use pixel ACCOUNT_ID to check pixel setup
5. Use custom-conversions PIXEL_ID to review custom conversion rules

When the user asks about conversion tracking

1. Run pixel ACCOUNT_ID to find the Snap Pixel
2. Use signal-readiness PIXEL_ID to check event quality scores
3. Use custom-conversions PIXEL_ID to list custom conversion rules
4. Pull stats with --conversion-source-types web,app and attribution windows

When the user asks about billing

1. Run invoices ACCOUNT_ID to list invoices for an ad account
2. Run transactions ORG_ID to list transactions for an organization
3. Run funding-sources ORG_ID to check funding sources
4. Run billing-centers ORG_ID to list billing centers

Error handling

• Authentication errors -- ask the user to verify their access token; check that SNAPCHAT_ADS_ACCESS_TOKEN is set, --credentials points to a valid file, or ~/.config/snapchat-ads-cli/credentials.json exists
• Empty results -- check that the parent entity ID is correct and that the entity has children (e.g., the ad account has campaigns)
• Missing stats -- verify the date range covers a period when the entity was active; check that --start-time and --end-time are in ISO 8601 format
• Delivery status issues -- use delivery-status to diagnose why an entity is not serving
• Invalid entity-type -- for delivery-status use campaigns, adsquads, or ads; for audit-logs use campaigns, adsquads, ads, or creatives.

All errors are written to stderr as JSON with an error field and a non-zero exit code:

{"error": "Unauthorized"}

API documentation references

• snapchat-ads-cli documentation
• Snapchat Marketing API overview
• Authentication
• Organizations
• Ad Accounts
• Campaigns
• Ad Squads
• Ads
• Creatives
• Audience Segments
• Measurement / Stats
• Media
• Bid Estimates
• Invoices
• Audit Logs
• Members & Roles