Documentos
Ctrl+K Buscar Alt+[Alt+] Guías
Obtener clave API

API · Biblioteca de anuncios

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

OBTENER/api/v1/pinterest-ads

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

Send Clave X-API on every request.

Query parameters

  • palabra clavecadenaoptional

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

  • palabra clave de búsquedacadenaoptional

    Field scope for the keyword.

    Por defecto Todo·Valores Todo URL de destino storeurl nombre de la página texto del anuncio nombre del producto
  • paísescadenaoptional

    All or comma-separated country codes.

  • clasificacióncadenaoptional
    Por defecto fecha de hallazgo·Valores fecha de hallazgo comments likes shares reactions última conexión días corriendo
  • dirección de ordenacióncadenaoptional
    Por defecto desc·Valores desc asc
Solicitud
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()
Respuesta
{
    "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 datos 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).

Todos de consulta

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

Parámetro Notas
palabra clave Free-text search. Comma-separated terms are treated as alternatives.
palabra clave de búsqueda Field scope: Todo, URL de destino, storeurl, nombre de la página, texto del anuncio, o nombre del producto.
pageid / identificador de página a partir de la URL Restrict results to one Pinterest promoter/page id.
producto / id_del_producto Restrict results to one Shopify product id referenced by the ad.
nichos Todo or comma-separated niche values.
países Todo or comma-separated country codes matched against Pinterest targeting countries.
idiomas / language Todo or comma-separated language codes.
gender Audience gender value where available.
sitio web / technologies Store technology filters, for example Shopify-related values from the dashboard.
mediatype vídeos, video, imágenes, o imagen.
pagetype producto, productos, collection, o colecciones.
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.
precio mínimo, precio máximo Product price range when Shopify product data is available.
de, a Ad start/creation date range.
desde la última vez que se le vio, tolastseen Last-seen date range.
producto_de, producto_a Product or collection creation date range.
mindays, días máximos Days-running range based on the ad start date.
clasificación / clasificar fecha de hallazgo, comments, likes, shares, reactions, última conexión, o días corriendo.
dirección de ordenación asc o desc; defaults to desc.
filtro de puntuación publicitaria / adscore ganador, escalado, o pruebas; 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.