Un'API della libreria di annunci per gli annunci Meta, Google e TikTok

Ogni ricerca usa la stessa chiave, la stessa paginazione e gli stessi codici di errore, e risponde in JSON. Chiamala da uno script o dalla tua app, oppure lascia che un agente IA la chiami tramite il server MCP.

Annunci Meta, annunci Google e TikTok in un'unica API per librerie di annunci

Dietro la chiave ci sono tre dataset di annunci. Gli annunci Meta coprono Facebook e Instagram, e li cerchi per parole nel testo, nel marchio o nella landing page. Gli annunci Google comprendono annunci di testo, immagine e video, con un filtro per la rete su cui sono girati, YouTube incluso. Un annuncio video rimanda all'Ads Transparency Center di Google, dove viene riprodotto. TikTok ti dà annunci e post organici in un'unica ricerca, con le loro visualizzazioni, i like e le condivisioni.

Ogni annuncio rimanda al marchio che c'è dietro: la pagina dell'inserzionista e, quando esiste, il negozio Shopify collegato. Così puoi passare da un annuncio al negozio, poi al traffico e ai più venduti del negozio, con la stessa chiave.

L'elenco completo si trova nella Documentazione API. Se preferisci cliccare piuttosto che scrivere codice, le stesse ricerche funzionano nel nostro strumento spia per annunci.

Ottieni una chiave API e invia la tua prima richiesta

1. Crea un account, conferma la tua email e scegli un piano a pagamento: è da lì che parte l'API.
2. Apri Chiavi API nella tua dashboard e crea una chiave. Copiala subito: viene mostrata una sola volta.
3. Invia la chiave a ogni richiesta, nell'header X-API-Key o come bearer token.

Questa richiesta trova annunci video di skincare ancora attivi. Funziona con ogni piano a pagamento:

# Search Meta ads
curl "https://api.sellwinners.com/v1/ads?search=skincare&status=active&mediaType=video&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/ads Parametri e campi nella documentazione

La risposta contiene un requestId, gli annunci in data e un oggetto pagination. In ogni annuncio, media ha la miniatura e gli URL del video, content il titolo, il testo, l'invito all'azione e la landing page, e advertiser la pagina che lo pubblica. metrics conta i duplicati e aggiunge copertura e spesa stimata.

Una ricerca Meta restituisce un annuncio per marchio, così un inserzionista non può riempire la pagina. Aumenta maxAdsPerBrand (fino a 15, o 0 per nessun limite) per vederne di più di ciascuno.

Filtra per nome

Gli annunci Meta accettano 111 filtri con nome, inviati come parametri di query in una GET o come campi del corpo in una POST. Tra i più comuni ci sono minDaysRunning, countries, cta e minDuplicates. Un nome scritto male riceve un 400 validation_failed che elenca i nomi accettati dall'endpoint, così un errore di battitura non restituisce mai annunci non filtrati.

# Search Meta ads with advanced filters
curl -X POST "https://api.sellwinners.com/v1/ads/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "skincare", "status": "active", "mediaType": "video", "countries": ["US"], "minDaysRunning": 30, "sortBy": "reach", "limit": 10}'

POST /v1/ads/query Parametri e campi nella documentazione

La copertura è quella nell'UE e nel Regno Unito, e la spesa è sempre una stima.

Tutti gli annunci di un marchio

Trova l'id inserzionista del marchio con GET /v1/lookup?q=allbirds.com&type=advertiser, poi elenca i suoi annunci, dai più longevi:

# Meta ads of one advertiser
curl "https://api.sellwinners.com/v1/advertisers/ADVERTISER_ID/ads?sortBy=longestRunning&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/advertisers/{advertiser_id}/ads Parametri e campi nella documentazione

La nostra pagina sulla ricerca nella libreria di annunci Meta descrive questa vista nell'app web, insieme al mix di formati e alle landing page del marchio.

Scorri i risultati

Le ricerche accettano limit (fino a 100) e page oppure offset. Per la pagina successiva, ripeti la richiesta con page più uno, oppure con offset più limit. Fermati quando hasMore è false.

La paginazione raggiunge i primi 5.000 risultati di una ricerca (per una ricerca di inserzionisti, i primi 100). Per andare oltre, aggiungi filtri o cambia l'ordinamento. Alla maggior parte delle ricerche serve la parte alta di un elenco ben filtrato, non la pagina 200.

