Pinterest Ads

Strategic skill for managing Pinterest Ads campaigns via the Pinterest Ads API v5 surface exposed by the Hyper MCP. Ad-group creation goes through a direct REST call (bypassing SDK model conversion) so parameter types must be sent exactly as documented — strings as strings, integers as integers.

Out of scope — defer to other skills

Request	Send them to
Google Ads campaign	google-ads
Meta (Facebook / Instagram) ad campaign	meta-ads
Amazon Sponsored Products	amazon-ads
TikTok ad campaign	tiktok-ads
Competitor ad research from the Meta Ads Library	meta-ads-library
Organic Pinterest pinning	not currently shipped — use the Pinterest app

Requirements

• Hyper MCP installed and connected. https://app.hyperfx.ai/mcp
• Pinterest Ads integration connected at https://app.hyperfx.ai/integrations (Pinterest Business account with ad account access).

If pinterest_ads_list_ad_accounts is not in the tool list, stop and tell the user to enable the Hyper MCP and connect Pinterest Ads.

Tool surface

Tool group	Tools
Accounts	pinterest_ads_list_ad_accounts, pinterest_ads_get_ad_account
Campaigns	pinterest_ads_list_campaigns, pinterest_ads_get_campaign, pinterest_ads_create_campaign, pinterest_ads_update_campaign
Ad groups	pinterest_ads_list_ad_groups, pinterest_ads_get_ad_group, pinterest_ads_create_ad_group, pinterest_ads_update_ad_group
Ads	pinterest_ads_list_ads, pinterest_ads_get_ad, pinterest_ads_create_ad, pinterest_ads_update_ad
Audiences	pinterest_ads_list_audiences, pinterest_ads_create_audience, pinterest_ads_create_customer_list
Conversion	pinterest_ads_list_conversion_tags, pinterest_ads_create_conversion_tag, pinterest_ads_send_conversion_event
Keywords	pinterest_ads_create_keyword
Analytics	pinterest_ads_get_campaign_analytics

Critical Rules

CRITICAL: All budgets and bids are in microcurrency. $1.00 = 1,000,000 microdollars. $50/day = 50,000,000. Never pass dollar amounts directly.

CRITICAL: When using is_flexible_daily_budgets: true, you MUST also set is_campaign_budget_optimization: true. FDB requires CBO.

CRITICAL: Lifetime CBO campaigns MUST include end_time (Unix timestamp).

CRITICAL: Create campaigns with status PAUSED initially. Never launch live without user review.

CRITICAL: WEB_CONVERSION ad groups MUST use billable_event="IMPRESSION" (NOT CLICKTHROUGH) and MUST include optimization_goal_metadata with attribution_windows, conversion_event, conversion_tag_id, and cpa_goal_value_in_micro_currency.

CRITICAL: Keyword creation REQUIRES match_type. Without it, the API returns 500 errors.

CRITICAL: CBO campaigns manage budget at the campaign level. Do NOT set budget_in_micro_currency on ad groups under CBO campaigns.

IMPORTANT: retention_days is deprecated for ENGAGEMENT audiences. Omit it from audience rules.

Phase 1: Account Discovery

Call pinterest_ads_list_ad_accounts() to list accessible accounts.

• If multiple: ask the user to select one.
• If single: inform the user and proceed.
• Note the ad_account_id — it's required for every subsequent tool call.

Phase 2: Account Assessment

Existing campaign audit

Run these in parallel to understand the account state:

pinterest_ads_list_campaigns(ad_account_id="<AD_ACCOUNT_ID>")
pinterest_ads_list_ad_groups(ad_account_id="<AD_ACCOUNT_ID>")
pinterest_ads_list_ads(ad_account_id="<AD_ACCOUNT_ID>")
pinterest_ads_list_audiences(ad_account_id="<AD_ACCOUNT_ID>")
pinterest_ads_list_conversion_tags(ad_account_id="<AD_ACCOUNT_ID>")

Research & confirm

• Get the destination URL and creative assets (Pin IDs).
• Understand the campaign objective (awareness, consideration, conversions).
• Confirm daily / lifetime budget.
• Confirm target audience (geo, interests, demographics).
• If WEB_CONVERSION: ensure a conversion tag exists.

Phase 3: Campaign Structure

Pinterest campaign hierarchy

Ad Account
└── Campaign (objective, budget for CBO)
    └── Ad Group (targeting, bidding, schedule)
        └── Ad (creative Pin + tracking)

Campaign objectives

Objective	Use case
AWARENESS	Brand visibility, impressions
CONSIDERATION	Traffic, engagement
VIDEO_VIEW	Video completion
WEB_CONVERSION	Purchases, signups, leads
CATALOG_SALES	Shopping / product catalog
WEB_SESSIONS	Website visits

CBO vs Non-CBO

