Documentazione dell'API di dati e-commerce

L'API di SellWinners ti offre dati di intelligence su e-commerce e pubblicità tramite HTTPS, con risposte JSON: negozi Shopify con i loro prodotti e il loro traffico; prodotti dei negozi con prezzo, stime di vendita, recensioni e annunci; annunci Meta, Google e TikTok; inserzionisti; e le email che inviano i marchi. Ogni endpoint è disponibile anche per gli agenti IA tramite il nostro server MCP ospitato. Questa pagina tratta l'autenticazione, il formato delle risposte, la paginazione, l'ordinamento e i filtri, i limiti di richieste e i crediti, gli errori e gli URL dei media, poi ogni endpoint con i suoi parametri e una richiesta di esempio, e gli strumenti del server MCP.

Guida rapida

1. Crea un account, conferma la tua email e scegli un piano a pagamento: l'API e il server MCP partono da lì.
2. Apri Chiavi API e crea una chiave. Copiala subito: viene mostrata una sola volta.
3. Fai la tua prima richiesta:

curl "https://api.sellwinners.com/v1/lookup?q=allbirds.com" \
  -H "X-API-Key: YOUR_API_KEY"

import requests

API = "https://api.sellwinners.com"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}

hit = requests.get(f"{API}/v1/lookup", params={"q": "allbirds.com", "type": "shop"}, headers=HEADERS).json()["data"][0]
shop = requests.get(f"{API}/v1/shops/{hit['shop']['id']}", headers=HEADERS).json()["data"]
print(shop["domain"], shop["traffic"]["monthlyVisits"])

const API = "https://api.sellwinners.com";
const headers = { "X-API-Key": process.env.API_KEY };

const found = await (await fetch(`${API}/v1/lookup?q=allbirds.com&type=shop`, { headers })).json();
const shop = (await (await fetch(`${API}/v1/shops/${found.data[0].shop.id}`, { headers })).json()).data;
console.log(shop.domain, shop.traffic.monthlyVisits);

Autenticazione

Invia la tua chiave API a ogni richiesta nell'header X-API-Key, oppure come bearer token:

X-API-Key: YOUR_API_KEY
# or
Authorization: Bearer YOUR_API_KEY

Le chiavi iniziano con ak_live_. Tienile segrete: non inserirle nel codice front-end o in repository pubblici. Puoi creare più chiavi (una per app o ambiente) e revocare qualsiasi chiave dalla tua dashboard; una chiave revocata smette di funzionare immediatamente.

Risposte

Ogni risposta è in JSON. Contiene un requestId e il risultato in data: una lista per le ricerche e gli elenchi, un oggetto per una singola scheda. Le liste aggiungono un oggetto pagination, e alcune risposte aggiungono meta.

{
  "requestId": "req_8f2c1a9b4d7e6f3a2b1c0d9e",
  "data": [
    {
      "id": "facebook_1203948571620394",
      "platform": "facebook",
      "status": "active",
      "daysRunning": 42,
      "media": { "type": "video", "thumbnailUrl": "https://api.sellwinners.com/v1/media/file/b7a0.jpg", "mediaUrl": "https://api.sellwinners.com/v1/media/file/4c1e.mp4" },
      "advertiser": { "id": "104958372615", "name": "Glow Labs", "liveAdsCount": 86 },
      "content": { "title": "Glass skin in 14 days", "body": "Dermatologist tested.", "callToAction": "Shop now", "landingPageUrl": "https://glowlabs.example/serum" },
      "metrics": { "reach": 184000, "estimatedSpend": 1656, "duplicates": 3 },
      "audience": { "targetedCountries": ["FR", "DE"], "mainCountry": "FR" },
      "rank": { "currentRank": 4, "rankDelta": -2, "improvementPct": 0.3333 },
      "flags": { "isEuAd": true },
      "extra": { "shop": { "domain": "glowlabs.example" } }
    }
  ],
  "pagination": { "page": 1, "limit": 25, "total": 1840, "totalPages": 74, "hasMore": true }
}

Le schede sono oggetti annidati: un annuncio ha media, advertiser, content, metrics, audience, rank e flags, e negozi, inserzionisti, annunci Google, elementi TikTok ed email sono raggruppati allo stesso modo. Un valore non noto è null. Gli altri campi senza una posizione fissa sono conservati in extra. L'esempio qui sopra è abbreviato.

In un annuncio, content.title è il titolo e content.callToAction è un testo leggibile come «Shop now». metrics.estimatedSpend è la stima della spesa della fonte quando esiste (un singolo annuncio da /v1/ads/{adId} la legge), altrimenti copertura x 9 / 1000 (9 USD ogni 1.000 persone raggiunte); una stima della spesa mantiene due decimali sotto i 10 USD ed è in dollari interi da 10 USD in su. rank.rankDelta è la posizione attuale meno quella precedente, quindi un valore negativo significa che l'annuncio è salito, e rank.improvementPct è una frazione (0,25 è un quarto).

