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