Setting	CBO campaign	Non-CBO campaign
Budget location	Campaign level (daily_spend_cap or lifetime_spend_cap)	Ad group level (budget_in_micro_currency)
is_campaign_budget_optimization	true	false
Ad group budget	Managed by Pinterest	Set per ad group

Phase 4: Campaign Creation

1. Create campaign

pinterest_ads_create_campaign(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="Spring Collection 2026",
    objective_type="WEB_CONVERSION",
    status="PAUSED",
    daily_spend_cap=50000000,
    is_campaign_budget_optimization=true,
    is_flexible_daily_budgets=true,
)

Parameter requirements:

• is_flexible_daily_budgets=true → requires is_campaign_budget_optimization=true.
• lifetime_spend_cap → requires end_time.
• All spend caps in microcurrency.

2. Create ad group

CRITICAL: This tool sends a direct REST call to the Pinterest API v5 (bypassing SDK models). Pass parameter values exactly as documented — strings as strings, integers as integers.

CRITICAL: Ad-group parameters depend heavily on the parent campaign's objective_type. Follow the objective-specific templates below exactly.

billable_event values: CLICKTHROUGH, IMPRESSION, VIDEO_V_50_MRC.

Objective / billable_event compatibility

Campaign objective_type	Required billable_event	bid_in_micro_currency	optimization_goal_metadata
AWARENESS	IMPRESSION	REQUIRED (integer)	Not needed
CONSIDERATION	CLICKTHROUGH	REQUIRED (integer)	Not needed
VIDEO_VIEW	VIDEO_V_50_MRC	Optional	Not needed
WEB_CONVERSION	IMPRESSION	Optional	REQUIRED
CATALOG_SALES	CLICKTHROUGH	REQUIRED (integer)	Not needed
WEB_SESSIONS	CLICKTHROUGH	Optional	Not needed

Template: CONSIDERATION campaign (simplest, non-CBO)

pinterest_ads_create_ad_group(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="US Women 25-54",
    campaign_id="<CAMPAIGN_ID>",
    billable_event="CLICKTHROUGH",
    bid_in_micro_currency=1000000,
    budget_in_micro_currency=10000000,
    targeting_spec={"LOCATION": ["US"], "GENDER": ["female"], "MINIMUM_AGE": "25", "MAXIMUM_AGE": "54"},
    bid_strategy_type="AUTOMATIC_BID",
    status="PAUSED",
)

Template: CONSIDERATION campaign (CBO — no ad group budget)

pinterest_ads_create_ad_group(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="US Women 25-54",
    campaign_id="<CAMPAIGN_ID>",
    billable_event="CLICKTHROUGH",
    bid_in_micro_currency=1000000,
    targeting_spec={"LOCATION": ["US"], "GENDER": ["female"], "MINIMUM_AGE": "25", "MAXIMUM_AGE": "54"},
    bid_strategy_type="AUTOMATIC_BID",
    status="PAUSED",
)

Template: WEB_CONVERSION campaign (requires optimization_goal_metadata)

CRITICAL: WEB_CONVERSION ad groups MUST use billable_event="IMPRESSION" (NOT CLICKTHROUGH). They MUST provide optimization_goal_metadata with the full nested structure shown below.

TYPE SAFETY: cpa_goal_value_in_micro_currency MUST be a string (e.g., "5000000"), NOT an integer. conversion_tag_id MUST be a string. attribution_windows values MUST be integers.

pinterest_ads_create_ad_group(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="Conversion - Checkout",
    campaign_id="<CAMPAIGN_ID>",
    billable_event="IMPRESSION",
    targeting_spec={"LOCATION": ["US"]},
    bid_strategy_type="AUTOMATIC_BID",
    status="PAUSED",
    optimization_goal_metadata={
        "conversion_tag_v3_goal_metadata": {
            "attribution_windows": {
                "click_window_days": 30,
                "engagement_window_days": 30,
                "view_window_days": 1,
            },
            "conversion_event": "CHECKOUT",
            "conversion_tag_id": "<CONVERSION_TAG_ID>",
            "cpa_goal_value_in_micro_currency": "5000000",
            "is_roas_optimized": false,
        },
    },
)

conversion_event values: PAGE_VISIT, SIGNUP, CHECKOUT, CUSTOM, VIEW_CATEGORY, SEARCH, ADD_TO_CART, WATCH_VIDEO, LEAD, APP_INSTALL.

attribution_windows — only these exact combos are accepted (click / engage / view):

click_window_days	engagement_window_days	view_window_days	Shorthand
30	30	30	30/30/30
30	30	7	30/30/7
30	30	1	30/30/1 (default)
7	7	7	7/7/7
7	7	1	7/7/1
7	0	0	7/0/0
1	1	1	1/1/1
1	0	0	1/0/0