I report sulle posizioni del monitoraggio marchi (/ad-rank, /scaling-ads, /v1/workspace/scaling-ads e lo strumento MCP get_brandtracker_scaling_ads) aggiungono i propri metrics: lì metrics.rankDelta è la posizione precedente meno quella attuale (positivo: posizioni guadagnate) e metrics.improvementPct è la frazione della posizione precedente guadagnata, come in un annuncio (0,875 è l'87,5%). In un singolo annuncio, metrics.reachDelta1d, reachDelta7d e reachDelta30d sono calcolati dal suo storico della copertura. I negozi indicano le loro categorie: catalog.mainCategory negli elenchi, più catalog.categories in un singolo negozio.

In un annuncio Google, media.type e media.format sono text, image o video, e media.url è l'immagine dell'annuncio: per un annuncio video, la sua miniatura (non c'è alcun file video). transparencyUrl è l'annuncio nell'Ads Transparency Center di Google, dove un annuncio video viene riprodotto; è null quando l'annuncio non ha id Google. network è search, youtube, shopping, maps o other, e lo stesso vale per i valori di extra.networks.

Modifiche del 19 ottobre 2026:

• Il media.format di un annuncio Google era un codice di formato e ora è text, image o video, il suo media.type può essere text o video, e extra.networks usa i nomi in minuscolo di network.
• Un media.url di Google non è mai un file video, anche quando media.type è video.
• Nel filtro formats di Google, image ora indica gli annunci con immagine (prima indicava gli annunci di testo), quindi usa text per gli annunci di testo. I codici precedenti static_image, html5_iframe e responsive_display, e i loro nomi brevi, sono ancora accettati.

Lo status di un annuncio Google è active solo finché Google mostra l'annuncio: uno che Google non mostra da più di 7 giorni è unknown. daysRunning conta i giorni da firstSeenAt a lastSeenAt, entrambi inclusi; extra.servedDays è il conteggio della fonte dei dati, che continua anche dopo che un annuncio si ferma. I filtri concordano con ciò che mostra ogni annuncio: status=active tiene gli annunci che Google ha mostrato negli ultimi 7 giorni e status=inactive gli annunci che la fonte dei dati segna come fermati, quindi un annuncio unknown non rientra in nessuno dei due; minDaysRunning e maxDaysRunning tengono gli annunci il cui daysRunning rientra nell'intervallo. Un elenco di questo tipo ha pagination.total null, e quando pochi degli annunci letti corrispondono termina in anticipo, con meta.partial e un avviso.

Senza testo di ricerca, sortBy=relevance elenca i più recenti; sortBy=reach accetta solo order=desc. Con status=active, sortBy=reach elenca pochi annunci: in ordine di copertura i primi annunci sono per lo più quelli che Google ha smesso di mostrare, quindi ordina per più recenti per avere gli annunci che Google mostra adesso (lo dice il suo avviso). Gli annunci Google non accettano sortBy=longestRunning: la fonte dei dati lo calcola su giorni che continuano dopo che un annuncio si ferma, quindi elencava annunci che Google non mostra più, e risponde 400 con questa motivazione.

extra.startIsFloor segnala un annuncio visto per la prima volta il 31 maggio 2018, il primo giorno dei dati sugli annunci di Google, quindi potrebbe essere più vecchio. audience.countries elenca ogni paese del pubblico, con una percentage solo per un annuncio mostrato in un solo paese; remarketing e interest sono null quando non sono noti.

Google riporta una copertura solo per alcuni degli annunci mostrati nell'UE, spesso solo come 10.000.000, il massimo della sua scala (10 milioni o più): la maggior parte degli annunci non ne ha, e nullReasons dice perché reach.value è null (not_reported: un annuncio mostrato nell'UE per cui Google non ne riporta alcuna; eu_only: un annuncio mostrato altrove), tranne per una copertura che il piano esclude. extra.networks è l'elenco delle piattaforme dell'annuncio secondo la fonte dei dati, che potrebbe non citare network. extra.shop.google contiene i totali Google del sito web dell'inserzionista; per un sito che non è un negozio (un app store, un social network, un accorciatore di link) advertiser.domain e websiteId sono null.

Modifiche del 20 ottobre 2026:

• Un dominio (GET /v1/shops/{domain}, il lookup, un domain TikTok, il profilo del concorrente) è il sito con esattamente quel dominio, anche fuori dall'indice dei negozi; uno che la fonte dei dati non raggiunge risponde 404.
• GET /v1/lookup ordina i risultati dal migliore: il sito del dominio stesso, le sue pagine Facebook (prima la pagina principale), poi le pagine con un nome simile; per un nome, il sito del marchio e le sue pagine (prima la pagina principale), poi i negozi e le pagine trovati tramite il nome.
• Una volta trovato il sito del marchio, un negozio o una pagina che contiene il nome solo all'interno di una parola viene escluso, e un sito con quel nome è esatto solo quando pubblica annunci; altrimenti una corrispondenza per nome è esatta solo con traffico o annunci. Le pagine ufficiali con un altro nome e senza annunci attivi vengono dopo le pagine trovate tramite il nome.
• Il signals.activeAdsSource della riga di un negozio indica da dove provengono i suoi activeAds: page (gli annunci attivi della sua pagina principale, letti al momento, nella riga del negozio stesso) o index (il conteggio dell'indice dei negozi, che può essere meno recente).
• Una ricerca negozi per dominio (searchType=domain) elenca per primo il sito esatto, con extra.exactDomainMatch (e extra.inShopIndex false quando l'indice dei negozi non lo include).
• Per un sito che non è un negozio (un app store, un sito social o di messaggistica, un accorciatore di link o un redirect di tracciamento), l'extra.domain della riga di un inserzionista è null, la scheda di un inserzionista lo indica in extra.nonShopSite, omette extra.platforms e ricava linkedShops dalle sue landing page (fromLandingPages), e un annuncio non ha shops.
• Le date e ore che la fonte dei dati invia senza fuso orario sono in UTC e ora vengono inviate con +00:00.
• Nelle statistiche delle email, emailsByDayOfWeek ha come chiave il numero del giorno: 0 è domenica, 6 sabato.
• Le righe del lookup possono contenere nullReasons, e la scheda di un negozio meta.partial quando non è stato possibile leggere le cifre della sua riga negli elenchi.

Altre modifiche del 20 ottobre 2026 (TikTok):

• Il publishedAt di un elemento TikTok è in UTC. Era in ritardo di 1 o 2 ore, quindi un post pubblicato nelle ultime ore di un giorno UTC compariva il giorno dopo, con un daysRunning inferiore di un giorno.
• I filtri concordano con esso: publishedAfter e publishedBefore sono in UTC (una data da sola indica l'inizio del suo giorno, e publishedBefore elenca i post precedenti), minDaysRunning e maxDaysRunning contano dal giorno UTC, come fa daysRunning, e sortBy=longestRunning parte dal 31 agosto 2016, alle 22:00 UTC.

Altre modifiche del 20 ottobre 2026 (annunci Google):

• GET /v1/google-ads, POST /v1/google-ads/query e lo strumento MCP non accettano sortBy=longestRunning (né daysRunning) e rispondono 400 con la motivazione: la fonte dei dati lo calcola su giorni che continuano dopo che un annuncio si ferma, quindi elencava annunci che Google non mostra più.
• Una ricerca Free i cui primi risultati restano pochi con status=active risponde con meta.partial e un avviso che indica quanti degli annunci letti elenca.
• In extra.shop, un sito senza dati di traffico non ha monthlyVisits (era 0), un trafficGrowth30d compare solo accanto a visite superiori a 0, e extra.shop.google omette un totalReach o un weeklyReach pari a 0 (mai riportati) e, quando non conta alcun annuncio, i conteggi pari a 0.
• Un annuncio Google salvato in una bacheca si legge allo stesso modo.

Altre modifiche del 20 ottobre 2026 (negozi):

• In GET /v1/shops/{shopId}, advertising.summary.reach30d è la copertura UE degli ultimi 30 giorni, sommata per data (era il totale dall'inizio del monitoraggio, ora totalReach), spend30d è quella copertura x 9 / 1000, extra.estimatedSpendUsd è la spesa dall'inizio del monitoraggio e extra.adsLaunched30d somma gli annunci lanciati negli ultimi 30 giorni; sono tutti null per un negozio senza copertura nell'UE o nel Regno Unito.
• Le schede dei negozi, i negozi in elenco e le statistiche delle email contengono nullReasons, un percorso di campo associato al motivo per cui è null: not_shopify (vendite e prodotti sono stimati solo per i negozi Shopify), no_estimate, not_measured, eu_uk_only, not_linked (nessun profilo TikTok), not_on_tp, no_reviews, none_found.
• Una stima delle vendite pari a zero accanto alle unità vendute è null, nelle schede, negli elenchi e nello storico delle vendite, il cui period=week ha un punto per settimana.
• traffic.growth30d è una frazione (-0,1543 è -15,4%), e traffic.history parte dal primo mese con visite.
• catalog.mainCategory deriva dagli id delle categorie (la più specifica del ramo principale), con catalog.categoryLeaves e productsCountCapped (25.001 è il tetto della fonte dei dati: 25.000 o più).
• Una pagina Trustpilot senza recensioni ha una valutazione null.
• tiktok.matchedBy è socials o handle quando le cifre TikTok provengono dai profili social del negozio o da un profilo trovato tramite il suo handle (una corrispondenza, non un collegamento della fonte dei dati).
• advertising.mainPageActiveAds indica gli annunci attivi della pagina principale (la lettura della sua panoramica degli annunci, come la mostra la sua pagina principale in linkedAdvertisers; solo in mancanza di questa, il conteggio mostrato negli elenchi dei negozi) e linkedAdvertisers[].rank la posizione della pagina.
• I negozi simili escludono il negozio stesso e i suoi siti, e ogni pagina viene completata con negozi presi più in basso nell'elenco (offset e limit contano l'elenco senza di essi).
• I prodotti ordinati per popolarità mettono per primi i più venduti del negozio (meta.order).
• Le email e le statistiche delle email di un negozio contano ogni tipo di campagna, e le loro cifre a 90 giorni sono null quando non sono note.
• Un ordinamento per vendite elenca una riga per negozio Shopify (extra.sharedSalesWith), e sortBy=estMonthlySales&order=asc esclude i negozi senza stima.

Altre modifiche del 20 ottobre 2026 (cifre dei negozi):

• Un ordinamento per vendite di GET /v1/shops continua a leggere oltre i domini che unisce in una riga per negozio Shopify (si fermava dopo le prime righe), unisce i domini di un negozio anche più in basso nell'elenco, e il suo pagination.total è null finché l'elenco non viene letto fino alla fine; sortBy=estMonthlySales&order=asc parte da una stima di 100 USD (minMonthlySales 100).
• Una stima delle vendite inferiore a 0,50 USD per unità venduta è null (no_estimate), nelle schede, negli elenchi e nello storico delle vendite.
• traffic.monthlyVisits è null per un sito non ancora misurato e traffic.growth30d lo è quando il mese precedente non aveva visite (not_measured); il growth30d di un social network deriva dal suo storico dei follower quando la fonte dei dati dà 0 o nessun valore, e 0 follower è null (not_measured).
• I negozi in elenco indicano perché catalog.productsCount e sales.unitsSold sono null.
• extra.storeWide segnala un dominio con 0 visite che riporta le vendite del suo negozio (uno 0 misurato, oppure un altro dominio del negozio, indicato in extra.sharedSalesWith, ha le visite; Free omette il nome nella scheda di un negozio).
• advertising.mainPageActiveAds indica gli annunci attivi della pagina principale come li legge la sua panoramica degli annunci (solo in mancanza di questa, il conteggio mostrato negli elenchi dei negozi).
• I negozi simili escludono anche i negozi del marchio del negozio, e extra.similarIndexed è false per un negozio che l'indice di somiglianza non contiene.
• catalog.mainCategory mantiene l'etichetta della fonte dei dati solo quando è il nome di una categoria.
• Un file multimediale collegato in una risposta e che la fonte dei dati non ha più risponde 200 con un corpo vuoto e X-Media-Missing: true.

Altre modifiche del 20 ottobre 2026 (inserzionisti e annunci Meta):

• La copertura di un inserzionista è la copertura nell'UE e nel Regno Unito, nelle finestre della ricerca inserzionisti: advertising.reach30d, extra.reach14d, reach90d e totalReach sono null per una pagina senza annunci nell'UE o nel Regno Unito e senza copertura, o per una finestra che la fonte dei dati non ha conteggiato, e nullReasons indica il motivo (eu_uk_only, not_measured); una pagina creata all'interno di una finestra ha tutta la sua copertura in essa (erano 0).
• In GET /v1/advertisers/{advertiserId} la copertura è quella mostrata negli elenchi degli inserzionisti (veniva letta 30 rilevazioni prima, e le rilevazioni saltano dei giorni), le stime della spesa sono null insieme a essa, extra.avgSpendUsd14d è la spesa media giornaliera su 14 giorni, extra.avgActiveAds14d è la media a 14 giorni dei suoi annunci attivi (erano i suoi nuovi annunci di 14 giorni), dove la fonte dei dati non l'ha calcolata, per una pagina creata entro i 14 giorni a partire dai suoi annunci attivi letti dal suo primo giorno (extra.averagedFrom), altrimenti null, e i conteggi dei nuovi annunci di una pagina creata all'interno della finestra contano tutti i suoi annunci.
• advertising.countryDistribution è la quota dei suoi annunci attivi destinati a ciascun paese (un annuncio è destinato a più paesi), extra.reachCountries contiene la quota di ciascun paese nella copertura UE, extra.platforms.meta contiene gli annunci della pagina stessa (conteneva quelli della pagina principale del negozio), un conteggio TikTok o Google senza cifra viene omesso, extra.mainLandingPages ripiega sull'anteprima delle landing page di una nuova pagina, e i lastAds di una pagina i cui annunci la ricerca annunci non ha ancora acquisito sono gli ultimi elencati nella sua riga inserzionista, con meta.indexing, come in GET /v1/advertisers/{advertiser_id}/ads (con meta.liveAds).
• Novità: GET /v1/advertisers/{advertiserId}/history, gli annunci attivi della pagina e la copertura UE guadagnata, giorno per giorno.
• Un numero di follower Instagram pari a 0 è null (la fonte dei dati scrive 0 per una pagina senza un account che conosca).
• Il metrics.reach di un annuncio Meta e la sua spesa sono null per un annuncio non mostrato nell'UE o nel Regno Unito (eu_uk_only; erano 0 o null) e per un annuncio UE la cui copertura non è ancora conteggiata (not_measured; era 0), con le righe dei media che ne indicano il motivo in nullReasons.reach, media.type è carousel per un annuncio con più di un'immagine o un video, e extra.startIsFloor segnala un annuncio iniziato il 1° gennaio 2018, il primo giorno delle date degli annunci Meta della fonte dei dati.
• sortBy=adRank elenca per prima la posizione migliore (1), qualunque sia l'ordine.
• Un singolo annuncio (GET /v1/ads/{adId}) prende l'ultima copertura riportata dalla fonte dei dati e la relativa spesa, conta le variazioni della sua copertura per data finché il suo storico della copertura è aggiornato (altrimenti sono null), elenca le sue immagini e i suoi video come fa la sua riga di ricerca, compila advertiser.reach30d e pageAnalytics.instagramFollowersHistory, aggiunge pageAnalytics.reachHistory (la stessa serie di impressionsHistory) e dà il nome a un negozio che la scheda indica solo con il suo id (con il suo traffic null e nullReasons shops.traffic quando il sito non è misurato); i suoi audience.gender, ageMin, ageMax e metrics.aggregatedReach sono sempre null, perché la fonte dei dati non li riporta per un singolo annuncio.
• In una ricerca inserzionisti, sortBy=reach ordina per la copertura totale dall'inizio del monitoraggio e newAds per i nuovi annunci di 14 giorni.
• Il targeting di un annuncio Meta indica perché la sua copertura è null: eu_uk_only solo per un annuncio che non è destinato ad alcun paese dell'UE né al Regno Unito; uno che è destinato a uno di essi, o il cui targeting non è ancora noto, è not_measured nei suoi primi 7 giorni e not_reported dopo (erano eu_uk_only), negli elenchi degli annunci, nelle righe dei media e nel singolo annuncio.
• Un singolo annuncio legge i suoi storici della copertura e della spesa come una sola serie, una rilevazione al giorno (anche le sue variazioni), e prende l'ultima rilevazione e la spesa di quella serie quando la copertura della scheda ne è più del doppio e la serie arriva fino all'ultimo giorno dell'annuncio; il suo media ripiega sul primo file elencato, e advertiser.totalReach sulla copertura UE dei dettagli della pagina.
• La scheda di un inserzionista la cui riga non riporta alcuna copertura, accanto a dettagli della pagina che ne riportano una, prende la loro copertura (extra.totalReach, la relativa spesa, advertising.reach30d calcolato su di essa), le sue quote extra.reachCountries non vengono mai arrotondate a 0, extra.averagedFrom non è mai precedente al giorno in cui la pagina è stata creata, e il suo storico giornaliero (extra.history, GET /v1/advertisers/{advertiserId}/history) omette le rilevazioni che la fonte dei dati ha mancato (una serie di zeri di 14 giorni o meno tra rilevazioni superiori a 0).
• Un singolo annuncio che prende la rilevazione della sua serie conserva la copertura della scheda in extra.recordReach (la cifra mostrata negli elenchi degli annunci); in una ricerca inserzionisti, una riga che non riporta copertura UE accanto a dettagli della pagina che ne riportano una prende la loro copertura, come fa la sua scheda; e GET /v1/advertisers/{advertiserId}/history conserva le rilevazioni pari a 0 di una pagina che ora non ha annunci UE e che ha guadagnato copertura prima dei giorni richiesti (non ne ha guadagnata; venivano omesse come not_measured).
• Con Free, un annuncio la cui copertura non è nota ne indica il motivo come nei piani a pagamento; solo una copertura che il piano esclude non ha un motivo.

Altre modifiche del 20 ottobre 2026 (stime della spesa):

• Una spesa stimata inferiore a 10 USD mantiene due decimali: una copertura di 140 a 9 USD ogni 1.000 persone raggiunte fa 1,26 (era 1), e una media giornaliera mantiene i propri centesimi; da 10 USD in su una stima della spesa è in dollari interi (una copertura di 2.000 fa 18).
• Questo vale per extra.estimatedSpendUsd e extra.avgSpendUsd14d della scheda di un inserzionista, per advertising.summary.spend30d e extra.estimatedSpendUsd di un negozio, per metrics.estimatedSpend di un annuncio Meta, e per statistics.euData.estimatedSpend30d di un monitoraggio marchi e l'estimatedSpend di ogni punto di /time-series (entrambi avevano due decimali a qualsiasi importo), sia nell'API sia negli strumenti MCP. Dove la cifra della fonte dei dati è proprio quella stima in dollari interi, mantiene i centesimi allo stesso modo.

Altre modifiche del 20 ottobre 2026 (copertura degli inserzionisti e storico giornaliero):

• GET /v1/advertisers/{advertiserId} aggiunge extra.reachScope: outside_eu_uk per una pagina la cui copertura per paese è stata vista per lo più fuori dall'UE e dal Regno Unito (la fonte dei dati riporta anche la copertura di alcuni annunci mostrati altrove; la sua copertura e le stime ricavate da essa sono allora quella copertura, non la copertura UE), altrimenti eu_uk. Il suo extra.avgSpendUsd14d per una pagina creata entro i 14 giorni è la sua spesa sull'intero numero di giorni dalla sua creazione (almeno uno; era la sua copertura a 14 giorni su 14 giorni quando la riga inserzionista ne aveva una).
• L'extra.history della scheda di un inserzionista e GET /v1/advertisers/{advertiserId}/history partono dal giorno in cui la pagina è stata creata; extra.history.newAds omette i suoi 0 dei giorni che la fonte dei dati ha mancato, extra.followersHistory e i like e i follower di pageAnalytics di un annuncio omettono uno 0 tra due rilevazioni superiori a 0 o di uno di quei giorni, e le stime giornaliere della spesa mantengono due decimali sotto i 10 USD.
• Una pagina i cui annunci attivi non sono ancora in nessun elenco ha meta.indexing nella sua scheda, e una prima pagina vuota di GET /v1/advertisers/{advertiser_id}/ads con meta.indexing e meta.liveAds.
• Un singolo annuncio (GET /v1/ads/{adId}): extra.spendHistory parte dal giorno in cui l'annuncio è iniziato, ogni spendUsd con due decimali sotto i 10 USD; advertiser.totalReach non è mai inferiore all'ultima rilevazione di pageAnalytics.reachHistory (extra.pageRecordReach contiene allora il totale della scheda, quello mostrato negli elenchi degli inserzionisti); extra.recordSpend è la spesa di extra.recordReach; extra.reachScope e extra.pageReachScope indicano dove è stata vista la maggior parte della copertura dell'annuncio e di quella della sua pagina.

Altre modifiche del 20 ottobre 2026 (monitoraggio marchi):

• In GET /v1/brandtrackers e GET /v1/brandtrackers/{id}, uno 0 di advertising.newAdsLastDay accanto a lanci negli ultimi 7 giorni viene verificato rispetto ai lanci del negozio di ieri: il loro conteggio, oppure null (not_measured) se non c'è una rilevazione di quel giorno; un elenco verifica al massimo 20 marchi per chiamata, quelli della pagina richiesta.
• In /top-ads e /v1/workspace/top-ads, metrics.totalReach è la copertura UE dell'annuncio: null per un annuncio mostrato fuori dall'UE e dal Regno Unito (eu_uk_only) o per un annuncio UE non ancora conteggiato (not_measured), con nullReasons, e ultimo in un ordinamento per copertura (era 0).
• /testing calcola le sue statistiche sulla copertura sugli annunci la cui copertura è nota, con nullReasons stats.reach per un gruppo che non ne ha nessuno.
• In /hooks, /transcripts, /landing-pages e negli hook e nelle landing page dell'area di lavoro, un totalImpressions pari a 0 è null con il nuovo motivo no_eu_reach (nessuna copertura UE o del Regno Unito conteggiata per i suoi annunci; not_measured con euOnly), ultimo nel suo ordinamento.
• In /ad-rank, /scaling-ads e /v1/workspace/scaling-ads, quando lo storico delle posizioni di un annuncio inizia all'interno di una finestra di 14 o 30 giorni, metrics.previousRank e rankDelta contano dalla sua rilevazione più vecchia in quella finestra: metrics.since è quel giorno e meta.windowNote lo indica, e una cifra che non si può fornire è null con nullReasons.
• In /partners, isOwnPage è true per la pagina principale del negozio, per le sue pagine ufficiali con un nome simile a quello del marchio e per una pagina che ha il nome del marchio (anche i creator possono essere classificati come ufficiali), e una copertura o una spesa null ha nullReasons.
• La prima pagina di /ads con adCopyHashes ha meta.latestAdDate e dataFreshnessLagDays, e con status=active meta.stoppedCount.
• /demography è il pubblico nell'UE e nel Regno Unito, e un paese sotto un decimillesimo del primo passa da countryDistribution a otherCountries.
• /ad-copy-evolution e /headline-evolution hanno un punto per ogni giorno registrato (0 quando il testo non è stato usato, null in un giorno tagliato ai testi che conserva), ordinano i testi in base al giorno più recente e omettono i giorni che la fonte dei dati ha letto male (annunci attivi sotto un decimo dei giorni circostanti, per un giorno o 2 o 3 di fila, o molti meno testi rispetto ai giorni su entrambi i lati), come indica meta.periodNote; meta.recordedDays conta i giorni. Anche gli annunci attivi settimanali e mensili di /time-series omettono 2 o 3 rilevazioni di questo tipo di fila.

Altre modifiche del 20 ottobre 2026 (report del monitoraggio marchi, lookup e copertura Google):

• In /ad-rank, /scaling-ads e /v1/workspace/scaling-ads ogni posizione di una riga deriva dallo storico delle posizioni dell'annuncio: metrics.currentRank è la sua rilevazione del giorno in cui è stata letta la posizione nella libreria di annunci (la posizione mostrata da /top-ads; la libreria può essere un giorno indietro rispetto allo storico), altrimenti la sua rilevazione più recente, la trajectory termina in quel giorno, e se non c'è una rilevazione nel giorno in cui inizia la finestra conta la rilevazione più vecchia al suo interno (la variazione della fonte dei dati sulla finestra non viene più usata).
• I primi 50 annunci della libreria di annunci (10 per marchio quando si considerano più marchi) vengono riordinati in base a queste cifre: un annuncio che secondo esse ha guadagnato meno di minRankDelta, o si posiziona sotto maxCurrentRank, viene escluso (un annuncio il cui storico delle posizioni non dà alcun guadagno, secondo il conteggio della libreria di annunci), pagination copre gli annunci conservati e meta.rankNote indica cosa è stato letto ed escluso, anche tra più marchi.
• Una /time-series giornaliera (e il graph della panoramica) è null in un giorno i cui annunci attivi la fonte dei dati ha letto male (sotto un decimo dei giorni su entrambi i lati; il giorno più recente resta come letto, anche nelle evoluzioni dei testi), e così i suoi lanci, e lo sono anche i lanci del giorno successivo quando sono quasi tutti i suoi annunci attivi; settimane e mesi omettono quei lanci, e leftOut elenca i giorni. /landing-page-evolution omette quei giorni da ogni pagina, e la rilevazione di una pagina inferiore a un decimo delle rilevazioni su entrambi i lati, come indica il suo meta.periodNote, con il giorno a cui arriva lo storico quando è in ritardo.
• Un gruppo di /testing senza copertura conteggiata ha nullReasons stats.reach no_eu_reach, a meno che uno dei suoi annunci non sia ancora conteggiato (not_measured) o che tutti siano stati mostrati fuori dall'UE e dal Regno Unito (eu_uk_only); la copertura e la spesa mancanti di una riga di /partners sono not_measured solo nei 7 giorni successivi al suo launchDate, no_eu_reach dopo.
• /creatives indica come carousel un annuncio con più immagini o video (era unknown).
• In GET /v1/lookup, il signals.monthlyVisits di un negozio è null per un sito non ancora misurato (nullReasons not_measured; era 0), gli annunci attivi della riga del negozio esatto (con ogni type, anche shop) sono quelli della sua pagina principale come li legge la sua panoramica degli annunci, il suo mainPageActiveAds, e le righe delle pagine del negozio leggono i propri allo stesso modo, il signals.monthlyVisits di un marchio monitorato (e il suo totalTraffic in GET /v1/brandtrackers) è null per un sito non ancora misurato e indica perché manca (not_measured, o no_shop per una pagina senza negozio), e con Free la copertura di una pagina che nessun piano ha mantiene il suo motivo (eu_uk_only, not_measured), anche negli elenchi degli inserzionisti.
• Un reach.value null di un annuncio Google ha nullReasons (not_reported, eu_only), tranne per una copertura che il piano esclude.
• In GET /v1/shops/{shopId}, advertising.mainPageActiveAds indica gli annunci attivi della pagina principale come li legge la sua panoramica degli annunci, il conteggio mostrato dalla sua pagina principale in linkedAdvertisers (era il conteggio dell'indice dei negozi, che può essere più vecchio di un giorno).

Altre modifiche del 20 ottobre 2026 (TikTok ed email):

• Il metrics.engagementRate di una riga TikTok è (like + commenti + condivisioni + salvataggi) / visualizzazioni, espresso come frazione (0,0513 è il 5,13%; le ricerche inviavano una percentuale e GET /v1/tiktok/library/{itemId} un'altra metrica), e daysRunning indica i giorni trascorsi dalla pubblicazione del post, in entrambi.
• metrics.rank è la posizione del post tra i post del suo creator (1 è la migliore).
• profile.followers è null quando la fonte dei dati non li ha conteggiati (inviava 0), content.category è null per la sua categoria generica All, e content.hashtags sono i tag del post, una volta ciascuno, scritti come nella sua descrizione e senza la punteggiatura che li segue (quelli di una scheda sono l'elenco della fonte dei dati, quelli di una riga di ricerca quelli della descrizione).
• Una scheda TikTok aggiunge profile.adsCount, organicCount e avgPostsPerWeek90d, compila profile.pageCreation, e ha links null per una riga della fonte dei dati senza alcun TikTok dietro (un id di meno di 15 cifre, o pubblicato prima del 31 agosto 2016, alle 22:00 UTC).
• sortBy=longestRunning parte dai primi TikTok (31 agosto 2016, 22:00 UTC).
• La scheda di un'email indica il tipo di promozione, la categoria e l'evento, e le visite mensili, gli annunci attivi, i prodotti e le cifre a 90 giorni del suo negozio sono quelli mostrati negli elenchi delle email, come lo sono le cifre last90Days delle statistiche delle email.
• Una riga email omette extra.shopActiveAds per uno 0 senza totale di annunci (i suoi nullReasons indicano not_measured), e allora il shop.marketing.activeAds della scheda di un'email è null; quando non è stato possibile leggere le cifre del negozio, la scheda ha meta.partial, un avviso e nullReasons failed per esse.
• Nello strumento MCP analyze_shop_emails, dominant classifica separatamente tipi di campagna, categorie, tipi di promozione ed eventi, ed esclude No Promotion e No Event.

Modifiche del 21 ottobre 2026:

• Le metrics.views di un elemento TikTok, e i suoi likes e saves che risultano 0 accanto a esse, sono null con nullReasons not_measured (e così engagementRate) quando la fonte dei dati ha inviato 0 visualizzazioni accanto a like, commenti, condivisioni o salvataggi superiori a 0, nelle ricerche e in GET /v1/tiktok/library/{itemId}; sortBy=views o likes con order=asc elenca i post con le visualizzazioni conteggiate (minViews 1).
• Una ricerca di annunci Meta con websiteIds elenca gli annunci dei negozi stessi: ogni annuncio della pagina principale di un negozio e delle sue pagine ufficiali con un nome simile, e gli annunci delle sue altre pagine (creator, editori e partner che hanno pubblicato i suoi annunci) che rimandano al negozio o a un sito del suo dominio; finché l'elenco non viene letto fino alla fine, il pagination.total della ricerca è allora il numero di annunci delle pagine del negozio cercate, una stima (pagination.totalEstimated true), oppure null quando la ricerca non indica nessuna delle sue pagine.
• Con sortBy=longestRunning, ogni blocco di annunci letto dalla fonte dei dati viene messo in ordine di daysRunning.
• In GET /v1/shops/{shopId}, advertising.activeAds conta gli annunci attivi delle pagine del negozio stesso (linkedAdvertisers[].isOwnPage), e nei suoi /products un più venduto in classifica ha il titolo, il prezzo e l'immagine di catalog.bestSellers (il prezzo di un più venduto può essere il più basso tra quelli delle sue varianti).
• Il traffic.monthlyVisits di un negozio (e il growth30d) è null con not_measured quando risulta 0 perché il suo storico è sceso a 0 accanto a una stima delle vendite superiore a 0 e a unità vendute, nelle schede, nei negozi in elenco e simili e nel lookup; un dominio di questo tipo resta comunque extra.storeWide.
• In GET /v1/ads/{adId}, advertiser.totalReach è l'ultima rilevazione di pageAnalytics.reachHistory finché quella rilevazione ha al massimo 2 giorni (extra.pageRecordReach contiene allora il totale della scheda), extra.advertiserTotalAds viene compilato dalle cifre in elenco della pagina (not_measured se mancano), gli aumenti di copertura a 7 e a 30 giorni di un annuncio iniziato all'interno della finestra sono tutta la sua copertura, e un aumento inferiore a quello di meno giorni è null (not_measured).
• Il statistics.ctaCount di un monitoraggio marchi indica ogni invito all'azione come fa content.callToAction («Shop now»).

Altre modifiche del 21 ottobre 2026 (negozi):

• In GET /v1/shops/{shopId}, advertising.history indica gli annunci attivi della pagina principale giorno per giorno con ogni piano (con Free contava quelli di tutte le pagine), e la documentazione specifica che copertura e spesa di advertising.summary, extra.adsLaunched30d, extra.totalAds ed extra.estimatedSpendUsd coprono tutte le pagine del negozio, mentre advertising.activeAds conta le sue pagine.
• Un catalog.productsCount di un negozio pari a 0 senza alcun prodotto elencato, accanto a visite, una stima delle vendite o unità vendute, è null con not_measured, nelle schede, nei negozi in elenco e nel meta.productsCount di GET /v1/shops/{shopId}/products; sortBy=productsCount esclude quei negozi, e con order=asc invia minProductsCount 1 a meno che non sia indicato un minimo di prodotti.
• Una ricerca di annunci Meta di un negozio ristretta a pagine che non sono sue (trackedPages) e che termina in anticipo ne indica il motivo in meta.warnings, senza chiedere di restringerla.
• GET /v1/filters/shops segnala in meta.warnings quando la fonte dei dati non elenca alcun valore, e indica gli elenchi che li forniscono.

Altre modifiche del 21 ottobre 2026 (paginazione, email ed elenchi di annunci):

• La paginazione di una ricerca inserzionisti non fallisce più quando la fonte dei dati non la prosegue (rispondeva 503, e riprovare non serviva): i suoi primi 100 risultati vengono letti in una sola chiamata, e la pagina che raggiunge la fine di ciò che si può leggere risponde hasMore false, con meta.partial true e un avviso che indica fin dove arriva la lettura della ricerca.
• Una pagina che inizia oltre il total esatto di una ricerca è vuota, con hasMore false.
• Una ricerca TikTok ordinata per views o likes con order=asc parte dai primi TikTok (31 agosto 2016, 22:00 UTC), come fa longestRunning, e le metrics.views di un elemento TikTok (e l'engagementRate) sono null con not_measured quando riportano meno visualizzazioni che like.
• Il content.bodyPreview e il bodyLength di un'email, e il content.body di una scheda, sono null con not_measured dove la fonte dei dati ha inviato il suo segnaposto per un corpo che non ha letto.
• Le date e ore che la fonte dei dati fornisce in UTC sono scritte allo stesso modo negli elenchi e nelle schede, con +00:00 e senza zeri finali nella frazione di secondo (2026-09-30T00:20:11.507+00:00; gli orari di creazione o modifica delle tue bacheche, dei tuoi preferiti, dei tuoi monitoraggi marchi e dei tuoi link di condivisione terminano con Z, come prima), e le righe delle email riportano gli id della loro categoria, del tipo di promozione e dell'evento, come fa la scheda dell'email.
• Ogni elenco paginato risponde con pagination.hasMore, e GET /v1/google-ads/facets/countries risponde con un oggetto pagination.
• Un corpo della richiesta che non è un JSON valido risponde 400 validation_failed con il messaggio «The request body is not valid JSON.» e details.position, il carattere in cui si interrompe.
• Negli elenchi di annunci Meta la copertura di una riga è la rilevazione dell'indice degli annunci, che può essere un giorno indietro rispetto alla scheda dell'annuncio, e i suoi aumenti di copertura sono null accanto a una copertura nota quando la fonte dei dati non ne elenca alcuno (not_measured), tranne su una finestra in cui l'annuncio è iniziato, dove ha guadagnato tutta la copertura che riporta la sua riga; in GET /v1/ads/{adId} anche un aumento null accanto a una copertura nota ha not_measured.

Modifiche del 22 ottobre 2026 (il piano Free):

• L'API e il server MCP sono passati ai piani a pagamento: una chiave di un account con il piano Free rispondeva 403 plan_not_eligible su ogni endpoint tranne GET /v1/account, con details.upgradeUrl, e non veniva conteggiato nulla. Con Free non si poteva creare alcuna chiave.
• Da allora il piano Free è cambiato: la sezione Il piano Free indica cosa include ora.
• Una chiave creata con un piano a pagamento viene conservata, e torna a funzionare non appena l'account torna a un piano a pagamento. I link di condivisione creati da un account con Free vengono sospesi allo stesso modo.

Altre modifiche del 22 ottobre 2026 (report e schede dei negozi):

• In GET /v1/shops/{shopId}/ad-ranking/series, rankDelta è la posizione finale meno quella iniziale (negativa quando l'annuncio è salito, come in ogni annuncio; erano le posizioni guadagnate) e improvementPercent ora è improvementPct, una frazione; ogni riga di /ad-ranking riporta le stesse due cifre sulla finestra della classifica in rank.
• Nel /activity/calendar di un marchio monitorato, in un giorno del calendario e in /activity/calendar/days, meta.partial è true o false, meta.partialSources indica le fonti lette in parte (in /calendar e in un giorno), e gli orari delle anteprime sono in UTC, anche quelli di un post TikTok.
• In GET /v1/shops/{shopId}/landing-pages/detail, activeAds ripiega sugli annunci della pagina, shareOfAds è linkedAdsTotal su shopActiveAds, snapshots conta i giorni in cui la pagina è stata acquisita, lifetimeAds e impressions sono stati rimossi (le impression erano di nuovo la copertura), una copertura pari a 0 è null con nullReasons.reach no_eu_reach, e i linkedAds hanno i campi delle righe di una ricerca di annunci.
• Il /feed di un negozio elenca i suoi annunci Meta, come fanno le sue ricerche di annunci.
• GET /v1/market/q4-overview accetta qualsiasi from e to all'interno della stagione.
• In /q4-season, winners elenca la chiave di ogni evento di vendita con le sue creatività, e gli url delle landing page riportano il loro schema.
• I rilevatori Shopify leggono un negozio al suo dominio senza www..
• GET /v1/advertisers/{advertiserId} e le landing page, il pubblico e il mix di media di un marchio monitorato riportano un giorno passato in meta.snapshotDate.
• Quando le statistiche degli annunci Meta di un negozio non si possono leggere in quel momento, GET /v1/shops/{shopId} risponde meta.partial true con un avviso: la sua copertura, le stime della spesa ricavate da essa e il suo mix di media e formati sono null con nullReasons failed, i suoi annunci per paese sono conteggiati come li fornisce la sua riga di ricerca, e la risposta non viene conservata, quindi la chiamata successiva li legge di nuovo (il profilo del concorrente riporta gli stessi meta.partial e avvisi).
• Una landing page sul dominio del negozio, o su un suo sottodominio, è toShop true in /v1/shops/{shopId}/advertisers e /advertisers/{advertiserId}/landing-pages; quando i domini del negozio non includono quel dominio, meta.domains lo elenca per primo a partire dalle landing page delle sue pagine (fromLandingPages true, un limite inferiore), e il shopAds di una pagina non è mai inferiore agli annunci attivi delle sue landing page sul negozio (shopAdsAtLeast true quando viene alzato).
• In GET /v1/tiktok/library/{itemId}, profile.latestPosts[].mediaUrl è il video del post, oppure null con nullReasons not_reported (era l'immagine di copertina).
• Una ricerca inserzionisti legge i suoi primi 100 risultati e indica che termina nella pagina che raggiunge il centesimo (hasMore false e l'avviso), non nella pagina vuota successiva.
• Una ricerca TikTok ordinata per views o likes con order=asc ora esclude i post le cui visualizzazioni non sono conteggiate (meno visualizzazioni che like), e il suo pagination.total è una stima (totalEstimated) finché l'elenco non viene letto fino alla fine; ogni altro ordinamento li elenca, con le visualizzazioni null.

Altre modifiche del 22 ottobre 2026 (elementi salvati e hook per annunci):

• Novità: GET /v1/boards/search trova ciò che hai salvato, in tutte le bacheche e nei tuoi preferiti, in base alle parole di ciò che mostra ogni copia salvata (ogni parola deve comparire, in qualsiasi ordine; maiuscole e accenti vengono ignorati), al suo id o al nome della sua bacheca, e accetta sourceType, boardId, savedFrom e savedTo; legge solo i tuoi elementi salvati, mai la fonte dei dati (MCP find_saved_items).
• Novità: POST /v1/tools/ad-hooks scrive tre brevi frasi di apertura per un annuncio del tuo prodotto, e GET /v1/tools/ad-hooks indica la tua disponibilità: nessun limite mensile nei piani a pagamento, e un limite al minuto (429 con Retry-After); la lettura della disponibilità non viene conteggiata (MCP write_ad_hooks).
• Il server MCP ha 64 strumenti.

Altre modifiche del 23 ottobre 2026 (viste salvate e filtri dei negozi):

• Novità: GET /v1/views elenca le ricerche che hai salvato nelle pagine elenco del sito, ciascuna con la ricerca che esegue (request: la ricerca, searchType, sortBy, order e i filtri con nome, come li accettano gli endpoint di ricerca); POST /v1/views ne salva una, PATCH /v1/views/{viewId} la rinomina, la sposta o la modifica e DELETE /v1/views/{viewId} la elimina. Leggono e scrivono solo le tue viste, mai la fonte dei dati (MCP list_saved_views).
• Le ricerche negozi accettano excludeCurrencies (codici valuta come EUR), socialNetworks (instagram o tiktok: un negozio con almeno uno dei due) e shopifyPlan (headless). trafficGrowth legge anche 90 giorni (min90, max90) e adsGrowth 7 giorni (min7, max7), oppure il period di una regola (last90d, last7d); min e max restano gli ultimi 30 giorni.
• Il server MCP ha 65 strumenti.

Altre modifiche del 23 ottobre 2026 (link ai prodotti):

• In GET /v1/shops/{shopId}, ogni elemento di catalog.bestSellers riporta handle e productUrl, la pagina del prodotto sul sito del negozio: l'indirizzo fornito dalla fonte dei dati quando è sul dominio del negozio (o su un suo sottodominio) o sul suo dominio myshopify, altrimenti https://<domain>/products/<handle> quando il suo handle è noto, altrimenti null.
• In GET /v1/shops/{shopId}/products, productUrl segue la stessa regola, quindi un indirizzo su un altro sito non viene più fornito, e handle è null quando non è una singola parte di un indirizzo.

Altre modifiche del 23 ottobre 2026 (righe dei negozi, negozi simili e prodotti):

• Il createdAt di un negozio (la scheda del negozio, le righe dei negozi e i negozi simili) è solo la data di creazione di un negozio Shopify. Per un sito fuori da Shopify la fonte dei dati fornisce il giorno in cui ha iniziato a monitorare il sito, non la sua creazione: createdAt ora è null (nullReasons tracking_date) e quel giorno è il nuovo trackedSince. Una data uguale o precedente al 1° gennaio 2000 è il segnaposto della fonte dei dati ed è null (not_reported).
• I catalog.bestSellers delle righe dei negozi riportano handle, productUrl (con la regola della scheda del negozio) e rank (1 è il più venduto), e le righe riportano profile.isHeadless e catalog.myShopifyDomain, come fa la scheda del negozio.
• Il googleAds.reach.value della riga di un negozio è null: le righe dei negozi non riportano la copertura Google, che si trova nella scheda del negozio (extra.googleAds.reach).
• I negozi simili (GET /v1/shops/{shopId}/similar, i similarShops della scheda) conservano il loro extra (logo, Trustpilot, storico delle vendite). Un elenco di simili che la fonte dei dati interrompe prima della fine risponde meta.partial e un avviso nella pagina che raggiunge quel punto.
• In GET /v1/shops/{shopId}/products, createdAt e publishedAt erano l'orologio del negozio inviato come UTC (8 ore troppo presto per un negozio con l'ora del Pacifico USA). Ora sono in UTC, con il nuovo updatedAt, a partire dallo scostamento del negozio rispetto a UTC (meta.shopUtcOffset, come -08:00). Quando non è possibile leggere alcuno scostamento, i tre sono null (local_time) e createdAtLocal, publishedAtLocal e updatedAtLocal forniscono l'orologio del negozio, senza fuso orario.
• Un prodotto elencato solo tra i più venduti dei dettagli del negozio ha publishedAt e updatedAt null (not_reported): quelli della fonte dei dati erano copie del suo orario di creazione.
• Ogni prodotto indica in quali elenchi si trova (lists: bestSellers, newest) e la sua posizione tra i più venduti (listPosition, da 1 a 100).

Altre modifiche del 23 ottobre 2026 (schede dei negozi):

• In GET /v1/shops/{shopId}, extra.googleAds.reach.value era sempre null: ora è la copertura UE di Google del negozio, con lowerBound e upperBound, e extra.googleAds aggiunge reachHistory, history (i suoi annunci Google segnati come attivi per settimana), updatedAt e latestAds.
• Il growth30d di un social network ora è la variazione a 30 giorni della panoramica dei follower (per alcune pagine Facebook era un'altra finestra: 0,3636 dove la variazione era 0,2898). Anche GET /v1/shops/{shopId}/socials lo fornisce come growth30d.
• Il profilo X del negozio è socials.x. socials.twitter è rinominato socials.x e resta, come lo stesso oggetto, per una release. Ogni rete ha url, e socials.others elenca gli altri link del negozio.
• tiktok.profileMetrics.percentAds è una percentuale (da 0 a 100); il nuovo adsShare è lo stesso valore come frazione. tiktok aggiunge avatarUrl, history, postsChange30d, postsChange30dPct e latestAds, e tiktok.activity.avgActiveAds7d e avgActiveAds30d, prima null, calcolano la media giornaliera dei suoi annunci TikTok.
• Novità nei piani a pagamento: advertising.summary.firstAdSeenAt, longestRunningDays, medianRunningDays, landingPagesCount e le variazioni a 30 giorni degli annunci attivi, degli annunci lanciati e della copertura UE (activeAdsChange30d, launchedChange30d, reachChange30d, ciascuna anche come frazione, …Pct), e advertising.runningDaysMix, reachCountries, reachHistory, topLandingPages, adsByAgeRange e adsByGender. Con ogni piano: advertising.allPagesHistory e advertising.topCountries[].ads.
• Novità: catalog.bestSellers[].rank, sales.hasSubscription, technology.apps[].appStoreUrl e categories, profile.isHeadless, extra.updatedAt, e i createdAt e trackedSince delle date dei negozi descritte sopra.
• GET /v1/shops/{shopId}/advertisers aggiunge il logoUrl e i moreLandingPages di ogni pagina, un profileUrl dove la panoramica degli annunci non ne ha uno, e il landingPagesCount e i moreLandingPages di ogni dominio.

Altre modifiche del 23 ottobre 2026 (prodotti):

• Novità: GET /v1/products e POST /v1/products/query cercano e sfogliano i prodotti dei negozi, ciascuno con prezzo, stime di vendita, unità vendute, recensioni, posizione tra i più venduti, annunci Meta, copertura e spesa UE, paesi di vendita, data di lancio e negozio, ordinati per relevance, newest (la data di lancio), activeAds o spend (la spesa pubblicitaria UE degli ultimi 30 giorni) (MCP search_products). searchType confronta il testo con il nome del prodotto o con il dominio del suo negozio, e i filtri con nome limitano il prezzo in USD, gli annunci attivi, la quota di annunci, il numero di recensioni e il giorno di lancio, e accettano valute e abbonamento; GET /v1/filters/products elenca le valute che accettano.
• shop (il dominio o l'id di un negozio) elenca solo i prodotti di quel negozio, senza testo di ricerca accanto, nella ricerca prodotti e in search_products. Le bacheche salvano i prodotti (sourceType product) come li ha mostrati l'ultima ricerca, e la ricerca in tutto ciò che è salvato li trova per titolo e negozio.
• Il server MCP ha 73 strumenti.

Altre modifiche del 23 ottobre 2026 (filtri dei prodotti):

• La ricerca prodotti accetta altri filtri con nome: la stima delle vendite di un mese o di un giorno (minEstMonthlySales, minEstDailySales e i loro massimi; il limite giornaliero conta come 30 giorni di quel valore), le unità vendute in un mese o in un giorno (minUnitsSoldMonthly, minUnitsSoldDaily), sellingCountries (un prodotto che vende in almeno uno di essi), shopCountries, il punteggio delle recensioni (minRating, maxRating), minAdsLaunched (annunci Meta lanciati negli ultimi 30 giorni), minSpendShare, minEuReach (la copertura UE su 30 giorni), hasPartnershipAds, promoTypes (percent-off) e minShopProductsCount, ciascuno con il suo massimo dove esiste; GET /v1/filters/products elenca anche i paesi dei negozi.
• sortBy accetta estSales (la stima delle vendite), adPressure (la quota di annunci) e bestSelling (la posizione tra i più venduti del suo negozio, prima la posizione 1), e searchType accetta productDescription e url.
• Ogni prodotto ha i suoi ultimi annunci (advertising.latestAds, con le loro immagini in advertising.previewUrls) e le sue settimane (weeks: annunci attivi, quota di annunci, spesa e copertura UE al giorno), e bestSeller.rankPercent è la sua posizione come percentuale dei prodotti del negozio (più basso è meglio).

Modifiche del 24 ottobre 2026 (parametri, letture non riuscite e pagine profonde):

• Un parametro di query che una route non legge viene rifiutato con 400 validation_failed, il cui messaggio lo indica ed elenca i parametri che la route accetta, mentre prima veniva scartato senza alcun avviso (un nome scritto male, o un filtro inviato a una route che non ne ha, riceveva una risposta come se non fosse mai stato inviato). Le ricerche rifiutano un filtro con nome sconosciuto come prima. Viene rifiutato anche un parametro semplice (country, mediaType, active, type) che imposta su un altro valore un filtro impostato anche da un filtro con nome.
• Monitoraggio marchi: /ads e /timeline/metadata rifiutano uno snapshotDate passato (leggono la libreria di annunci com'è adesso), /partnership-ads un sortBy sconosciuto, /v1/workspace/scaling-ads un period sconosciuto, e gli elenchi dei monitoraggi un hasNewAdsSince di oltre 30 giorni fa (i contatori dei nuovi annunci coprono 30 giorni). /v1/workspace/hooks, /ad-copies e /landing-pages leggono le righe di ogni marchio nel sortBy e nell'order richiesti prima di unirle. I report del sito su più marchi inviano euOnly solo ai report che lo leggono.
• I negozi simili rifiutano displayInTrending in filters (l'elenco non ha un flag dell'indice dei negozi) e leggono i loro limiti di crescita come percentuali, come fa una ricerca negozi; un offset oltre ciò che una richiesta può leggere (600 negozi oltre quelli già letti) viene rifiutato con un 400 che indica fin dove si può arrivare, e una pagina in cui la lettura si è fermata ha meta.partial con un avviso. La libreria TikTok di un negozio rifiuta i filtri per profilo e per sito (l'ambito del negozio stesso ne prende il posto).
• Una parte di una risposta che la fonte dei dati non è riuscita a leggere questa volta imposta meta.partial con un avviso (e la risposta non viene messa in cache), mai un vuoto silenzioso o un elenco vuoto; una risposta della fonte dei dati che non è JSON è un 503 upstream_error, e un negozio salvato, un nuovo monitoraggio o un elenco di opzioni email la cui lettura non riesce risponde con l'errore, mai con not_found. Una pagina più profonda di quella che raggiunge una lettura di un elenco che omette righe ha meta.partial e hasMore true, e i testi degli annunci, i partner e i test creativi di un marchio indicano con meta.partial quando una lettura non copre il marchio.
• GET /v1/google-ads/facets/networks accetta search, limit e offset, come gli altri elenchi di opzioni. Il metric di /v1/shops/compare è obbligatorio (il riferimento lo indicava come facoltativo).
• MCP: uno strumento rifiuta un argomento che il tipo scelto non legge (shop_report, lookup_filter_ids, market_overview, scan_advertiser) e argomenti in contrasto tra loro (trend_signal con sort_by, active_only con status, un argomento con nome insieme a filters); creative_inspiration_pack classifica insieme gli annunci di tutte le parole chiave.

Altre modifiche del 24 ottobre 2026 (ricerca per immagine):

• Novità: POST /v1/products/image-search trova i prodotti dei negozi che somigliano a un'immagine, ciascuno con il suo negozio, a partire dal più simile. Invia l'immagine come multipart/form-data: un file PNG, JPG o WEBP di massimo 10 MB (image), oppure l'URL diretto di un'immagine (imageUrl), che scarichiamo noi stessi. Ogni riga è una riga prodotto come la restituisce la ricerca prodotti, con similarity (da 0,7 a 1) e matchOnly (una corrispondenza di cui l'indice dei prodotti non ha alcuna scheda: solo titolo, immagine, prezzo, data di lancio e negozio).
• La ricerca accetta i filtri con nome della ricerca prodotti, sortBy (relevance, estSales, activeAds, adPressure, newest, spend, spend14d) e maxPerShop (le 1, 3, 5, 10 o 20 corrispondenze più vicine di ogni negozio), in pagine di massimo 32. GET /v1/products/image-search/{searchId} legge le altre pagine, gli ordinamenti, i filtri e i risultati per negozio senza inviare di nuovo l'immagine, e GET /v1/products/image-search/history elenca le tue ricerche per immagine recenti.
• L'immagine viene riscritta prima della ricerca, come JPEG senza i suoi metadati (EXIF, posizione, commenti), e l'URL di un'immagine non lascia mai i nostri server. Nuovi errori: 400 invalid_image, 400 unsupported_url e 422 unreadable_image.
• Con il piano Free, la ricerca per immagine è ordinata per pertinenza, senza filtri. Il server MCP ha 67 strumenti: search_products_by_image è nuovo.

Modifiche del 25 ottobre 2026 (crediti):

• L'API e il server MCP sono conteggiati in crediti invece che in richieste: 1 credito = 1 risultato restituito: i dettagli di un marchio, un annuncio o una riga di un elenco. Un risultato vuoto è gratuito. Una chiamata costa i risultati che restituisce, e la disponibilità mensile dei piani è in crediti.
• Le risposte a consumo inviano X-Usage-Cost, X-Credits-Used, X-Credits-Remaining e X-Credits-Source; GET /v1/usage riporta i crediti di ricarica in credits.topup.balance.
• 402 insufficient_credits arriva quando i crediti del mese e i crediti di ricarica sono entrambi esauriti, con details.upgradeUrl e details.topUpUrl.
• Il limite di richieste è condiviso da tutta l'area di lavoro.

I link di condivisione (shareUrl) aprono una pagina web su https://sellwinners.com che chiunque può vedere. La stessa scheda è disponibile in JSON da /v1/shared/ads/{token} e /v1/shared/boards/{token}. Un link il cui proprietario ha il piano Free risponde 403 forbidden finché il proprietario non torna a un piano a pagamento.

Gli endpoint di identità /v1/me, /v1/usage e /v1/workspace restituiscono i loro oggetti al livello principale, accanto a requestId. Gli endpoint di sistema /v1, /v1/health e /v1/system/freshness non riportano requestId, e /v1 e /v1/health rispondono con un oggetto semplice senza data. L'id della richiesta viene inviato anche nell'header X-Request-Id. Indicalo quando contatti l'assistenza.

Bacheche, preferiti e monitoraggi marchi hanno anche endpoint POST, PATCH e DELETE. Accettano un corpo JSON, inviato con Content-Type: application/json.

Paginazione

Gli endpoint di elenco accettano limit (fino a 100 nelle ricerche; gli elenchi di facet accettano fino a 500 e gli /snapshots di un marchio fino a 365) e page (1, 2, 3…) oppure offset. Quando vengono inviati entrambi, si usa offset. La dimensione di pagina predefinita è indicata per ogni endpoint. Gli elenchi di annunci, annunci Google, TikTok, email e media rispondono con:

"pagination": { "page": 2, "limit": 25, "total": 1840, "totalPages": 74, "hasMore": true }

Gli elenchi di negozi, prodotti e inserzionisti, e gli annunci di un inserzionista, rispondono con:

"pagination": { "limit": 32, "offset": 32, "total": 5120, "hasMore": true }

Per ottenere la pagina successiva, ripeti la stessa richiesta con page più uno, oppure con offset più limit. Nel corpo di una POST …/query, invia "page" o "offset" come campi. hasMore è false nell'ultima pagina. Quando la fonte dei dati non prosegue una ricerca oltre un certo punto, la pagina che lo raggiunge risponde hasMore false con meta.partial true e un avviso che indica quanti risultati si possono leggere. La paginazione raggiunge i primi 5.000 risultati di una ricerca (per una ricerca inserzionisti, i primi 100). Restringi la ricerca con i filtri o cambia l'ordinamento per vedere altri risultati.

Gli elenchi di annunci Google restituiscono un total esatto, tranne un elenco ristretto dalla regola sullo stato o sui giorni di attività (vedi la ricerca di annunci Google). Un "totalEstimated": true segnala un total (e il relativo totalPages) che è una stima finché l'elenco non viene letto fino alla fine, come per i negozi simili di un negozio e per una ricerca di annunci Meta di un negozio (websiteIds).

Bacheche, preferiti e report del monitoraggio marchi accettano page e limit e rispondono con page, limit, total, totalPages e hasMore. Gli elenchi di facet, i /products di un negozio e i suoi negozi /similar accettano limit e offset e rispondono con limit, offset, total e hasMore.

Ordinamento & filtri

Gli endpoint di ricerca accettano sortBy e order (desc per impostazione predefinita). Quando passi un termine di ricerca, i risultati sono ordinati per relevance a meno che tu non scelga un altro ordinamento; senza termine di ricerca il valore predefinito è newest (negozi e prodotti: relevance, media: reach). Le ricerche di annunci Google e TikTok sono sempre ordinate per pertinenza; lì sortBy si applica quando sfogli senza termine di ricerca.

Ogni dataset ha un endpoint POST …/query che accetta un corpo JSON con query, filters, sortBy, order, limit e page (o offset) per i filtri avanzati. Usa gli endpoint dei facet per vedere i valori e gli id accettati dai filtri.

I filtri si possono inviare per nome: come parametri di query aggiuntivi in una ricerca GET (?status=active&minDaysRunning=30&mainCountries=US,GB) o come campi di primo livello del corpo di una POST …/query ({"status": "active", "minDaysRunning": 30}). Ogni endpoint qui sotto elenca i nomi che accetta. Negli endpoint di ricerca, un nome di filtro che l'endpoint non supporta restituisce un 400 validation_failed che elenca quelli supportati, così un errore di battitura non restituisce mai in silenzio risultati non filtrati; i report del monitoraggio marchi ignorano i nomi che non conoscono. Gli elenchi accettano valori separati da virgole o un array JSON, le date usano 2026-01-31, e l'oggetto filters grezzo funziona ancora accanto ai filtri con nome.

I filtri di crescita (trafficGrowth, adsGrowth, pageReachGrowth, adReachGrowth) accettano regole scritte come {"comparison": "greater" | "lower", "value": 50} oppure {"operator": "gte" | "lte", "value": 50}. I valori sono percentuali sugli ultimi 30 giorni; altri periodi non sono disponibili. minRankDelta è il numero minimo di posizioni che un annuncio ha guadagnato in rankDeltaWindow (7d a meno che tu non invii 14d o 30d). hideSavedAds esclude gli annunci che hai già salvato. Gli id delle categorie per ogni filtro categoryIds provengono da /v1/facets/categories.

Limiti di richieste & crediti

1 credito = 1 risultato restituito: i dettagli di un marchio, un annuncio o una riga di un elenco. Un risultato vuoto è gratuito. Ogni piano include i crediti del mese, rinnovati alle 00:00 UTC del giorno 1. Una chiamata costa i risultati che restituisce, quindi un limit più piccolo costa meno, e una chiamata a uno strumento MCP costa i risultati che restituisce, come l'API. I crediti e il limite di richieste valgono per area di lavoro: tutti i suoi membri, tutte le sue chiavi, l'API e il server MCP condividono un unico pacchetto di crediti e un unico limite di richieste. Con un piano a pagamento, il proprietario dell'area di lavoro può acquistare crediti di ricarica nella pagina di fatturazione (con €1 ne acquisti 120, a partire da €10): si usano dopo i crediti del mese, si accumulano e non scadono mai.

Ogni risposta a consumo include:

X-RateLimit-Limit       requests allowed per minute
X-RateLimit-Remaining   requests left this minute
X-Usage-Cost            credits this request cost
X-Credits-Used          credits this request cost (the same number)
X-Credits-Remaining     credits left after this request (monthly and top-up)
X-Credits-Source        recurring, topup or hybrid (when it cost credits)
X-Quota-Limit           credits included this month
X-Quota-Remaining       monthly credits left
X-Quota-Reset           when the monthly credits renew (UTC)
X-Request-Id            the id of this request

Oltre il limite di richieste al minuto ricevi 429 rate_limited con un header Retry-After (in secondi). Quando i crediti del mese e i crediti di ricarica sono entrambi esauriti ricevi 402 insufficient_credits, con details.upgradeUrl e details.topUpUrl, finché i crediti mensili non si rinnovano. Controlla i tuoi crediti in qualsiasi momento con GET /v1/account o GET /v1/usage. Queste chiamate non costano nulla, inviano comunque X-Usage-Cost: 0, X-Credits-Used: 0 e X-Credits-Remaining, e funzionano anche quando i crediti sono esauriti.

Questi limiti si applicano all'API e al server MCP, nei piani a pagamento e con Free. L'app web sul sito non è a consumo: nei piani a pagamento è illimitata, nei limiti di un uso corretto.

Il piano Free

Il piano Free include l'app web e il server MCP (150 crediti al mese), senza l'API. Un account Free crea nella sua dashboard una chiave per il server MCP (agenti IA), entro 150 crediti al mese e 10 richieste al minuto; l'API REST fa parte dei piani a pagamento: con una chiave Free risponde 403 plan_not_eligible, con details.feature, details.requiredPlan e details.upgradeUrl, su ogni endpoint tranne GET /v1/account, e non viene conteggiato nulla. Una chiave creata con un piano a pagamento viene sospesa con Free, e torna a funzionare non appena l'account torna a un piano a pagamento. Con Free, una ricerca restituisce i suoi primi risultati e uno strumento o un endpoint i cui dati non sono inclusi in Free risponde con il messaggio dei piani a pagamento. Il confronto dei piani mostra cosa include Free. I marchi demo sono consultabili per intero sul sito.

Errori

Gli errori usano i codici di stato HTTP standard e un corpo JSON:

{
  "error": {
    "code": "invalid_api_key",
    "message": "This API key is invalid or has been revoked.",
    "requestId": "req_8f2c1a9b4d7e6f3a2b1c0d9e",
    "details": null
  }
}

code è stabile e puoi basarci la logica del tuo codice in sicurezza, message è scritto per le persone, e details contiene dati aggiuntivi quando ce ne sono (i campi rifiutati di un 400; i crediti mensili, la loro data di rinnovo, upgradeUrl e topUpUrl di un 402).

URL dei media

Le immagini e i video nelle risposte vengono serviti dalla nostra CDN all'indirizzo https://api.sellwinners.com/v1/media/file/…. Questi URL non richiedono una chiave API e non consumano crediti, quindi puoi incorporarli direttamente nei tag <img> e <video>. Un file che la fonte dei dati non ha più viene inviato come null per un giorno, e un file mancante risponde con un 404 vuoto del suo tipo di media. Anche le immagini dei prodotti e le icone delle app ospitate sulla CDN di Shopify vengono servite dalla nostra CDN. Per mostrare un'immagine piccola, aggiungi ?w=96 (miniature) o ?w=480 (schede): un'immagine JPEG, PNG, WebP o GIF viene allora inviata come WebP con al massimo quella larghezza, mai ingrandita; un'animazione, un'immagine più piccola o un video arrivano così come sono. Per un elenco semplice di creatività pronte da mostrare, usa /v1/media.

Per mostrare un'immagine alle sue dimensioni ma più leggera, aggiungi ?w=full: un'immagine JPEG, PNG, WebP o GIF viene allora inviata come WebP con la sua larghezza e la sua altezza originali, con una qualità che appare identica, se così si risparmia almeno un decimo del file; altrimenti, e per un'animazione o un video, l'originale arriva così com'è. Senza w, viene inviato il file originale.

Individuazione

Trasforma un nome, un dominio o l'id di una pagina negli id richiesti dagli altri endpoint.

curl "https://api.sellwinners.com/v1/lookup?q=allbirds.com&limit=5" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/lookup/facebook-shop?shopId=allbirds.com" \
  -H "X-API-Key: YOUR_API_KEY"

Negozi

Trova negozi Shopify e ottieni prodotti, traffico, vendite, social e annunci.

curl "https://api.sellwinners.com/v1/shops?search=shoes&country=US&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/shops/query" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"limit": 10, "mainMarketCountries": ["US"], "minMonthlyVisits": 50000, "page": 1, "search": "shoes", "sortBy": "monthlyVisits"}'

curl "https://api.sellwinners.com/v1/shops/allbirds.com" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/allbirds.com/products?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/allbirds.com/similar?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/allbirds.com/advertisers" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/allbirds.com/socials/history?days=90" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/allbirds.com/sales/history?days=90" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/SHOP_ID/socials" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/SHOP_ID/tiktok" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/SHOP_ID/apps" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/SHOP_ID/pixels" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/SHOP_ID/stores" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/SHOP_ID/media-mix" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/SHOP_ID/emails?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/compare?shopIds=allbirds.com%2Con.com" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/tools/shopify-apps?url=allbirds.com" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/tools/shopify-theme?url=allbirds.com" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/allbirds.com/feed" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/allbirds.com/q4-season" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/allbirds.com/q4-season/landing-pages" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/allbirds.com/q4-season/creatives" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/allbirds.com/ad-texts?kind=hook&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/allbirds.com/landing-pages" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/allbirds.com/landing-pages/detail?url=https%3A//www.allbirds.com/" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/allbirds.com/advertisers/ADVERTISER_ID/landing-pages" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/allbirds.com/ad-ranking?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/shops/allbirds.com/ad-ranking/query" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/allbirds.com/ad-ranking/series" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/allbirds.com/creative-testing?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/allbirds.com/creative-testing/2026-10-19" \
  -H "X-API-Key: YOUR_API_KEY"

Mercato

I totali giornalieri dell'intero mercato e la sua stagione Q4.

curl "https://api.sellwinners.com/v1/market/overview" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/market/q4-overview" \
  -H "X-API-Key: YOUR_API_KEY"

Annunci Meta

Creatività degli annunci Facebook e Instagram con media, copertura e posizione.

curl "https://api.sellwinners.com/v1/ads?search=skincare&country=US&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/ads/query" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"limit": 10, "mainCountries": ["US"], "mediaType": "video", "minDaysRunning": 14, "page": 1, "query": "skincare", "sortBy": "reach", "status": "active"}'

curl "https://api.sellwinners.com/v1/ads/AD_ID" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/ads/AD_ID/reach-history?limit=30" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/ads/AD_ID/media-url" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/ads/facets/landing-pages?scopeDomain=allbirds.com" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/ads/facets/ad-copies?scopeDomain=allbirds.com" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/ads/facets/partners?scopeDomain=allbirds.com" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/ads/AD_ID/share" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X DELETE "https://api.sellwinners.com/v1/ads/AD_ID/share" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shared/ads/TOKEN" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/tools/ad-hooks" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"angle": "pain", "language": "en", "niche": "skincare", "platform": "both", "product": "Vitamin C serum"}'

curl "https://api.sellwinners.com/v1/tools/ad-hooks" \
  -H "X-API-Key: YOUR_API_KEY"

Google Ads

Creatività degli annunci Google.

curl "https://api.sellwinners.com/v1/google-ads?search=running%20shoes&country=US&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/google-ads/query" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"limit": 10, "page": 1, "query": "running shoes", "status": "active"}'

curl "https://api.sellwinners.com/v1/google-ads/AD_ID" \
  -H "X-API-Key: YOUR_API_KEY"

TikTok

Annunci e post organici TikTok.

curl "https://api.sellwinners.com/v1/tiktok/library?search=fitness&country=US&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/tiktok/library/query" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"limit": 10, "minViews": 100000, "page": 1, "query": "fitness", "type": "ad"}'

curl "https://api.sellwinners.com/v1/tiktok/library/ITEM_ID" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/SHOP_ID/tiktok/library?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Media

Creatività pronte da mostrare: URL di immagini e video sulla nostra CDN.

curl "https://api.sellwinners.com/v1/media?search=sneakers&country=US&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/media/query" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"limit": 10, "mediaType": "video", "page": 1, "query": "skincare", "status": "active"}'

curl "https://api.sellwinners.com/v1/media/file/FILE_KEY" \
  -H "X-API-Key: YOUR_API_KEY"

Inserzionisti

Inserzionisti (pagine Facebook) e la loro attività.

curl "https://api.sellwinners.com/v1/advertisers?search=nike&country=US&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/advertisers/query" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"limit": 10, "minActiveAds": 10, "offset": 0, "query": "nike"}'

curl "https://api.sellwinners.com/v1/advertisers/ADVERTISER_ID" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/advertisers/ADVERTISER_ID/history?days=90" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/advertisers/ADVERTISER_ID/ads?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Email

Email di marketing e newsletter dei marchi.

curl "https://api.sellwinners.com/v1/emails?search=black%20friday&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/emails/query" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"campaignTypes": ["Marketing"], "limit": 10, "page": 1, "query": "black friday", "sentAfter": "2025-11-01"}'

curl "https://api.sellwinners.com/v1/emails/EMAIL_ID" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/emails/EMAIL_ID/html" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shops/allbirds.com/emails/stats?month=2026-09" \
  -H "X-API-Key: YOUR_API_KEY"

Prodotti

Prodotti dei negozi con prezzo, vendite, recensioni, annunci e copertura UE.

curl "https://api.sellwinners.com/v1/products?search=serum&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/products/query" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"limit": 10, "minActiveAds": 10, "minPriceUsd": 20, "offset": 0, "query": "serum", "sortBy": "activeAds"}'

curl "https://api.sellwinners.com/v1/products/SHOP_ID:PRODUCT_ID" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/products/lookup?url=https%3A//example.com/products/blue-mug" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/products/SHOP_ID:PRODUCT_ID/ads" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/products/SHOP_ID:PRODUCT_ID/share-links" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X DELETE "https://api.sellwinners.com/v1/products/SHOP_ID:PRODUCT_ID/share-links" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shared/products/TOKEN" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/products/facets" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/shops/image-search" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "[email protected]"

curl -X POST "https://api.sellwinners.com/v1/products/image-search" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "maxPerShop=3"

curl "https://api.sellwinners.com/v1/products/image-search/history?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/products/image-search/SEARCH_ID?sortBy=activeAds&page=2" \
  -H "X-API-Key: YOUR_API_KEY"

Facet

I valori e gli id accettati dai filtri di ricerca.

curl "https://api.sellwinners.com/v1/facets/categories?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/facets/shopify-apps?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/facets/technologies?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/facets/pixels?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/facets/themes?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/facets/email-classifications" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/google-ads/facets/networks" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/google-ads/facets/countries?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/google-ads/facets/formats" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/google-ads/facets/statuses" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/google-ads/facets/categories?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/tiktok/facets/categories?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/tiktok/facets/languages?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/tiktok/facets/countries?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/tiktok/facets/content-types?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/tiktok/facets/media-types?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/emails/facets/promotionTypes?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/filters/shops" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/filters/advertisers" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/filters/products" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/filters/ads" \
  -H "X-API-Key: YOUR_API_KEY"

Bacheche

Salva annunci, negozi, prodotti, email e inserzionisti nelle bacheche e condividili.

curl "https://api.sellwinners.com/v1/boards?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/boards" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"kind": "collection", "name": "Skincare winners", "surface": "ads", "visibility": "workspace"}'

curl "https://api.sellwinners.com/v1/boards/BOARD_ID" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X PATCH "https://api.sellwinners.com/v1/boards/BOARD_ID" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"description": "Ads worth a second look.", "name": "Skincare winners 2026"}'

curl -X DELETE "https://api.sellwinners.com/v1/boards/BOARD_ID" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/boards/BOARD_ID/restore" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X PATCH "https://api.sellwinners.com/v1/boards/BOARD_ID/parent" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"parentBoardId": "BOARD_ID"}'

curl "https://api.sellwinners.com/v1/boards/BOARD_ID/items?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/boards/search?q=serum&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/boards/BOARD_ID/items" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"sourceId": "AD_ID", "sourceType": "meta_ad"}'

curl -X POST "https://api.sellwinners.com/v1/boards/BOARD_ID/items/ITEM_ID/move" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"targetBoardId": "BOARD_ID"}'

curl -X DELETE "https://api.sellwinners.com/v1/boards/BOARD_ID/items/ITEM_ID" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/boards/BOARD_ID/share-links" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X DELETE "https://api.sellwinners.com/v1/boards/BOARD_ID/share-links" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/shared/boards/TOKEN" \
  -H "X-API-Key: YOUR_API_KEY"

Preferiti

Annunci, negozi ed email preferiti, in cartelle.

curl "https://api.sellwinners.com/v1/favorites/ads?scope=workspace&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/favorites/ads" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"adId": "AD_ID", "scope": "workspace"}'

curl -X PATCH "https://api.sellwinners.com/v1/favorites/ads/saved/FAVORITE_ID/folder?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"folderId": "FOLDER_ID"}'

curl -X DELETE "https://api.sellwinners.com/v1/favorites/ads/saved/FAVORITE_ID?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X DELETE "https://api.sellwinners.com/v1/favorites/ads/RECORD_ID?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/favorites/ads/folders?scope=workspace&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/favorites/ads/folders" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Winners", "scope": "workspace"}'

curl -X PATCH "https://api.sellwinners.com/v1/favorites/ads/folders/reorder?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"folders": [{"id": "FOLDER_ID", "order": 0}]}'

curl -X POST "https://api.sellwinners.com/v1/favorites/ads/folders/FOLDER_ID/share?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X DELETE "https://api.sellwinners.com/v1/favorites/ads/folders/FOLDER_ID/share?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X PATCH "https://api.sellwinners.com/v1/favorites/ads/folders/FOLDER_ID/visibility?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"visibility": "private"}'

curl -X PATCH "https://api.sellwinners.com/v1/favorites/ads/folders/FOLDER_ID?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Top performers"}'

