OpenSkillIndex← back to search
claude-codeopenclawresearch

Skills pinterest-ads-cli

install
source · Clone the upstream repo
git clone https://github.com/openclaw/skills
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/bin-huang/pinterest-ads-cli" ~/.claude/skills/openclaw-skills-pinterest-ads-cli && rm -rf "$T"
OpenClaw · Install into ~/.openclaw/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.openclaw/skills && cp -r "$T/skills/bin-huang/pinterest-ads-cli" ~/.openclaw/skills/openclaw-skills-pinterest-ads-cli && rm -rf "$T"
manifest: skills/bin-huang/pinterest-ads-cli/SKILL.md
tags
#pinterest-ads#cli#analytics#reporting#data-extraction
source content

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.

OptionDescriptionDefault
--page-size <n>
Results per page (max 250)25
--bookmark <cursor>
Pagination cursor--

account

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

pinterest-ads-cli account <ad-account-id>

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 <ad-account-id>
OptionDescriptionDefault
--campaign-ids <ids>
Filter by campaign IDs (comma-separated)--
--entity-statuses <statuses>
Filter by status (comma-separated, e.g. ACTIVE,PAUSED)--
--page-size <n>
Results per page (max 250)25
--order <order>
Sort order: ASCENDING or DESCENDING--
--bookmark <cursor>
Pagination cursor--

adgroups

List ad groups for an ad account.

pinterest-ads-cli adgroups <ad-account-id>
OptionDescriptionDefault
--campaign-ids <ids>
Filter by campaign IDs (comma-separated)--
--ad-group-ids <ids>
Filter by ad group IDs (comma-separated)--
--entity-statuses <statuses>
Filter by status (comma-separated)--
--page-size <n>
Results per page (max 250)25
--order <order>
Sort order: ASCENDING or DESCENDING--
--bookmark <cursor>
Pagination cursor--

ads

List ads for an ad account.

pinterest-ads-cli ads <ad-account-id>
OptionDescriptionDefault
--campaign-ids <ids>
Filter by campaign IDs (comma-separated)--
--ad-group-ids <ids>
Filter by ad group IDs (comma-separated)--
--ad-ids <ids>
Filter by ad IDs (comma-separated)--
--entity-statuses <statuses>
Filter by status (comma-separated)--
--page-size <n>
Results per page (max 250)25
--order <order>
Sort order: ASCENDING or DESCENDING--
--bookmark <cursor>
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 <ad-account-id>
OptionDescriptionDefault
--ad-group-id <id>
Filter by ad group ID--
--page-size <n>
Results per page (max 250)25
--bookmark <cursor>
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 <ad-account-id>
OptionDescriptionDefault
--page-size <n>
Results per page (max 250)25
--order <order>
Sort order: ASCENDING or DESCENDING--
--bookmark <cursor>
Pagination cursor--

customer-lists

List customer lists for an ad account.

pinterest-ads-cli customer-lists <ad-account-id>
OptionDescriptionDefault
--page-size <n>
Results per page (max 250)25
--order <order>
Sort order: ASCENDING or DESCENDING--
--bookmark <cursor>
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 <ad-account-id>

conversion-tag

Get a specific conversion tag.

pinterest-ads-cli conversion-tag <ad-account-id> <tag-id>

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 <ad-account-id>
OptionDescriptionDefault
--is-active
Only return active profiles (boolean flag)false
--page-size <n>
Results per page (max 250)25
--bookmark <cursor>
Pagination cursor--

order-lines

List order lines for an ad account.

pinterest-ads-cli order-lines <ad-account-id>
OptionDescriptionDefault
--page-size <n>
Results per page (max 250)25
--order <order>
Sort order: ASCENDING or DESCENDING--
--bookmark <cursor>
Pagination cursor--

order-line

Get a specific order line.

pinterest-ads-cli order-line <ad-account-id> <order-line-id>

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 <ad-account-id>
OptionDescriptionDefault
--page-size <n>
Results per page (max 250)25
--order <order>
Sort order: ASCENDING or DESCENDING--
--bookmark <cursor>
Pagination cursor--

lead-form

Get a specific lead form.

pinterest-ads-cli lead-form <ad-account-id> <lead-form-id>

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.

OptionDescriptionDefault
--page-size <n>
Results per page (max 250)25
--bookmark <cursor>
Pagination cursor--

feeds

List catalog feeds.

OptionDescriptionDefault
--page-size <n>
Results per page (max 250)25
--bookmark <cursor>
Pagination cursor--

product-groups

List catalog product groups.

OptionDescriptionDefault
--page-size <n>
Results per page (max 250)25
--bookmark <cursor>
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 <region>
OptionDescriptionDefault
--trend-type <type>
Required. Trend type: growing, monthly, yearly, seasonal--
--interests <interests>
Filter by interests (comma-separated)--
--genders <genders>
Filter by genders (comma-separated)--
--ages <ages>
Filter by age groups (comma-separated)--
--limit <n>
Number of results50

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 <ad-account-id>
OptionDescriptionDefault
--start-date <date>
Required. Start date (YYYY-MM-DD)--
--end-date <date>
Required. End date (YYYY-MM-DD)--
--columns <cols>
Required. Metrics (comma-separated)--
--granularity <gran>
TOTAL, DAY, HOUR, WEEK, MONTHDAY
--click-window-days <n>
Click attribution window: 0, 1, 7, 14, 30, 60--
--view-window-days <n>
View attribution window: 0, 1, 7, 14, 30, 60--

campaign-analytics

Get campaign-level analytics.

pinterest-ads-cli campaign-analytics <ad-account-id>
OptionDescriptionDefault
--campaign-ids <ids>
Required. Campaign IDs (comma-separated)--
--start-date <date>
Required. Start date (YYYY-MM-DD)--
--end-date <date>
Required. End date (YYYY-MM-DD)--
--columns <cols>
Required. Metrics (comma-separated)--
--granularity <gran>
TOTAL, DAY, HOUR, WEEK, MONTHDAY

adgroup-analytics

Get ad group-level analytics.

pinterest-ads-cli adgroup-analytics <ad-account-id>
OptionDescriptionDefault
--ad-group-ids <ids>
Required. Ad group IDs (comma-separated)--
--start-date <date>
Required. Start date (YYYY-MM-DD)--
--end-date <date>
Required. End date (YYYY-MM-DD)--
--columns <cols>
Required. Metrics (comma-separated)--
--granularity <gran>
TOTAL, DAY, HOUR, WEEK, MONTHDAY

ad-analytics

Get ad-level analytics.

pinterest-ads-cli ad-analytics <ad-account-id>
OptionDescriptionDefault
--ad-ids <ids>
Required. Ad IDs (comma-separated)--
--start-date <date>
Required. Start date (YYYY-MM-DD)--
--end-date <date>
Required. End date (YYYY-MM-DD)--
--columns <cols>
Required. Metrics (comma-separated)--
--granularity <gran>
TOTAL, DAY, HOUR, WEEK, MONTHDAY

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

  • Authentication errors -- ask the user to verify their access token and 
    ads:read
    scope
  • Credentials not found -- check that one of the three credential sources is configured: 
    --credentials
    flag, 
    PINTEREST_ADS_ACCESS_TOKEN
    env var, or 
    ~/.config/pinterest-ads-cli/credentials.json
  • Empty analytics -- check the date range, entity status, and whether the account had active ads in the period
  • Permission errors -- ensure the access token has the required 
    ads:read
    scope
  • Invalid column names -- verify column names match the Pinterest API schema (e.g., 
    SPEND_IN_MICRO_DOLLAR
    , not 
    SPEND
    )

API documentation references