Docs
Ctrl+K Rechercher Alt+[Alt+] Guides
Obtenir une clé API

API · Bibliothèque publicitaire

Publicités sur Pinterest

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).

OBTENIR/api/v1/pinterest-ads

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

Send Clé X-API on every request.

Query parameters

  • mot-cléstringoptional

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

  • searchkeywordstringoptional

    Field scope for the keyword.

    Par défaut Tous-Values Tous landingurl storeurl pagename adtext productname
  • countriesstringoptional

    All or comma-separated country codes.

  • sortingstringoptional
    Par défaut datefound-Values datefound comments likes shares reactions lastseen daysrunning
  • sortdirectionstringoptional
    Par défaut desc-Values desc asc
Demande
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.

Paramètre Remarques
mot-clé Free-text search. Comma-separated terms are treated as alternatives.
searchkeyword Field scope: Tous, landingurl, storeurl, pagename, adtext, or productname.
pageid / pageidfromurl Restrict results to one Pinterest promoter/page id.
produit / productid Restrict results to one Shopify product id referenced by the ad.
niches Tous or comma-separated niche values.
countries Tous or comma-separated country codes matched against Pinterest targeting countries.
languages / language Tous 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 vidéos, video, images, or image.
pagetype produit, produits, 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 / trier datefound, comments, likes, shares, reactions, lastseen, or daysrunning.
sortdirection asc ou 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.