Pinterest Ads CLI

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 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.

| Option | Description | Default | |--------|-------------|---------| | --page-size | Results per page (max 250) | 25 | | --bookmark | Pagination cursor | -- |

#### account

Get details of a specific ad account. Takes the ad account ID as a required argument.

pinterest-ads-cli account 

Campaign hierarchy

# List campaigns
pinterest-ads-cli campaigns 123456789
pinterest-ads-cli campaigns 123456789 --entity-statuses ACTIVE,PAUSED
pinterest-ads-cli campaigns 123456789 --order DESCENDING --page-size 100
List ad groups
pinterest-ads-cli adgroups 123456789
pinterest-ads-cli adgroups 123456789 --campaign-ids campaign_1,campaign_2
List ads
pinterest-ads-cli ads 123456789
pinterest-ads-cli ads 123456789 --campaign-ids campaign_1 --entity-statuses ACTIVE

#### campaigns

List campaigns for an ad account.

pinterest-ads-cli campaigns 

| Option | Description | Default | |--------|-------------|---------| | --campaign-ids | Filter by campaign IDs (comma-separated) | -- | | --entity-statuses | Filter by status (comma-separated, e.g. ACTIVE,PAUSED) | -- | | --page-size | Results per page (max 250) | 25 | | --order | Sort order: ASCENDING or DESCENDING | -- | | --bookmark | Pagination cursor | -- |

#### adgroups

List ad groups for an ad account.

pinterest-ads-cli adgroups 

| Option | Description | Default | |--------|-------------|---------| | --campaign-ids | Filter by campaign IDs (comma-separated) | -- | | --ad-group-ids | Filter by ad group IDs (comma-separated) | -- | | --entity-statuses | Filter by status (comma-separated) | -- | | --page-size | Results per page (max 250) | 25 | | --order | Sort order: ASCENDING or DESCENDING | -- | | --bookmark | Pagination cursor | -- |

#### ads

List ads for an ad account.

pinterest-ads-cli ads 

| Option | Description | Default | |--------|-------------|---------| | --campaign-ids | Filter by campaign IDs (comma-separated) | -- | | --ad-group-ids | Filter by ad group IDs (comma-separated) | -- | | --ad-ids | Filter by ad IDs (comma-separated) | -- | | --entity-statuses | Filter by status (comma-separated) | -- | | --page-size | Results per page (max 250) | 25 | | --order | Sort order: ASCENDING or DESCENDING | -- | | --bookmark | Pagination cursor | -- |

Keywords

# List keywords for an ad account
pinterest-ads-cli keywords 123456789
pinterest-ads-cli keywords 123456789 --ad-group-id adgroup_1

#### keywords

List targeting keywords for an ad account.

pinterest-ads-cli keywords 

| Option | Description | Default | |--------|-------------|---------| | --ad-group-id | Filter by ad group ID | -- | | --page-size | Results per page (max 250) | 25 | | --bookmark | Pagination cursor | -- |

Audiences

# List audiences
pinterest-ads-cli audiences 123456789
List customer lists
pinterest-ads-cli customer-lists 123456789

#### audiences

List audiences for an ad account.

pinterest-ads-cli audiences 

| Option | Description | Default | |--------|-------------|---------| | --page-size | Results per page (max 250) | 25 | | --order | Sort order: ASCENDING or DESCENDING | -- | | --bookmark | Pagination cursor | -- |

#### customer-lists

List customer lists for an ad account.

pinterest-ads-cli customer-lists 

| Option | Description | Default | |--------|-------------|---------| | --page-size | Results per page (max 250) | 25 | | --order | Sort order: ASCENDING or DESCENDING | -- | | --bookmark | Pagination cursor | -- |

Conversion tracking

# List all conversion tags
pinterest-ads-cli conversion-tags 123456789
Get a specific conversion tag
pinterest-ads-cli conversion-tag 123456789 tag_abc

#### conversion-tags

List conversion tags for an ad account. No pagination options -- returns all tags.

pinterest-ads-cli conversion-tags 

#### conversion-tag

Get a specific conversion tag.

pinterest-ads-cli conversion-tag  

Billing

# List billing profiles
pinterest-ads-cli billing-profiles 123456789
pinterest-ads-cli billing-profiles 123456789 --is-active
List order lines
pinterest-ads-cli order-lines 123456789
Get a specific order line
pinterest-ads-cli order-line 123456789 orderline_abc

#### billing-profiles

List billing profiles for an ad account.

pinterest-ads-cli billing-profiles 

