VX Agents

OpenAPI Marketplace · Advertising

Pinterest Ads

v1.0.0 · 13 endpoints · 0 connections · shared by vx.ai

Lets an agent report on and manage Pinterest advertising: list ad accounts, campaigns, ad groups and ads, pull spend, impression and click analytics at each level, create campaigns, and change budgets, bids and statuses. Curated from Pinterest's official OpenAPI specification.

Connect this API to an AI agent Browse all specs

What you can do with Pinterest Ads via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
GET /ad_accounts listAdAccounts List the ad accounts you can access
GET /ad_accounts/{ad_account_id} getAdAccount Get an ad account (currency, owner, country)
GET /ad_accounts/{ad_account_id}/analytics getAdAccountAnalytics Get account-level spend and performance by day
GET /ad_accounts/{ad_account_id}/campaigns listCampaigns List campaigns with status and budgets
POST /ad_accounts/{ad_account_id}/campaigns createCampaigns Create campaigns (create them PAUSED)
PATCH /ad_accounts/{ad_account_id}/campaigns updateCampaigns Change campaign status, budget or name (batch)
GET /ad_accounts/{ad_account_id}/campaigns/analytics getCampaignAnalytics Get spend and performance for campaigns
GET /ad_accounts/{ad_account_id}/ad_groups listAdGroups List ad groups with bids, budgets and targeting
PATCH /ad_accounts/{ad_account_id}/ad_groups updateAdGroups Change ad group status, bid or budget (batch)
GET /ad_accounts/{ad_account_id}/ad_groups/analytics getAdGroupAnalytics Get spend and performance for ad groups
GET /ad_accounts/{ad_account_id}/ads listAds List ads with their status and Pins
PATCH /ad_accounts/{ad_account_id}/ads updateAds Pause, activate or rename ads (batch)
GET /ad_accounts/{ad_account_id}/ads/analytics getAdAnalytics Get spend and performance for ads

Authentication

pinterestOAuth

OAuth 2.0

Scopes: ads:read ads:write

Pinterest OAuth 2.0 (authorization code) for a Pinterest app with Ads access.

How to get a credential

  1. Sign in at developers.pinterest.com with the business account that manages the ads, and Connect app / create an app (Standard access is needed for production ad accounts).
  2. In the app settings, add the VX Agents redirect URI shown in the credential form and copy the App ID and App secret key.
  3. Paste them into the VX Agents credential and sign in, approving the ads:read and ads:write scopes. The user must have an Admin, Analyst or Campaign manager role on the ad account.

Permissions used

Scope Operations
ads:read listAdAccounts, getAdAccount, getAdAccountAnalytics, listCampaigns, getCampaignAnalytics, listAdGroups, getAdGroupAnalytics, listAds, getAdAnalytics
ads:write createCampaigns, updateCampaigns, updateAdGroups, updateAds

Common errors

  • 401 Unauthorized: access token expired (they last 30 days). Reconnect the credential so it gets a fresh token.
  • 403 Forbidden: missing ads:write/ads:read scope, or the user has no role (or only an Analyst role, which cannot write) on that ad account.
  • 400 Bad Request: invalid date range (analytics allow up to 90 days per request and data from the last 914 days), unknown columns, or a budget below the minimum. Read the message field.
  • 429 Too Many Requests: rate limit for the endpoint category. Wait and retry with backoff.

Store the connection as a VX Agents OAuth credential. Never paste tokens into chat.

Usage guide

Setup

  • Connect a Pinterest OAuth credential with ads:read and ads:write. The signed-in user needs a role on each ad account (Analyst can only read).
  • Call listAdAccounts once and pin ad_account_id as a preset when the agent manages one account. Note the account currency.

Report first

  1. getAdAccountAnalytics with start_date/end_date (YYYY-MM-DD, up to 90 days per request), granularity (TOTAL, DAY, WEEK, MONTH) and columns, e.g. SPEND_IN_DOLLAR,IMPRESSION_1,CLICKTHROUGH_1,CTR,CPC_IN_MICRO_DOLLAR,TOTAL_CONVERSIONS.
  2. listCampaigns (filter entity_statuses=ACTIVE), then getCampaignAnalytics with campaign_ids (comma-separated, max 250) and the same columns to rank campaigns.
  3. Drill down: listAdGroups / getAdGroupAnalytics (ad_group_ids), then listAds / getAdAnalytics (ad_ids).
  4. Summarize spend, CTR, CPC and conversions, and propose changes.

Change campaigns (spends money: confirm first)

  1. Show the user the exact change (old → new) and wait for a yes before any write.
  2. Pause/activate or change budgets with updateCampaigns: an array like [{"id": "626...", "status": "PAUSED"}] or [{"id": "626...", "daily_spend_cap": 50000000}].
  3. Ad group bids/budgets/status with updateAdGroups (bid_in_micro_currency, budget_in_micro_currency, status); ad status with updateAds.
  4. New campaigns via createCampaigns with ad_account_id, name, objective_type (e.g. AWARENESS, CONSIDERATION, WEB_CONVERSION) and status: "PAUSED". Let the user activate it.

Good to know

  • Money fields ending in micro_currency/spend_cap are in micro units: 1,000,000 = 1.00 in the account currency (50000000 = 50.00).
  • Updates are batch PATCH calls: send only id plus the fields to change; check each item's exceptions in the response.
  • Statuses: ACTIVE, PAUSED, ARCHIVED (archived cannot be reactivated, so confirm first).
  • Analytics are delayed up to a few hours; data older than about 2.5 years is unavailable. Use reporting_timezone if the account is not in UTC.
  • Paging: follow bookmark with page_size up to 250.

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “Pinterest Ads” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.