curl -X DELETE "https://api.sellwinners.com/v1/favorites/ads/folders/FOLDER_ID?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"mode": "move_items_to_root"}'

curl "https://api.sellwinners.com/v1/favorites/shops?scope=workspace&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/favorites/shops" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"scope": "workspace", "websiteId": "SHOP_ID"}'

curl -X PATCH "https://api.sellwinners.com/v1/favorites/shops/saved/FAVORITE_ID/folder?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"folderId": "FOLDER_ID"}'

curl -X DELETE "https://api.sellwinners.com/v1/favorites/shops/saved/FAVORITE_ID?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X DELETE "https://api.sellwinners.com/v1/favorites/shops/RECORD_ID?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/favorites/shops/folders?scope=workspace&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/favorites/shops/folders" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Winners", "scope": "workspace"}'

curl -X PATCH "https://api.sellwinners.com/v1/favorites/shops/folders/reorder?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"folders": [{"id": "FOLDER_ID", "order": 0}]}'

curl -X POST "https://api.sellwinners.com/v1/favorites/shops/folders/FOLDER_ID/share?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X DELETE "https://api.sellwinners.com/v1/favorites/shops/folders/FOLDER_ID/share?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X PATCH "https://api.sellwinners.com/v1/favorites/shops/folders/FOLDER_ID/visibility?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"visibility": "private"}'

