Belgeler
Ctrl+K Arama Alt+[Alt+] Kılavuzlar
API anahtarını al

API

Pinterest reklamları

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

AL/api/v1/pinterest-ads

Search Pinterest ads. Sort/filter params use likes (= saves) and shares (= repins); response fields are save_count and repin_count.

Send X-API-Anahtarı on every request.

Query parameters

  • anahtar kelimedize
  • arama kelimesidize
    Default: TümüValues: Tümü hedef URL mağaza URL'si sayfa adı reklam metni ürün adı
  • ülkelerdize
  • sıralamadize
    Default: bulunma tarihiValues: bulunma tarihi yorumlar beğeniler hisse senetleri tepkiler son görülme tarihi koşu günleri
  • sıralama yönüdize
    Default: açıklamaValues: açıklama asc
  • sayfatamsayı
    Default: 0
  • scrolldize

    Opaque cursor; empty on first request.

  • sınırtamsayı

    Max 50 on first request; stored in scroll.

    Default: 20
Talep
curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/pinterest-ads?keyword=skincare&searchkeyword=All&countries=US&sorting=datefound&sortdirection=desc&page=0&scroll=string&limit=20"
const res = await fetch(`${ORIGIN}/api/v1/pinterest-ads?keyword=skincare&searchkeyword=All&countries=US&sorting=datefound&sortdirection=desc&page=0&scroll=string&limit=20`, {
  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&page=0&scroll=string&limit=20",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
)
data = res.json()
Yanıt
{
    "data": [
        {
            "id": "8471028374650192",
            "ad_id": "8471028374650192",
            "productid": "8471028374650192",
            "platform": "pinterest",
            "page_id": "5482938471028374",
            "page_name": "Glow Beauty Co.",
            "pageName": "Glow Beauty Co.",
            "promoter_username": "glowbeautyco",
            "page_profile_picture_url": "https://i.pinimg.com/60x60/aa/bb/cc/aabbccdd11223344556677889900aabb.jpg",
            "title": "The serum everyone's pinning",
            "text": "Dermatologist-tested vitamin C serum for brighter skin in 2 weeks.",
            "copy": "The serum everyone's pinning\n\nDermatologist-tested vitamin C serum for brighter skin in 2 weeks.",
            "description": "Dermatologist-tested vitamin C serum for brighter skin in 2 weeks.",
            "media_type": "video",
            "media_url": "https://v1.pinimg.com/videos/mc/expMp4/aa/bb/cc/aabbccdd11223344556677889900aabb.mp4",
            "image": "https://i.pinimg.com/originals/aa/bb/cc/aabbccdd11223344556677889900aabb.jpg",
            "poster": "https://i.pinimg.com/originals/aa/bb/cc/aabbccdd11223344556677889900aabb.jpg",
            "video": "https://v1.pinimg.com/videos/mc/expMp4/aa/bb/cc/aabbccdd11223344556677889900aabb.mp4",
            "pin_url": "https://www.pinterest.com/pin/8471028374650192/",
            "page_url": "https://www.pinterest.com/glowbeautyco/",
            "link": "https://glowbeautyco.com/products/vitamin-c-serum",
            "destination_url": "https://glowbeautyco.com/products/vitamin-c-serum",
            "urlStore": "https://glowbeautyco.com/products/vitamin-c-serum",
            "domain": "glowbeautyco.com",
            "save_count": 12400,
            "repin_count": 880,
            "repins": 880,
            "comment_count": 142,
            "comments": 142,
            "created_time": "2024-11-08 14:22:00",
            "started": "2024-11-08 14:22:00",
            "last_seen": "2026-03-15",
            "lastfoundago": "2 weeks ago",
            "daysrunning": 128,
            "adscore": "Winning",
            "adscore_reasons": [
                "Ad is running for longer than 7 days"
            ],
            "technologies": [
                "Shopify"
            ],
            "countries": [
                "US",
                "CA"
            ],
            "pagecountries": [
                "US",
                "CA"
            ],
            "pagecountrycount": 2,
            "adscount": 47,
            "niche_v2": "Beauty & Personal Care",
            "shopify_productprice": 34,
            "shopify_currency": "USD",
            "product_title": "Vitamin C Brightening Serum",
            "store_traffic": {
                "domain": "glowbeautyco.com",
                "canonical_domain": "glowbeautyco.com",
                "monthly_visits": 185000,
                "source": "similarweb",
                "monthly_visits_updated_at": "2026-02-01"
            },
            "like_count_history": {
                "2024-11-08": 1200,
                "2025-01-01": 5400,
                "2026-03-01": 12400
            },
            "share_count_history": {
                "2024-11-08": 80,
                "2025-01-01": 310,
                "2026-03-01": 880
            },
            "comment_count_history": {
                "2024-11-08": 12,
                "2026-03-01": 142
            },
            "saved": false,
            "hidden": false
        }
    ],
    "scroll": "a1b2c3d4e5f6789012345678901234ab",
    "limit": 20,
    "total": 240,
    "nextscrapetime": 1710000000
}
{
    "success": false,
    "error": "Unauthorized"
}
{
    "success": false,
    "error": "Invalid or expired scroll token"
}
{
    "success": false,
    "error": "WinningHunter Basic plan or higher required"
}
{
    "success": false,
    "error": "No API credits remaining. Buy an add-on pack or wait until next monthly reset.",
    "credits": {
        "used": 20000,
        "limit": 20000,
        "remaining": 0,
        "addon_remaining": 0,
        "total_remaining": 0
    },
    "purchase": {
        "url": "https://…/checkout-api-credits?credits=…"
    }
}

Each veriler item is a fully processed Pinterest ad — same pipeline as dashboard cards (map_pinterest_adprocess_ads). Engagement in responses uses save_count / repin_count (aliases repins, yorumlar). Sort/filter query params still use beğeniler (= saves) and hisse senetleri (= repins). Top-level total may be null when the count is not computed inline.

More query parameters

Parametre Notlar
sayfa kimliği / URL'den sayfa kimliği One promoter/page
ürün / ürün kodu One Shopify product id
nişler, diller / dil, cinsiyet Catalog filters
web sitesi / teknolojiler Store tech filters
medya türü videolar / resimler (and singular forms)
sayfa türü product(s) / collection(s)
minlikes / en çok beğenilen, mincomments / maksimum yorum sayısı, minshares / maksimum hisse Engagement ranges
mintraffic / maxtraffic, en düşük fiyat / maksimum fiyat When store/product data exists
...'den / ...'ye, songörüldüğünden beri / görülmüş, ürün_kaynağı / ürün_adresi Tarihler
zihin günleri / maksimum gün sayısı Çalışan günler
reklam puan filtresi / reklam puanı kazanan / ölçeklendirme / test

Pagination: empty scroll on first request; pass returned scroll with the same filters. Tokens expire after ~1 hour.

Does not use free dashboard Pinterest credits — only monthly API credits.