Docs
Ctrl+K Search Alt+[Alt+] Guides
Get API key

API · Ad library

Pinterest ads

Search Pinterest ads with the same filters as the in-app Pinterest Ads dashboard. Use the canonical /api/v1/pinterest-ads path (the dashboard /api/pinterest-ads route is session-oriented).

GET/api/v1/pinterest-ads

Search Pinterest ads. Engagement names are platform-specific: likes = saves, shares = repins.

Send X-API-Key on every request.

Query parameters

  • keywordstringoptional

    Free-text search. Comma-separated terms are alternatives.

  • searchkeywordstringoptional

    Field scope for the keyword.

    Default All·Values All landingurl storeurl pagename adtext productname
  • countriesstringoptional

    All or comma-separated country codes.

  • sortingstringoptional
    Default datefound·Values datefound comments likes shares reactions lastseen daysrunning
  • sortdirectionstringoptional
    Default desc·Values desc asc
Request
curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/pinterest-ads?keyword=skincare&searchkeyword=All&countries=US&sorting=datefound&sortdirection=desc"
const res = await fetch(`${ORIGIN}/api/v1/pinterest-ads?keyword=skincare&searchkeyword=All&countries=US&sorting=datefound&sortdirection=desc`, {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
  },
});
const data = await res.json();
import os, requests

res = requests.get(
    f"{ORIGIN}/api/v1/pinterest-ads?keyword=skincare&searchkeyword=All&countries=US&sorting=datefound&sortdirection=desc",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
)
data = res.json()
Response
{
    "data": [
        {
            "id": "8471028374650192",
            "page_name": "Glow Beauty Co.",
            "ad_text": "The serum everyone's pinning",
            "media_type": "image",
            "likes": 12400,
            "shares": 880,
            "landing_url": "https://glowbeauty.com/serum"
        }
    ],
    "scroll": null,
    "total": 240,
    "nextscrapetime": 1710000000
}
{
    "success": false,
    "error": "Unauthorized"
}
{
    "success": false,
    "error": "WinningHunter Standard subscription required"
}

Each data item is a normalized Pinterest ad record matching the in-app cards (creative metadata, landing page/product fields, engagement, and saved/hidden flags for the key owner).

All query parameters

The endpoint accepts the same query keys as the in-app Pinterest Ads dashboard.

Parameter Notes
keyword Free-text search. Comma-separated terms are treated as alternatives.
searchkeyword Field scope: All, landingurl, storeurl, pagename, adtext, or productname.
pageid / pageidfromurl Restrict results to one Pinterest promoter/page id.
product / productid Restrict results to one Shopify product id referenced by the ad.
niches All or comma-separated niche values.
countries All or comma-separated country codes matched against Pinterest targeting countries.
languages / language All or comma-separated language codes.
gender Audience gender value where available.
website / technologies Store technology filters, for example Shopify-related values from the dashboard.
mediatype videos, video, images, or image.
pagetype product, products, collection, or collections.
minlikes, maxlikes Pinterest saves range.
mincomments, maxcomments Comment count range.
minshares, maxshares Pinterest repins range.
mintraffic, maxtraffic Monthly store traffic range when store data is available.
minprice, maxprice Product price range when Shopify product data is available.
from, to Ad start/creation date range.
fromlastseen, tolastseen Last-seen date range.
product_from, product_to Product or collection creation date range.
mindays, maxdays Days-running range based on the ad start date.
sorting / sort datefound, comments, likes, shares, reactions, lastseen, or daysrunning.
sortdirection asc or desc; defaults to desc.
adscorefilter / adscore winning, scaling, or testing; filters after scoring and returns up to 20 matches.

Notes

  • Pinterest uses platform-specific engagement names. likes maps to saves, and shares maps to repins.
  • The programmatic endpoint does not use dashboard trial behavior and does not increment free Pinterest dashboard credits. It only uses monthly API credits.
  • For the full API overview, see WinningHunter API Documentation.