The tool auto-normalizes: if attribution_windows is missing or uses an invalid combo, it defaults to 30/30/1. It also auto-wraps in conversion_tag_v3_goal_metadata if the wrapper is missing, coerces cpa_goal_value_in_micro_currency to string, and defaults CPA to $10 if omitted.

cpa_goal_value_in_micro_currency: STRING (pattern ^[0-9]+$). Set high enough to avoid "CPA goal value below bid floor" errors. Example: "10000000" = $10 CPA.

Optional fields in conversion_tag_v3_goal_metadata:

• is_roas_optimized (boolean) — set true only when conversion_event="CHECKOUT" AND bid_strategy_type="AUTOMATIC_BID".
• learning_mode_type (string) — "ACTIVE" or "NOT_ACTIVE". Omit if not needed.

Template: AWARENESS campaign

pinterest_ads_create_ad_group(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="Brand Awareness",
    campaign_id="<CAMPAIGN_ID>",
    billable_event="IMPRESSION",
    bid_in_micro_currency=2000000,
    targeting_spec={"LOCATION": ["US"]},
    bid_strategy_type="AUTOMATIC_BID",
    status="PAUSED",
)

Budget rules for ad groups

• CBO campaigns: Do NOT set budget_in_micro_currency on the ad group. Budget is controlled at the campaign level.
• Non-CBO campaigns: budget_in_micro_currency is REQUIRED at the ad group level.

bid_strategy_type values: AUTOMATIC_BID, MAX_BID, TARGET_AVG.

status: Always create with status="PAUSED" for review. Set to "ACTIVE" after user approval.

pacing_delivery_type: Optional. "STANDARD" (default) or "ACCELERATED".

targeting_spec keys (all values are arrays of strings unless noted):

• LOCATION — ISO Alpha-2 country codes or US Nielsen DMA codes (e.g., ["US", "CA"], ["807"]). Required (or use GEO).
• GEO — Region codes (e.g., ["BE-VOV"]) or postal codes (e.g., ["US-94107"]). Alternative to LOCATION.
• GENDER — ["male"], ["female"], or ["unknown"].
• MINIMUM_AGE — string "18" through "65" (use with MAXIMUM_AGE, not with AGE_BUCKET).
• MAXIMUM_AGE — string "18" through "65" or "65+" (use with MINIMUM_AGE).
• AGE_BUCKET — ["18-24", "25-34", "35-44", "45-54", "55-64", "65+"] (legacy, cannot combine with MIN/MAX_AGE).
• INTEREST — interest IDs from Pinterest taxonomy.
• LOCALE — ISO 639-1 language codes (e.g., ["en"]).
• APPTYPE — ["android_mobile", "android_tablet", "ipad", "iphone", "web", "web_mobile"].
• AUDIENCE_INCLUDE — audience IDs to include.
• AUDIENCE_EXCLUDE — audience IDs to exclude.

3. Create ad

pinterest_ads_create_ad(
    ad_account_id="<AD_ACCOUNT_ID>",
    ad_group_id="<AD_GROUP_ID>",
    creative_type="REGULAR",
    pin_id="<PIN_ID>",
    name="Spring Sale Ad",
    status="ACTIVE",
    destination_url="https://example.com/spring-sale",
)

creative_type values: REGULAR, VIDEO, SHOPPING, CAROUSEL, MAX_VIDEO, SHOP_THE_PIN, IDEA.

Phase 5: Audience & Targeting

Create audience

pinterest_ads_create_audience(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="Website Visitors",
    audience_type="VISITOR",
    rule={"visitor_source_id": "<TAG_ID>", "type": "visitors"},
)

audience_type values: CUSTOMER_LIST, VISITOR, ENGAGEMENT, ACTALIKE.

Rule structure by type:

Type	Rule example
VISITOR	{"visitor_source_id": "<TAG_ID>", "type": "visitors"}
ENGAGEMENT	{"source": "AUDIENCE_RETENTION"} (do NOT include retention_days)
CUSTOMER_LIST	{"list_type": "EMAIL"}
ACTALIKE	{"source_id": "<SEED_AUDIENCE_ID>", "country": "US", "percentage": 5}

Create customer list

pinterest_ads_create_customer_list(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="Email Subscribers",
    records="user1@example.com,user2@example.com,...",
    list_type="EMAIL",
)

list_type values: EMAIL, IDFA, MAID, LR_ID, DLX_ID, HASHED_PINNER_ID.

Lists must match at least 100 Pinterest accounts after processing.

Phase 6: Conversion Tracking

List existing tags

pinterest_ads_list_conversion_tags(ad_account_id="<AD_ACCOUNT_ID>")

Create conversion tag

pinterest_ads_create_conversion_tag(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="Purchase Tracking",
    aem_enabled=true,
)

Send conversion event

