Pinterest Ads CLI Skill

You have access to pinterest-ads-cli, a read-only CLI for the Pinterest REST API v5. Use it to query ad accounts, pull performance analytics, inspect campaigns and ads, analyze audiences, browse product catalogs, discover trending search terms, and review billing across Pinterest advertising.

Quick start

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

# List accessible ad accounts
pinterest-ads-cli accounts

# Get a specific ad account
pinterest-ads-cli account 123456789

If the CLI is not installed, install it:

npm install -g pinterest-ads-cli

Authentication

The CLI requires a Pinterest OAuth2 access token. Most commands need the ads:read scope. Additional scopes may be required for specific commands: catalogs:read for catalog commands, user_accounts:read for trends, and billing:read for billing data. Credentials are resolved in this order:

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

The credentials JSON file format:

{
  "access_token": "YOUR_ACCESS_TOKEN"
}

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

Entity hierarchy

Ad Account
 +-- Campaign
 |    +-- Ad Group
 |         +-- Ad
 |         +-- Keyword
 +-- Audience
 +-- Customer List
 +-- Conversion Tag
 +-- Billing Profile
 +-- Order Line
 +-- Lead Form

Catalog resources (catalogs, feeds, product groups) are not scoped to an ad account and are accessed at the top level.

Monetary values

Pinterest analytics returns monetary metrics in micro-currency units (1/1,000,000 of the ad account's currency). Fields like SPEND_IN_MICRO_DOLLAR, CPC_IN_MICRO_DOLLAR, and ECPM_IN_MICRO_DOLLAR must be divided by 1,000,000 to get the actual amount. Despite the DOLLAR suffix in field names, values are in the ad account's configured currency (USD, GBP, EUR, etc.).

Example: SPEND_IN_MICRO_DOLLAR: 5000000 means 5.00 in the account's currency.

Output format

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

Pagination uses cursor-based --bookmark values returned in the response. Pass the bookmark from a previous response to get the next page.

Commands reference

Account discovery

# List ad accounts
pinterest-ads-cli accounts
pinterest-ads-cli accounts --page-size 50

# Get a specific ad account
pinterest-ads-cli account 123456789

accounts

List ad accounts the user has access to.

account