curl -X PATCH "https://api.sellwinners.com/v1/favorites/shops/folders/FOLDER_ID?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Top performers"}'

curl -X DELETE "https://api.sellwinners.com/v1/favorites/shops/folders/FOLDER_ID?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"mode": "move_items_to_root"}'

curl "https://api.sellwinners.com/v1/favorites/emails?scope=workspace&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/favorites/emails" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"emailId": 123456, "scope": "workspace"}'

curl -X PATCH "https://api.sellwinners.com/v1/favorites/emails/saved/FAVORITE_ID/folder?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"folderId": "FOLDER_ID"}'

curl -X DELETE "https://api.sellwinners.com/v1/favorites/emails/saved/FAVORITE_ID?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X DELETE "https://api.sellwinners.com/v1/favorites/emails/RECORD_ID?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/favorites/emails/folders?scope=workspace&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/favorites/emails/folders" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Winners", "scope": "workspace"}'

curl -X PATCH "https://api.sellwinners.com/v1/favorites/emails/folders/reorder?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"folders": [{"id": "FOLDER_ID", "order": 0}]}'

curl -X POST "https://api.sellwinners.com/v1/favorites/emails/folders/FOLDER_ID/share?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X DELETE "https://api.sellwinners.com/v1/favorites/emails/folders/FOLDER_ID/share?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X PATCH "https://api.sellwinners.com/v1/favorites/emails/folders/FOLDER_ID/visibility?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"visibility": "private"}'