pinterest_ads_send_conversion_event(
    ad_account_id="<AD_ACCOUNT_ID>",
    event_name="checkout",
    action_source="web",
    event_time=1709424000,
    event_id="unique_event_123",
    user_data={
        "em": ["5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"],
        "client_ip_address": "192.168.1.1",
        "client_user_agent": "Mozilla/5.0...",
    },
    custom_data={"currency": "USD", "value": "99.99"},
)

event_name values: add_to_cart, checkout, custom, lead, page_visit, search, signup, view_category, watch_video.

action_source values: app_android, app_ios, web, offline.

user_data requirements (at least one identifier required):

• em — array of SHA256-hashed email addresses (NOT plain text).
• hashed_maids — array of hashed mobile ad IDs.
• OR: client_ip_address + client_user_agent.

Phase 7: Keywords

CRITICAL: match_type is REQUIRED. Without it, the Pinterest API returns a 500 error.

pinterest_ads_create_keyword(
    ad_account_id="<AD_ACCOUNT_ID>",
    parent_id="<AD_GROUP_ID>",
    value="spring fashion trends",
    match_type="BROAD",
)

match_type values: BROAD, PHRASE, EXACT, EXACT_NEGATIVE, PHRASE_NEGATIVE.

• BROAD — ads show for related searches.
• PHRASE — ads show when search contains the phrase.
• EXACT — ads show only for exact match.
• EXACT_NEGATIVE / PHRASE_NEGATIVE — exclude these terms.

bid (optional): Bid in microcurrency for this keyword. Overrides ad group default bid.

Phase 8: Analytics

pinterest_ads_get_campaign_analytics(
    ad_account_id="<AD_ACCOUNT_ID>",
    campaign_ids=["<CAMPAIGN_ID>"],
    start_date="2026-02-01",
    end_date="2026-03-01",
    columns=["SPEND_IN_MICRO_DOLLAR", "TOTAL_IMPRESSION", "TOTAL_CLICKTHROUGH", "CPC_IN_MICRO_DOLLAR", "CTR", "CPM_IN_MICRO_DOLLAR"],
    granularity="DAY",
)

granularity values: TOTAL, DAY, HOUR, WEEKLY, MONTHLY.

Common analytics columns: SPEND_IN_MICRO_DOLLAR, TOTAL_IMPRESSION, TOTAL_CLICKTHROUGH, CPC_IN_MICRO_DOLLAR, CPM_IN_MICRO_DOLLAR, CTR, ECTR, TOTAL_CONVERSIONS, TOTAL_CONVERSIONS_VALUE_IN_MICRO_DOLLAR.

Update Operations

pinterest_ads_update_campaign, pinterest_ads_update_ad_group, and pinterest_ads_update_ad all follow the same shape — pass ad_account_id, the entity ID (campaign_id / ad_group_id / ad_id), and any fields you want to change. Statuses use ACTIVE, PAUSED, or ARCHIVED (cannot be unarchived).

pinterest_ads_update_campaign(
    ad_account_id="<AD_ACCOUNT_ID>",
    campaign_id="<CAMPAIGN_ID>",
    name="Updated Name",
    status="PAUSED",
    daily_spend_cap=75000000,
)

Campaign Workflow

Discovery → audit account → research (objectives, audience, assets) → confirm strategy → create campaign (PAUSED) → create ad groups → create ads → review → activate.

Known Limitations

Issue	Workaround
Keyword creation returns 500 without match_type	Always specify match_type (BROAD, PHRASE, EXACT).
retention_days deprecated for ENGAGEMENT audiences	Omit from rule dict.
WEB_CONVERSION ad groups require many parameters	Use the WEB_CONVERSION template exactly — include full optimization_goal_metadata.
WEB_CONVERSION ad groups must use IMPRESSION billable_event	Do NOT use CLICKTHROUGH for WEB_CONVERSION.
CBO campaigns reject ad group budgets	Do NOT set budget_in_micro_currency when parent campaign has CBO enabled.
cpa_goal_value_in_micro_currency must be a string	Pass as "5000000", not 5000000.
conversion_tag_id must be a real tag from the account	List conversion tags first, then use an existing tag ID.

Safety Rules

Never:

• Assume Pin IDs or ad account IDs — always ask or look up.
• Skip the account audit phase.
• Create campaigns without explicit approval.
• Set campaigns to ACTIVE without user consent.
• Pass dollar amounts instead of microcurrency.
• Use retention_days for ENGAGEMENT audiences.
• Create WEB_CONVERSION ad groups without optimization_goal_metadata.
• Use CLICKTHROUGH billable_event for WEB_CONVERSION campaigns (use IMPRESSION).
• Set ad group budgets on CBO campaigns.
• Create keywords without specifying match_type.
• Pass cpa_goal_value_in_micro_currency as an integer (must be a string like "5000000").
• Omit conversion_tag_id from WEB_CONVERSION optimization metadata (list tags first, use a real ID).