Spotify Ads CLI Skill

You have access to spotify-ads-cli, a read-only CLI for the Spotify Ads API (v3). Use it to query businesses and ad accounts, pull aggregate and insight reports, create async CSV reports, estimate audience sizes and bid ranges, explore targeting options, manage audiences and assets, and track measurement pixels and datasets.

Quick start

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

# List businesses for the current user
spotify-ads-cli businesses

# List ad accounts for a business
spotify-ads-cli ad-accounts biz_abc123

If the CLI is not installed, install it:

npm install -g spotify-ads-cli

Authentication

The CLI requires a Spotify OAuth access token from a Spotify Developer App with Ads API access. Credentials are resolved in this order:

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

The credentials file format:

{
  "access_token": "your_access_token"
}

Before running any command, verify credentials are configured by running spotify-ads-cli businesses. If it fails with a credentials error, ask the user to set up authentication. To request Ads API access, contact [email protected].

Entity hierarchy

Business
 +-- Ad Account
      +-- Campaign
      |    +-- Ad Set (targeting, budget, schedule)
      |         +-- Ad (creative)
      +-- Asset (audio, images)
      +-- Audience (custom, lookalike)
      +-- Pixel / Dataset (measurement)

Monetary values

Spotify uses micros for input parameters: 1 dollar = 1,000,000 micros. Bid amounts (bid_micro_amount) and budgets (budget_micro_amount) are in micros -- divide by 1,000,000 for the actual amount. Reporting endpoints (aggregate and insight reports) return spend in standard currency units (no conversion needed).

Output format

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

Listing commands use offset-based pagination with --offset and --limit (max 50). Reporting commands use continuation tokens via --continuation-token.

Commands reference

Account discovery

# List businesses for the current user
spotify-ads-cli businesses

# Get a specific business
spotify-ads-cli business biz_abc123

# List ad accounts for a business (supports pagination)
spotify-ads-cli ad-accounts biz_abc123
spotify-ads-cli ad-accounts biz_abc123 --offset 0 --limit 50

# Get a specific ad account
spotify-ads-cli ad-account acc_abc123

Campaign hierarchy

# List campaigns for an ad account (filter by status: ACTIVE, PAUSED, COMPLETED, DRAFT)
spotify-ads-cli campaigns acc_abc123
spotify-ads-cli campaigns acc_abc123 --status ACTIVE
spotify-ads-cli campaigns acc_abc123 --offset 0 --limit 25

# Get a specific campaign
spotify-ads-cli campaign camp_abc123