Pinterest Marketing API: Ads

Pinterest Marketing API: Ads

Download OpenAPI specification:Download

You are viewing documentation specific to Ads and will only see endpoints and guides curated for this App type. See Introduction to learn more.


June 2022

Summary of changes for June

  • Deprecation of Get Related Keywords endpoint
  • API support for Idea ads

Idea ads

Ad Creation (promoting Idea Pins)

To promote an Idea Pin,

Send a POST request to:{advertiser_id}/ads

  1. Set "creative_type" to "STORY"
  2. Set "destination_url" as it is required for Idea ads
  3. Set "pin" to an Idea Pin id.


Reporting changes are the same as the reporting changes for Idea Pins with paid partnership with the exception of video metrics.

Video metrics

Our video metrics are calculated as follows:

  • We treat all videos and images within an Idea ad as one video and calculate standard video metrics across this video. Eg: for Video 1 (10 sec) | Image 2 (5 seconds) | Video 3 (10 sec), the total video length is 10+5+10 = 25 sec
  • Image pages will always auto advance after 5 seconds if the Idea ad is viewed in full screen
  • The total video length is counted as watch time if the user auto-advanced from one page to the next
  • We only count actual watchtime if the user skips to the next video or image card. Eg: If a user watched 3 seconds of Video 1, we count 3 secs of watchtime and not 10 secs. If a user spent 2 seconds on Image 2 while it is autoadvancing, we count 2 secs of watchtime and not 5 secs.

March 2022

Summary of changes for March

  • Ads API v3 shutdown
  • Update to top pins metric sort options

Ads API v3 Shutdown

Ads API v3 has come to an end of life starting today March 1st, 2022. From now on, all ads/v3 endpoints will return a 410 error response. Please make requests to Ads API v4. Check out the v3 to v4 migration guide for an overview of the new changes. Learn more about our new ads v4 bulk features.

Update to top pins metric sort options

GET /v3/partners/analytics/users/{user}/pins/top/

We are removing support for sorting by rates in the top pins endpoint. The updated list of supported metrics for the sort_by parameter is impressions, engagements, pin clicks, outbound clicks, and saves.

November 2021

Summary of changes for November

  • Enhancements to Engagement Audiences
  • Deprecation of Top Repins endpoint

Engagement Audiences

New engagement action options

We are simplifying the process of creating engagement audiences by introducing the option to create engagement audiences from Pinners who have performed “any engagement action” or “optimized engagement actions”.

  • With “any engagement action”, you can reach audiences who have perfo