| Option | Description | Default | |--------|-------------|---------| | --is-active | Only return active profiles (boolean flag) | false | | --page-size | Results per page (max 250) | 25 | | --bookmark | Pagination cursor | -- |

#### order-lines

List order lines for an ad account.

pinterest-ads-cli order-lines 

| Option | Description | Default | |--------|-------------|---------| | --page-size | Results per page (max 250) | 25 | | --order | Sort order: ASCENDING or DESCENDING | -- | | --bookmark | Pagination cursor | -- |

#### order-line

Get a specific order line.

pinterest-ads-cli order-line  

Lead forms

# List lead forms
pinterest-ads-cli lead-forms 123456789
Get a specific lead form
pinterest-ads-cli lead-form 123456789 leadform_abc

#### lead-forms

List lead generation forms for an ad account.

pinterest-ads-cli lead-forms 

| Option | Description | Default | |--------|-------------|---------| | --page-size | Results per page (max 250) | 25 | | --order | Sort order: ASCENDING or DESCENDING | -- | | --bookmark | Pagination cursor | -- |

#### lead-form

Get a specific lead form.

pinterest-ads-cli lead-form  

Catalogs (Pinterest Shopping)

Catalog commands are not scoped to an ad account.

# List catalogs
pinterest-ads-cli catalogs
List catalog feeds
pinterest-ads-cli feeds
List catalog product groups
pinterest-ads-cli product-groups

#### catalogs

List catalogs.

| Option | Description | Default | |--------|-------------|---------| | --page-size | Results per page (max 250) | 25 | | --bookmark | Pagination cursor | -- |

#### feeds

List catalog feeds.

| Option | Description | Default | |--------|-------------|---------| | --page-size | Results per page (max 250) | 25 | | --bookmark | Pagination cursor | -- |

#### product-groups

List catalog product groups.

| Option | Description | Default | |--------|-------------|---------| | --page-size | Results per page (max 250) | 25 | | --bookmark | Pagination cursor | -- |

Trends

Discover trending search terms by region. Does not require an ad account ID.

# Growing trends in the US
pinterest-ads-cli trends US --trend-type growing
Monthly trends filtered by interest
pinterest-ads-cli trends US --trend-type monthly --interests fashion --limit 20
Seasonal trends filtered by demographics
pinterest-ads-cli trends GB --trend-type seasonal --genders female --ages 25-34

#### trends

Get trending search terms for a region.

pinterest-ads-cli trends 

| Option | Description | Default | |--------|-------------|---------| | --trend-type | Required. Trend type: growing, monthly, yearly, seasonal | -- | | --interests | Filter by interests (comma-separated) | -- | | --genders | Filter by genders (comma-separated) | -- | | --ages | Filter by age groups (comma-separated) | -- | | --limit | Number of results | 50 |

Note: the trends command does not support --bookmark pagination. Use --limit to control the number of results.

Analytics

Analytics commands pull performance metrics for ad accounts, campaigns, ad groups, and ads. All analytics commands require --start-date, --end-date, and --columns.

# Account-level analytics
pinterest-ads-cli analytics 123456789 \
  --start-date 2026-03-01 \
  --end-date 2026-03-15 \
  --columns SPEND_IN_MICRO_DOLLAR,IMPRESSION_1,CLICKTHROUGH_1 \
  --granularity DAY
Campaign-level analytics
pinterest-ads-cli campaign-analytics 123456789 \
  --campaign-ids campaign_1,campaign_2 \
  --start-date 2026-03-01 \
  --end-date 2026-03-15 \
  --columns SPEND_IN_MICRO_DOLLAR,IMPRESSION_1,CLICKTHROUGH_1
Ad group-level analytics
pinterest-ads-cli adgroup-analytics 123456789 \
  --ad-group-ids adgroup_1 \
  --start-date 2026-03-01 \
  --end-date 2026-03-15 \
  --columns SPEND_IN_MICRO_DOLLAR,IMPRESSION_1
Ad-level analytics
pinterest-ads-cli ad-analytics 123456789 \
  --ad-ids ad_1 \
  --start-date 2026-03-01 \
  --end-date 2026-03-15 \
  --columns SPEND_IN_MICRO_DOLLAR,IMPRESSION_1

#### analytics

Get ad account-level analytics.

pinterest-ads-cli analytics 