Limiti di frequenza e crediti per piano

1 credito = 1 risultato restituito: i dettagli di un marchio, un annuncio o una riga di un elenco. Un risultato vuoto è gratuito. Errori, rifiuti, lookup e valori dei filtri non costano nulla, e una chiamata a uno strumento MCP costa i risultati che restituisce, come l'API. Tutti i membri di un'area di lavoro, le sue chiavi, l'API e il server MCP condividono un unico insieme di crediti e un unico limite di frequenza. I crediti mensili si rinnovano alle 00:00 UTC del 1° di ogni mese; i crediti di ricarica acquistati nella pagina di fatturazione vengono riportati ai mesi successivi.

Ogni risposta riporta X-RateLimit-Remaining e X-Credits-Remaining, e X-Usage-Cost indica quanto è costata la chiamata, così il tuo codice può rallentare prima di essere rifiutato. Oltre il limite al minuto ricevi 429 rate_limited con un Retry-After in secondi. Quando i crediti mensili ed eventuali crediti di ricarica sono esauriti, ricevi 402 insufficient_credits finché i crediti non si rinnovano. GET /v1/usage mostra a che punto sei e non costa nulla. Maggiori dettagli nella sezione limiti di frequenza e crediti.

Cerca annunci da un agente IA con il server MCP

Il server MCP offre a un agente IA gli stessi dati sotto forma di strumenti, tramite HTTP streamable, con la tua chiave API nell'header X-API-Key. La pagina del nostro Server MCP per agenti IA contiene l'URL del server e configurazioni pronte per Cursor, VS Code e Claude Desktop.

Per la ricerca sugli annunci l'agente chiama soprattutto search_ads, scan_ad per aprire un annuncio, search_google_ads_library, search_tiktok_library e search_advertisers. Chiedi a parole tue: «Trova annunci video di skincare ancora attivi negli Stati Uniti, apri i tre attivi da più tempo ed elencane gli hook». L'agente lo trasforma in filtri e chiamate. Le regole dei piani sono le stesse dell'API.

In cosa differisce dall'API della Libreria inserzioni di Meta

SellWinners non è l'API ufficiale di Meta. È un servizio indipendente e non è affiliato a Meta. Meta gestisce la propria API della Libreria inserzioni. Nella sua pagina sugli strumenti della Libreria inserzioni («Meta Ad Library tools» nel suo Centro per la trasparenza), Meta afferma che l'API «consente un'analisi più approfondita delle inserzioni su temi sociali, elezioni o politica, nonché delle inserzioni pubblicate nell'UE e nei territori associati», e parla di «utenti autorizzati». Abbiamo verificato quella pagina il 19 ottobre 2026.

I due servono a lavori diversi. L'API di Meta è gestita da Meta, secondo le regole di Meta. SellWinners è costruito per la ricerca e-commerce:

• Una sola chiave per gli annunci Meta, Google e TikTok, con la stessa paginazione, gli stessi errori e gli stessi limiti.
• Annunci legati al marchio che c'è dietro: la pagina dell'inserzionista, e il negozio Shopify quando esiste.
• Filtri che ti aiutano a individuare gli annunci che restano attivi: giorni di attività, duplicati, invito all'azione e posizione dell'annuncio.
• Un server MCP, così un agente IA può eseguire le ricerche per te.
• La copertura per gli annunci mostrati nell'UE e nel Regno Unito, e una spesa stimata.

Se il tuo lavoro riguarda annunci politici o su temi sociali, l'API di Meta è fatta per questo. Se vuoi vedere cosa pubblicano i marchi e-commerce su tre reti, e quali negozi ci sono dietro gli annunci, è il lavoro che fa SellWinners.

Dove andare adesso

Parti da una domanda, per esempio quali marchi di skincare tengono attivo lo stesso video da un mese. Eseguila una volta con curl, poi spostala nel tuo codice. Per approfondire una piattaforma, apri la libreria di annunci TikTok, la libreria di annunci Google o la ricerca inserzionisti. Per seguire un concorrente, puoi monitorare nel tempo gli annunci di un marchio. Per il mercato più ampio, guarda come si confrontano gli strumenti spia per annunci.

Cerca annunci in Esplora