curl -X PATCH "https://api.sellwinners.com/v1/favorites/emails/folders/FOLDER_ID?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Top performers"}'

curl -X DELETE "https://api.sellwinners.com/v1/favorites/emails/folders/FOLDER_ID?scope=workspace" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"mode": "move_items_to_root"}'

Viste salvate

Le ricerche che hai salvato nelle pagine elenco del sito, per pagina.

curl "https://api.sellwinners.com/v1/views" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/views" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"context": "shops", "name": "Big US shops", "state": "f.marketCountries=US\u0026f.minMonthlyVisits=100000\u0026sortBy=monthlyVisits"}'

curl -X PATCH "https://api.sellwinners.com/v1/views/VIEW_ID" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Big US shops 2026", "position": 0}'

curl -X DELETE "https://api.sellwinners.com/v1/views/VIEW_ID" \
  -H "X-API-Key: YOUR_API_KEY"

Monitoraggio marchi

Segui i marchi e leggi i report sui loro annunci, creatività e landing page.

curl "https://api.sellwinners.com/v1/brandtrackers?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/brandtrackers" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"domain": "allbirds.com"}'

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X DELETE "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/overview" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/snapshots?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/ads?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/timeline?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/timeline/metadata" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/partnership-ads?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/partnership-ads/count" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/top-ads?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/ad-rank?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/scaling-ads?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/creatives?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/testing?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/hooks?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/transcripts?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/headlines?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/ad-copies?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/landing-pages?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/landing-pages/simple?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/ad-copy-evolution?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/headline-evolution?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/landing-page-evolution?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/partners?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/media-mix" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/demography" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/activity?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/activity/events?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/activity/calendar" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/activity/calendar/days" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/BRANDTRACKER_ID/time-series" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/workspace/top-ads?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/workspace/scaling-ads?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/workspace/hooks?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/workspace/ad-copies?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/workspace/landing-pages?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/workspace/media-mix?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/brandtrackers/folders" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.sellwinners.com/v1/workspace/folders" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.sellwinners.com/v1/brandtrackers/folders" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Competitors"}'

curl -X PATCH "https://api.sellwinners.com/v1/brandtrackers/folders/FOLDER_ID" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Direct competitors"}'

curl -X DELETE "https://api.sellwinners.com/v1/brandtrackers/folders/FOLDER_ID" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"action": "move-to-default", "confirm": true}'