| Option | Description | Default | |--------|-------------|---------| | --start-date | Required. Start date (YYYY-MM-DD) | -- | | --end-date | Required. End date (YYYY-MM-DD) | -- | | --columns | Required. Metrics (comma-separated) | -- | | --granularity | TOTAL, DAY, HOUR, WEEK, MONTH | DAY | | --click-window-days | Click attribution window: 0, 1, 7, 14, 30, 60 | -- | | --view-window-days | View attribution window: 0, 1, 7, 14, 30, 60 | -- |

#### campaign-analytics

Get campaign-level analytics.

pinterest-ads-cli campaign-analytics 

| Option | Description | Default | |--------|-------------|---------| | --campaign-ids | Required. Campaign IDs (comma-separated) | -- | | --start-date | Required. Start date (YYYY-MM-DD) | -- | | --end-date | Required. End date (YYYY-MM-DD) | -- | | --columns | Required. Metrics (comma-separated) | -- | | --granularity | TOTAL, DAY, HOUR, WEEK, MONTH | DAY |

#### adgroup-analytics

Get ad group-level analytics.

pinterest-ads-cli adgroup-analytics 

| Option | Description | Default | |--------|-------------|---------| | --ad-group-ids | Required. Ad group IDs (comma-separated) | -- | | --start-date | Required. Start date (YYYY-MM-DD) | -- | | --end-date | Required. End date (YYYY-MM-DD) | -- | | --columns | Required. Metrics (comma-separated) | -- | | --granularity | TOTAL, DAY, HOUR, WEEK, MONTH | DAY |

#### ad-analytics

Get ad-level analytics.

pinterest-ads-cli ad-analytics 

| Option | Description | Default | |--------|-------------|---------| | --ad-ids | Required. Ad IDs (comma-separated) | -- | | --start-date | Required. Start date (YYYY-MM-DD) | -- | | --end-date | Required. End date (YYYY-MM-DD) | -- | | --columns | Required. Metrics (comma-separated) | -- | | --granularity | TOTAL, DAY, HOUR, WEEK, MONTH | DAY |

#### Common analytics columns

Columns documented in README: SPEND_IN_MICRO_DOLLAR, IMPRESSION_1, CLICKTHROUGH_1, CPC_IN_MICRO_DOLLAR, ECPM_IN_MICRO_DOLLAR, CTR, TOTAL_CONVERSIONS

The CLI passes column names directly to the Pinterest API v5 without validation. Refer to the Pinterest Analytics API docs for all available columns (e.g., video metrics, engagement metrics, web conversion metrics). Column names use uppercase with underscores (e.g., VIDEO_MRC_VIEWS_1, TOTAL_ENGAGEMENT). Monetary columns end in _IN_MICRO_DOLLAR -- divide by 1,000,000.

#### Attribution windows

Only the account-level analytics command supports attribution window options (--click-window-days and --view-window-days). The campaign, ad group, and ad-level analytics commands do not support these options in the CLI (this is a CLI limitation; the Pinterest API supports attribution windows on all analytics endpoints).

Workflow guidance

When the user asks for a quick overview

1. Run pinterest-ads-cli accounts to find accessible accounts 2. Use analytics with a recent date range and key columns like SPEND_IN_MICRO_DOLLAR,IMPRESSION_1,CLICKTHROUGH_1,CTR 3. Remember to divide micro-dollar values by 1,000,000 when presenting to the user

When the user asks for deep analysis

1. Start with account-level analytics to see overall performance 2. Use campaigns to list campaigns, then campaign-analytics for campaign-level breakdown 3. Drill down with adgroup-analytics or ad-analytics for underperforming entities 4. Use account-level analytics with --click-window-days and --view-window-days to understand attribution 5. Cross-reference with keywords to review targeting

When the user asks about audience targeting

1. Use audiences to see existing audiences 2. Use customer-lists to see customer list audiences 3. Use keywords with --ad-group-id to see targeting keywords for specific ad groups

When the user asks about conversion tracking

1. Run conversion-tags to list active conversion tags 2. Use conversion-tag to get details on a specific tag 3. Check analytics with TOTAL_CONVERSIONS column to see conversion performance

When the user asks about product catalogs

1. Use catalogs to list catalogs 2. Use feeds to inspect catalog feeds 3. Use product-groups to see product groupings

When the user asks about trends

1. Use trends with the appropriate region code (e.g., US, GB, CA) 2. Filter with --trend-type (growing, monthly, yearly, seasonal) 3. Narrow down with --interests, --genders, or --ages

When the user asks about billing

1. Use billing-profiles to see billing configurations (add --is-active for active only) 2. Use order-lines to see order lines 3. Use order-line with a specific ID for details

Error handling

API documentation references

# 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