E-commerce data API documentation

The SellWinners API gives you e-commerce and advertising intelligence over HTTPS with JSON responses: Shopify stores with their products and traffic; store products with their price, sales estimates, reviews and ads; Meta, Google and TikTok ads; advertisers; and the emails brands send. Every endpoint is also available to AI agents through our hosted MCP server. This page covers authentication, the response format, pagination, sorting and filters, rate limits and credits, errors and media URLs, then every endpoint with its parameters and an example request, and the MCP server's tools.

Quickstart

1. Create an account, confirm your email and choose a paid plan: the API and the MCP server start there.
2. Open API keys and create a key. Copy it right away: it's shown only once.
3. Make your first request:

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

Authentication

Send your API key on every request in the X-API-Key header, or as a bearer token:

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

Keys start with ak_live_. Keep them secret: don't put them in front-end code or public repositories. You can create several keys (one per app or environment) and revoke any key from your dashboard; a revoked key stops working immediately.

Responses

Every response is JSON. It carries a requestId and the result under data: a list for searches and listings, one object for a single record. Lists add a pagination object, and some answers add 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 }
}

Records are nested objects: an ad has media, advertiser, content, metrics, audience, rank and flags, and shops, advertisers, Google ads, TikTok items and emails are grouped the same way. A value that is not known is null. Further fields with no fixed place are kept under extra. The example above is shortened.

In an ad, content.title is the headline and content.callToAction is readable text such as "Shop now". metrics.estimatedSpend is the source's spend estimate when it has one (a single ad from /v1/ads/{adId} reads it), otherwise reach x 9 / 1000 (9 USD per 1,000 people reached); a spend estimate keeps two decimals under 10 USD and is in whole dollars from 10 USD up. rank.rankDelta is the current rank minus the previous one, so a negative value means the ad moved up, and rank.improvementPct is a fraction (0.25 is a quarter).

The brand tracker rank reports (/ad-rank, /scaling-ads, /v1/workspace/scaling-ads and the MCP tool get_brandtracker_scaling_ads) add their own metrics: there metrics.rankDelta is the previous rank minus the current one (positive: places gained) and metrics.improvementPct is the fraction of the previous rank gained, as in an ad (0.875 is 87.5%). On a single ad, metrics.reachDelta1d, reachDelta7d and reachDelta30d are filled from its reach history. Shops name their categories: catalog.mainCategory in listings, plus catalog.categories on a single shop.

In a Google ad, media.type and media.format are text, image or video, and media.url is the ad's image: for a video ad, its thumbnail (there is no video file). transparencyUrl is the ad on Google's Ads Transparency Center, where a video ad plays; it is null when the ad has no Google ids. network is search, youtube, shopping, maps or other, and so are the values of extra.networks.

Changed on October 19, 2026:

• A Google ad's media.format was a format code and is now text, image or video, its media.type can be text or video, and extra.networks uses the lower-case names of network.
• A Google media.url is never a video file, even when media.type is video.
• In the Google formats filter, image now means image ads (it meant text ads before), so use text for text ads. The earlier codes static_image, html5_iframe and responsive_display, and their short names, are still accepted.

A Google ad's status is active only while Google shows the ad: one Google has not shown for more than 7 days is unknown. daysRunning counts the days from firstSeenAt to lastSeenAt, both included; extra.servedDays is the data source's own count, which goes on after an ad stops. The filters agree with what each ad shows: status=active keeps the ads Google showed in the last 7 days and status=inactive the ads the data source marks stopped, so an unknown ad is under neither; minDaysRunning and maxDaysRunning the ads whose daysRunning is in range. Such a list has pagination.total null, and when few of the ads read match it ends early, with meta.partial and a warning.

With no search text, sortBy=relevance lists the newest; sortBy=reach takes order=desc only. With status=active, sortBy=reach lists few ads: in reach order the first ads are mostly ones Google stopped showing, so sort by newest for the ads Google shows now (its warning says so). Google ads take no sortBy=longestRunning: the data source ranks it by days that go on after an ad stops, so it listed ads Google no longer shows, and it answers 400 with that reason.

extra.startIsFloor marks an ad first seen on May 31, 2018, the first day of Google's ad data, so it may be older. audience.countries lists every audience country, with a percentage only for an ad shown in one; remarketing and interest are null when unknown.

Google reports a reach for some of the ads shown in the EU only, often only as 10,000,000, the top of its scale (10 million or more): most ads have none, and nullReasons says why reach.value is null (not_reported: an ad shown in the EU that Google reports none for; eu_only: an ad shown elsewhere), except for a reach the plan leaves out. extra.networks is the data source's list of the ad's platforms, which may not name network. extra.shop.google holds the Google totals of the advertiser's website; for a site that is not a shop (an app store, a social site, a link shortener) advertiser.domain and websiteId are null.

Changed on October 20, 2026:

• A domain (GET /v1/shops/{domain}, the lookup, a TikTok domain, the competitor brief) is the site with exactly that domain, also outside the shop index; one the data source does not reach answers 404.
• GET /v1/lookup ranks results best first: a domain's own site, its own Facebook pages (main page first), then the pages named like it; for a name, the brand's own site and its own pages (main page first), then the shops and pages found by the name.
• With the brand's site found, a shop or page that has the name only inside a word is left out and a site of that name is exact only when it runs ads; otherwise a name match is exact only with traffic or ads. Official pages of another name with no live ad come after the pages found by name.
• A shop row's signals.activeAdsSource says where its activeAds come from: page (its main page's live ads, read now, on the shop's own row) or index (the shop index's count, which can be older).
• A shop domain search (searchType=domain) lists the exact site first, with extra.exactDomainMatch (and extra.inShopIndex false when the shop index leaves it out).
• For a site that is not a shop (an app store, a social or messaging site, a link shortener or a tracking redirect), an advertiser row's extra.domain is null, an advertiser record names it in extra.nonShopSite, leaves out extra.platforms and takes linkedShops from its landing pages (fromLandingPages), and an ad has no shops.
• Date-times the data source sends without a zone are UTC and are now sent with +00:00.
• In email stats, emailsByDayOfWeek is keyed by the day's number: 0 is Sunday, 6 Saturday.
• Lookup rows may carry nullReasons, and a shop record meta.partial when its listing figures could not be read.

Also changed on October 20, 2026 (TikTok):

• A TikTok item's publishedAt is UTC. It was 1 or 2 hours late, so a post made in the last hours of a UTC day showed the next day and a daysRunning one day short.
• The filters agree with it: publishedAfter and publishedBefore are UTC (a date alone is the start of its day, and publishedBefore lists the posts before it), minDaysRunning and maxDaysRunning count from the UTC day, as daysRunning does, and sortBy=longestRunning starts at August 31, 2016, 22:00 UTC.

Also changed on October 20, 2026 (Google ads):

• GET /v1/google-ads, POST /v1/google-ads/query and the MCP tool take no sortBy=longestRunning (nor daysRunning) and answer 400 with the reason: the data source ranks it by days that go on after an ad stops, so it listed ads Google no longer shows.
• A Free search whose first results status=active leaves short answers meta.partial with a warning that says how many of the ads read it lists.
• In extra.shop, a site with no traffic data has no monthlyVisits (it was 0), a trafficGrowth30d comes only beside visits above 0, and extra.shop.google leaves out a 0 totalReach or weeklyReach (never reported) and, when it counts no ad, the 0 counts.
• A Google ad saved to a board reads the same.

Also changed on October 20, 2026 (shops):

• In GET /v1/shops/{shopId}, advertising.summary.reach30d is the EU reach of the last 30 days, summed by date (it was the total since tracking began, now totalReach), spend30d is that reach x 9 / 1000, extra.estimatedSpendUsd is the spend since tracking began and extra.adsLaunched30d sums the ads launched in the last 30 days; all are null for a shop with no EU or UK reach.
• Shop records, listed shops and email stats carry nullReasons, a field path mapped to why it is null: not_shopify (sales and products are estimated for Shopify stores only), no_estimate, not_measured, eu_uk_only, not_linked (no TikTok profile), not_on_tp, no_reviews, none_found.
• A sales estimate of zero next to units sold is null, in records, listings and the sales history, whose period=week has one point per week.
• traffic.growth30d is a fraction (-0.1543 is -15.4%), and traffic.history starts at the first month with visits.
• catalog.mainCategory comes from the category ids (the most specific of the main branch), with catalog.categoryLeaves and productsCountCapped (25,001 is the data source's ceiling: 25,000 or more).
• A Trustpilot page with no review has a null rating.
• tiktok.matchedBy is socials or handle when the TikTok figures come from the shop's social profiles or from a profile found by its handle (a match, not a link of the data source).
• advertising.mainPageActiveAds is the main page's live ads (its ad overview's reading, as its Main page in linkedAdvertisers shows it; the count shop lists show only without one) and linkedAdvertisers[].rank the page's rank.
• Similar shops leave out the shop itself and its own sites, and each page is filled from further down the list (offset and limit count the list without them).
• Products sorted by popularity rank the shop's best sellers first (meta.order).
• A shop's emails and email stats count every campaign type, and their 90-day figures are null when unknown.
• A sales sort lists one row per Shopify store (extra.sharedSalesWith), and sortBy=estMonthlySales&order=asc leaves out the shops with no estimate.

Also changed on October 20, 2026 (shop figures):

• A sales sort of GET /v1/shops reads on past the domains it merges into one row per Shopify store (it stopped after the first rows), merges a store's domains further down the list too, and its pagination.total is null until the list is read to its end; sortBy=estMonthlySales&order=asc starts at an estimate of 100 USD (minMonthlySales 100).
• A sales estimate under 0.50 USD a unit sold is null (no_estimate), in records, listings and the sales history.
• traffic.monthlyVisits is null for a site not measured yet and traffic.growth30d when the month before had no visits (not_measured); a social network's growth30d comes from its follower history when the data source gives 0 or none, and 0 followers is null (not_measured).
• Listed shops say why catalog.productsCount and sales.unitsSold are null.
• extra.storeWide marks a domain with 0 visits that carries its store's sales (a measured 0, or another domain of the store, named in extra.sharedSalesWith, has the visits; Free leaves the name out of a shop record).
• advertising.mainPageActiveAds is the main page's live ads as its ad overview reads them (the count shop lists show only without one).
• Similar shops also leave out the shop's brand stores, and extra.similarIndexed is false for a shop the similarity index does not hold.
• catalog.mainCategory keeps the data source's own label only when it is a category's name.
• A media file an answer linked that the data source no longer has answers 200 with an empty body and X-Media-Missing: true.

Also changed on October 20, 2026 (advertisers and Meta ads):

• An advertiser's reach is EU and UK reach, the advertiser search's own windows: advertising.reach30d, extra.reach14d, reach90d and totalReach are null for a page with no EU or UK ads and no reach, or for a window the data source has not counted, and nullReasons says why (eu_uk_only, not_measured); a page created inside a window has all its reach in it (they were 0).
• In GET /v1/advertisers/{advertiserId} the reach is the one advertiser lists show (it was read 30 readings back, and readings skip days), the spend estimates are null with it, extra.avgSpendUsd14d is the average daily spend of 14 days, extra.avgActiveAds14d is the 14-day average of its live ads (it was its new ads of 14 days), where the data source has not computed it, for a page created inside the 14 days from its live ads read since its first day (extra.averagedFrom), else null, and the new-ads counts of a page created inside the window count every one of its ads.
• advertising.countryDistribution is the share of its live ads that target each country (an ad targets several), extra.reachCountries holds each country's share of the EU reach, extra.platforms.meta holds the page's own ads (it held the shop's main page's), a TikTok or Google count with no figure is left out, extra.mainLandingPages falls back on the preview of a new page's landing pages, and the lastAds of a page whose ads the ad search has not taken in yet are the latest ones its advertiser row lists, with meta.indexing, as on GET /v1/advertisers/{advertiser_id}/ads (with meta.liveAds).
• New: GET /v1/advertisers/{advertiserId}/history, the page's live ads and the EU reach it gained, day by day.
• An Instagram follower count of 0 is null (the data source writes 0 for a page with no account it knows).
• A Meta ad's metrics.reach and its spend are null for an ad not shown in the EU or the UK (eu_uk_only; they were 0 or null) and for an EU ad whose reach is not counted yet (not_measured; it was 0), media rows saying why in nullReasons.reach, media.type is carousel for an ad of more than one image or video, and extra.startIsFloor marks an ad started on January 1, 2018, the first day of the data source's Meta ad dates.
• sortBy=adRank lists the best rank (1) first, whatever the order.
• One ad (GET /v1/ads/{adId}) takes the latest reach the data source reports and the spend of it, counts its reach deltas by date while its reach history is current (else they are null), lists its images and videos as its search row does, fills advertiser.reach30d and pageAnalytics.instagramFollowersHistory, adds pageAnalytics.reachHistory (the same series as impressionsHistory), and names a shop the record gives by its id only (its traffic null with nullReasons shops.traffic when the site is not measured); its audience.gender, ageMin, ageMax and metrics.aggregatedReach are always null, as the data source does not report them for one ad.
• In an advertiser search, sortBy=reach ranks by the total reach since tracking began and newAds by the new ads of 14 days.
• A Meta ad's targeting says why its reach is null: eu_uk_only only for an ad that targets no EU or UK country; one that targets one, or whose targeting is not known yet, is not_measured in its first 7 days and not_reported after (they were eu_uk_only), in ad listings, media rows and one ad.
• One ad reads its reach and spend histories as one series, one reading a day (its deltas too), and takes that series' last reading and spend when the record's reach is more than twice it and the series runs to the ad's last day; its media falls back on its first listed file, and advertiser.totalReach on the page details' EU reach.
• An advertiser record whose row reads no reach next to page details that read some has their reach (extra.totalReach, the spend of it, advertising.reach30d counted on it), its extra.reachCountries shares are never rounded to 0, extra.averagedFrom is never before the day the page was created, and its daily history (extra.history, GET /v1/advertisers/{advertiserId}/history) leaves out the readings the data source missed (a run of zeros of 14 days or fewer between readings above 0).
• One ad that takes its series' reading keeps the record's reach in extra.recordReach (the figure ad listings show); in an advertiser search, a row that reads no EU reach next to page details that read some has their reach, as its record does; and GET /v1/advertisers/{advertiserId}/history keeps the readings of 0 of a page with no EU ad now that gained reach before the days asked (it gained none; they were left out as not_measured).
• On Free, an ad whose reach is unknown says why as on paid plans; only a reach the plan leaves out has no reason.

Also changed on October 20, 2026 (spend estimates):

• An estimated spend under 10 USD keeps two decimals: a reach of 140 at 9 USD per 1,000 people reached is 1.26 (it was 1), and a daily average keeps its own cents; from 10 USD up a spend estimate is in whole dollars (a reach of 2,000 is 18).
• This holds for the advertiser record's extra.estimatedSpendUsd and extra.avgSpendUsd14d, a shop's advertising.summary.spend30d and extra.estimatedSpendUsd, a Meta ad's metrics.estimatedSpend, and a brand tracker's statistics.euData.estimatedSpend30d and the estimatedSpend of each /time-series point (both had two decimals at any amount), in the API and the MCP tools alike. Where the data source's own figure is that estimate in whole dollars, it keeps its cents the same way.

Also changed on October 20, 2026 (advertiser reach and daily history):

• GET /v1/advertisers/{advertiserId} adds extra.reachScope: outside_eu_uk for a page most of whose reach by country was seen outside the EU and the UK (the data source reports the reach of some ads shown elsewhere too; its reach and the estimates made from it are then that reach, not EU reach), else eu_uk. Its extra.avgSpendUsd14d of a page created inside the 14 days is its spend over the whole days since it was created (one at least; it was its 14-day reach over 14 days where the advertiser row had one).
• The advertiser record's extra.history and GET /v1/advertisers/{advertiserId}/history start on the day the page was created; extra.history.newAds leaves out its 0 of the days the data source missed, extra.followersHistory and an ad's pageAnalytics likes and followers a 0 between two readings above 0 or of such a day, and the daily spend estimates keep two decimals under 10 USD.
• A page whose live ads no list holds yet has meta.indexing on its record, and an empty first page of GET /v1/advertisers/{advertiser_id}/ads with meta.indexing and meta.liveAds.
• One ad (GET /v1/ads/{adId}): extra.spendHistory starts on the day the ad started, each spendUsd with two decimals under 10 USD; advertiser.totalReach is never below the last reading of pageAnalytics.reachHistory (extra.pageRecordReach then holds the record's total, the one advertiser lists show); extra.recordSpend is the spend of extra.recordReach; extra.reachScope and extra.pageReachScope say where most of the ad's reach and of its page's was seen.

Also changed on October 20, 2026 (brand trackers):

• In GET /v1/brandtrackers and GET /v1/brandtrackers/{id}, a 0 of advertising.newAdsLastDay beside launches in the last 7 days is checked against the shop's launches of yesterday: their count, or null (not_measured) with no reading of that day; a listing checks 20 brands a call at most, those of the page asked for.
• In /top-ads and /v1/workspace/top-ads, metrics.totalReach is the ad's EU reach: null for an ad shown outside the EU and the UK (eu_uk_only) or an EU ad not counted yet (not_measured), with nullReasons, and last in a reach sort (it was 0).
• /testing counts its reach stats over the ads whose reach is known, with nullReasons stats.reach for a batch with none.
• In /hooks, /transcripts, /landing-pages and the workspace hooks and landing pages, a totalImpressions of 0 is null with the new reason no_eu_reach (no EU or UK reach counted for its ads; not_measured with euOnly), last in its sort.
• In /ad-rank, /scaling-ads and /v1/workspace/scaling-ads, where an ad's rank history starts inside a 14 or 30-day window, metrics.previousRank and rankDelta count from its oldest reading there: metrics.since is that day and meta.windowNote says so, and a figure that cannot be given is null with nullReasons.
• In /partners, isOwnPage is true for the shop's main page, its official pages named like the brand and a page named as the brand (creators can be ranked official too), and a null reach or spend has nullReasons.
• The first page of /ads with adCopyHashes has meta.latestAdDate and dataFreshnessLagDays, and with status=active meta.stoppedCount.
• /demography is the audience in the EU and the UK, and a country under a ten-thousandth of the top one moves from countryDistribution to otherCountries.
• /ad-copy-evolution and /headline-evolution have a point for every recorded day (0 when the text was not used, null on a day cut at the texts it keeps), rank texts by the newest day and leave out the days the data source read wrong (live ads under a tenth of the days around them, one day or 2 or 3 in a row, or far fewer texts than the days on both sides), as meta.periodNote says; meta.recordedDays counts the days. Weekly and monthly /time-series live ads leave out 2 or 3 such readings in a row too.

Also changed on October 20, 2026 (brand tracker reports, lookup and Google reach):

• In /ad-rank, /scaling-ads and /v1/workspace/scaling-ads every rank of a row comes from the ad's rank history: metrics.currentRank is its reading of the day the ad library's rank was read (the rank /top-ads shows; the library can be a day behind the history), else its newest reading, the trajectory ends on that day, and with no reading on the day the window starts the oldest reading inside it counts (the data source's own change over the window is no longer used).
• The ad library's first 50 ads (10 per brand across brands) are ranked again by these figures: an ad that gained less than minRankDelta, or ranks below maxCurrentRank, by them is left out (an ad whose rank history gives no gain, by the ad library's own count), pagination covers the ads kept and meta.rankNote says what was read and left out, across brands too.
• A daily /time-series (and the overview's graph) is null on a day whose live ads the data source read wrong (under a tenth of the days on both sides of it; the newest day stays as read, in the text evolutions too), its launches too, and so are the launches of the day after it when they are nearly all its live ads; weeks and months leave those launches out, and leftOut lists the days. /landing-page-evolution leaves those days out of every page, and a page's own reading under a tenth of the readings on both sides, as its meta.periodNote says, with the day the history reaches when it is behind.
• A /testing batch with no reach counted has nullReasons stats.reach no_eu_reach unless one of its ads is not counted yet (not_measured) or all were shown outside the EU and the UK (eu_uk_only); a /partners row's missing reach and spend are not_measured only in the 7 days after its launchDate, no_eu_reach after.
• /creatives names an ad of several images or videos carousel (it was unknown).
• In GET /v1/lookup, a shop's signals.monthlyVisits is null for a site not measured yet (nullReasons not_measured; it was 0), the exact shop row's live ads (with every type, shop too) are its main page's as its ad overview reads them, its mainPageActiveAds, and the rows of the shop's own pages read theirs the same way, a tracked brand's signals.monthlyVisits (and its totalTraffic in GET /v1/brandtrackers) is null for a site not measured yet and says why it is missing (not_measured, or no_shop for a page with no shop), and on Free a page's reach that no plan has keeps its reason (eu_uk_only, not_measured), in advertiser lists too.
• A Google ad's null reach.value has nullReasons (not_reported, eu_only), except for a reach the plan leaves out.
• In GET /v1/shops/{shopId}, advertising.mainPageActiveAds is the main page's live ads as its ad overview reads them, the count its Main page in linkedAdvertisers shows (it was the shop index's count, which can be a day older).

Also changed on October 20, 2026 (TikTok and emails):

• A TikTok row's metrics.engagementRate is (likes + comments + shares + saves) / views as a fraction (0.0513 is 5.13%; searches sent a percent and GET /v1/tiktok/library/{itemId} another metric), and daysRunning is the days since the post was published, in both.
• metrics.rank is the post's rank among its creator's posts (1 is the best).
• profile.followers is null when the data source has not counted them (it sent 0), content.category is null for its catch-all All, and content.hashtags are the post's tags, once each, spelled as in its description and without the punctuation after them (a record's are the data source's list of them, a search row's those of the description).
• A TikTok record adds profile.adsCount, organicCount and avgPostsPerWeek90d, fills profile.pageCreation, and has null links for a row of the data source with no TikTok behind it (an id of fewer than 15 digits, or published before August 31, 2016, 22:00 UTC).
• sortBy=longestRunning starts at the first TikToks (August 31, 2016, 22:00 UTC).
• An email record names its promotion type, category and event, and its shop's monthly visits, live ads, products and 90-day figures are those the email lists show, as are the email stats' last90Days figures.
• An email row leaves out extra.shopActiveAds for a 0 with no ad total (its nullReasons say not_measured), and an email record's shop.marketing.activeAds is then null; when the shop's figures could not be read, the record has meta.partial, a warning and nullReasons failed for them.
• In the MCP tool analyze_shop_emails, dominant ranks campaign types, categories, promotion types and events each on its own and leaves out No Promotion and No Event.

Changed on October 21, 2026:

• A TikTok item's metrics.views, and its likes and saves that read 0 beside them, are null with nullReasons not_measured (and so is engagementRate) when the data source sent 0 views next to likes, comments, shares or saves above 0, in searches and in GET /v1/tiktok/library/{itemId}; sortBy=views or likes with order=asc lists the posts with their views counted (minViews 1).
• A Meta ad search with websiteIds lists the shops' own ads: every ad of a shop's main page and of its official pages named like it, and the ads of its other pages (creators, publishers and partners who ran its ads) that link to the shop or to a site on its domain; until the list is read to its end, the search's pagination.total is then the ads of the shop's own pages searched, an estimate (pagination.totalEstimated true), or null when the search names none of its own pages.
• With sortBy=longestRunning, each batch of ads read from the data source is put in order of daysRunning.
• In GET /v1/shops/{shopId}, advertising.activeAds counts the live ads of the shop's own pages (linkedAdvertisers[].isOwnPage), and in its /products a ranked best seller has the title, price and image of catalog.bestSellers (a best seller's price can be the lowest of its variants').
• A shop's traffic.monthlyVisits (and growth30d) is null with not_measured when it reads 0 since its history went to 0 next to a sales estimate above 0 and units sold, in records, listed and similar shops and the lookup; such a domain is still extra.storeWide.
• In GET /v1/ads/{adId}, advertiser.totalReach is the last reading of pageAnalytics.reachHistory while that reading is at most 2 days old (extra.pageRecordReach then holds the record's total), extra.advertiserTotalAds is filled from the page's listed figures (not_measured without one), the 7-day and 30-day reach gains of an ad started inside the window are all its reach, and a gain below that of fewer days is null (not_measured).
• A brand tracker's statistics.ctaCount names each call to action as content.callToAction does ("Shop now").

Also changed on October 21, 2026 (shops):

• In GET /v1/shops/{shopId}, advertising.history is the main page's live ads by day on every plan (on Free it counted every page's), and the docs say that advertising.summary reach and spend, extra.adsLaunched30d, extra.totalAds and extra.estimatedSpendUsd cover every page of the shop, where advertising.activeAds counts its own pages.
• A shop's catalog.productsCount of 0 with no product listed, next to visits, a sales estimate or units sold, is null with not_measured, in records, listed shops and the meta.productsCount of GET /v1/shops/{shopId}/products; sortBy=productsCount leaves those shops out, and with order=asc sends minProductsCount 1 unless a products minimum is given.
• A Meta ad search of a shop narrowed to pages that are not its own (trackedPages) that ends early says why in meta.warnings, without asking to narrow it.
• GET /v1/filters/shops says in meta.warnings when the data source lists no values, and names the lists that give them.

Also changed on October 21, 2026 (paging, emails and ad lists):

• Paging an advertiser search no longer fails when the data source will not continue it (it answered 503, and a retry did not help): its first 100 results are read in one call, and the page that reaches the end of what can be read answers hasMore false, with meta.partial true and a warning that says how far the search reads.
• A page that starts past a search's exact total is empty, with hasMore false.
• A TikTok search sorted by views or likes with order=asc starts at the first TikToks (August 31, 2016, 22:00 UTC), as longestRunning does, and a TikTok item's metrics.views (and engagementRate) is null with not_measured when it reads fewer views than likes.
• An email's content.bodyPreview and bodyLength, and a record's content.body, are null with not_measured where the data source sent its placeholder for a body it has not read.
• Date-times the data source gives in UTC are written one way in lists and records alike, with +00:00 and no trailing zeros in the fraction of a second (2026-09-30T00:20:11.507+00:00; the times your own boards, favorites, brand trackers and share links were created or changed end in Z, as before), and email rows carry the ids of their category, promotion type and event, as the email's record does.
• Every paged list answers pagination.hasMore, and GET /v1/google-ads/facets/countries answers a pagination object.
• A request body that is not valid JSON answers 400 validation_failed with the message "The request body is not valid JSON." and details.position, the character where it breaks off.
• In Meta ad lists a row's reach is the ad index's reading, which can be a day behind the ad's record, and its reach gains are null beside a known reach when the data source lists none (not_measured), except over a window the ad started in, where it gained all the reach its row reads; in GET /v1/ads/{adId} a gain that is null beside a known reach has not_measured too.

Changed on October 22, 2026 (the Free plan):

• The API and the MCP server moved to paid plans: a key of an account on the Free plan answered 403 plan_not_eligible on every endpoint except GET /v1/account, with details.upgradeUrl, and nothing was counted. No key could be made on Free.
• The Free plan has changed since: The Free plan says what it includes now.
• A key made on a paid plan is kept, and it works again as soon as the account is back on a paid plan. Share links made by an account on Free are paused the same way.

Also changed on October 22, 2026 (shop reports and records):

• In GET /v1/shops/{shopId}/ad-ranking/series, rankDelta is the end rank minus the start rank (negative when the ad moved up, as in every ad; it was the places gained) and improvementPercent is now improvementPct, a fraction; each row of /ad-ranking carries the same two figures over the ranking's window in rank.
• In a tracked brand's /activity/calendar, a calendar day and /activity/calendar/days, meta.partial is true or false, meta.partialSources names the sources read in part (on /calendar and a day), and preview times are UTC, a TikTok post's too.
• In GET /v1/shops/{shopId}/landing-pages/detail, activeAds falls back on the page's ads, shareOfAds is linkedAdsTotal out of shopActiveAds, snapshots counts the days the page was captured, lifetimeAds and impressions are gone (the impressions were the reach again), a reach of 0 is null with nullReasons.reach no_eu_reach, and linkedAds have the fields of an ad search's rows.
• A shop's /feed lists its own Meta ads, as its ad searches do.
• GET /v1/market/q4-overview takes any from and to inside the season.
• In /q4-season, winners lists each sale's key with its creatives, and landing page urls carry their scheme.
• The Shopify detectors read a store at its domain without www..
• GET /v1/advertisers/{advertiserId} and a tracked brand's landing pages, audience and media mix echo a past day in meta.snapshotDate.
• When a shop's Meta ad statistics cannot be read at that moment, GET /v1/shops/{shopId} answers meta.partial true with a warning: its reach, the spend estimates made from it and its media and format mix are null with nullReasons failed, its ads by country are counted as its search row gives them, and the answer is not kept, so the next call reads them again (the competitor brief carries the same meta.partial and warnings).
• A landing page on the shop's own domain, or a subdomain of it, is toShop true in /v1/shops/{shopId}/advertisers and /advertisers/{advertiserId}/landing-pages; when the shop's domains leave that domain out, meta.domains lists it first from its pages' landing pages (fromLandingPages true, a lower bound), and a page's shopAds is never fewer than the live ads of its landing pages on the shop (shopAdsAtLeast true when raised).
• In GET /v1/tiktok/library/{itemId}, profile.latestPosts[].mediaUrl is the post's video, or null with nullReasons not_reported (it was the cover image).
• An advertiser search reads its first 100 results and says it ends on the page that reaches the 100th (hasMore false and the warning), not on the empty page after it.
• A TikTok search sorted by views or likes with order=asc now leaves out the posts whose views are not counted (fewer views than likes), and its pagination.total is an estimate (totalEstimated) until the list is read to its end; every other order lists them, their views null.

Also changed on October 22, 2026 (saved items and ad hooks):

• New: GET /v1/boards/search finds what you saved, across every board and your favorites, by the words of what each saved copy shows (every word must appear, in any order; case and accents are ignored), its id or its board's name, and takes sourceType, boardId, savedFrom and savedTo; it reads your saved items only, never the data source (MCP find_saved_items).
• New: POST /v1/tools/ad-hooks writes three short opening lines for an ad of your product, and GET /v1/tools/ad-hooks gives your allowance: no monthly limit on paid plans, and a limit a minute (429 with Retry-After); reading the allowance is not counted (MCP write_ad_hooks).
• The MCP server has 64 tools.

Also changed on October 23, 2026 (saved views and shop filters):

• New: GET /v1/views lists the searches you saved on the website's list pages, each with the search it makes (request: the search, searchType, sortBy, order and named filters, as the search endpoints take them); POST /v1/views saves one, PATCH /v1/views/{viewId} renames, moves or changes it and DELETE /v1/views/{viewId} removes it. They read and write your own views only, never the data source (MCP list_saved_views).
• Shop searches take excludeCurrencies (currency codes such as EUR), socialNetworks (instagram or tiktok: a shop with any of them) and shopifyPlan (headless). trafficGrowth also reads 90 days (min90, max90) and adsGrowth 7 days (min7, max7), or a rule's period (last90d, last7d); min and max stay the last 30 days.
• The MCP server has 65 tools.

Also changed on October 23, 2026 (product links):

• In GET /v1/shops/{shopId}, each of catalog.bestSellers carries handle and productUrl, the product's page on the shop's own site: the address the data source gives when it is on the shop's domain (or a subdomain of it) or its myshopify domain, else https://<domain>/products/<handle> when its handle is known, else null.
• In GET /v1/shops/{shopId}/products, productUrl follows the same rule, so an address on another site is no longer given, and handle is null when it is no single part of an address.

Also changed on October 23, 2026 (shop rows, similar shops and products):

• A shop's createdAt (the shop record, shop rows and similar shops) is a Shopify store's creation date only. For a site off Shopify the data source gives the day it began tracking the site, not its creation: createdAt is now null (nullReasons tracking_date) and that day is the new trackedSince. A date on or before January 1, 2000 is the data source's placeholder and is null (not_reported).
• Shop rows' catalog.bestSellers carry handle, productUrl (the rule of the shop record's) and rank (1 is the best seller), and rows carry profile.isHeadless and catalog.myShopifyDomain, as the shop record does.
• A shop row's googleAds.reach.value is null: shop rows carry no Google reach, which is on the shop record (extra.googleAds.reach).
• Similar shops (GET /v1/shops/{shopId}/similar, the record's similarShops) keep their extra (logo, Trustpilot, sales history). A similar list the data source stops before its end answers meta.partial and a warning on the page that reaches that point.
• In GET /v1/shops/{shopId}/products, createdAt and publishedAt were the shop's own clock sent as UTC (8 hours early for a shop on US Pacific time). They are now UTC, with the new updatedAt, from the shop's offset from UTC (meta.shopUtcOffset, such as -08:00). When no offset can be read, the three are null (local_time) and createdAtLocal, publishedAtLocal and updatedAtLocal give the shop's clock, without a zone.
• A product listed only among the shop details' best sellers has a null publishedAt and updatedAt (not_reported): the data source's were copies of its creation time.
• Each product says which lists it is in (lists: bestSellers, newest) and its place among the best-selling ones (listPosition, 1 to 100).

Also changed on October 23, 2026 (shop records):

• In GET /v1/shops/{shopId}, extra.googleAds.reach.value was always null: it is now the shop's Google EU reach, with lowerBound and upperBound, and extra.googleAds adds reachHistory, history (its Google ads marked active by week), updatedAt and latestAds.
• A social network's growth30d is now the 30-day change of the followers overview (it was another window for some Facebook pages: 0.3636 where the change was 0.2898). GET /v1/shops/{shopId}/socials gives it as growth30d too.
• The shop's X profile is socials.x. socials.twitter is renamed socials.x and stays, the same object, for one release. Each network has url, and socials.others lists the shop's other links.
• tiktok.profileMetrics.percentAds is a percent (0 to 100); the new adsShare is the same as a fraction. tiktok adds avatarUrl, history, postsChange30d, postsChange30dPct and latestAds, and tiktok.activity.avgActiveAds7d and avgActiveAds30d, null before, average its TikTok ads by day.
• New on paid plans: advertising.summary.firstAdSeenAt, longestRunningDays, medianRunningDays, landingPagesCount and the 30-day changes of the live ads, launched ads and EU reach (activeAdsChange30d, launchedChange30d, reachChange30d, each also as a fraction, ...Pct), and advertising.runningDaysMix, reachCountries, reachHistory, topLandingPages, adsByAgeRange and adsByGender. On every plan: advertising.allPagesHistory and advertising.topCountries[].ads.
• New: catalog.bestSellers[].rank, sales.hasSubscription, technology.apps[].appStoreUrl and categories, profile.isHeadless, extra.updatedAt, and the createdAt and trackedSince of the shop dates above.
• GET /v1/shops/{shopId}/advertisers adds each page's logoUrl and moreLandingPages, a profileUrl where the ad overview has none, and each domain's landingPagesCount and moreLandingPages.

Also changed on October 23, 2026 (products):

• New: GET /v1/products and POST /v1/products/query search and browse store products, each with its price, sales estimates, units sold, reviews, best seller rank, Meta ads, EU reach and spend, selling countries, launch date and shop, sorted by relevance, newest (the launch date), activeAds or spend (EU ad spend over the last 30 days) (MCP search_products). searchType matches the text against the product's name or its shop's domain, and the named filters bound the price in USD, the active ads, the ad share, the number of reviews and the launch day, and take currencies and subscription; GET /v1/filters/products lists the currencies they take.
• shop (one shop's domain or id) lists that shop's products only, with no search text beside it, on the product search and in search_products. Boards save products (sourceType product) as a search last showed them, and the search of everything saved finds them by their title and shop.
• The MCP server has 73 tools.

Also changed on October 23, 2026 (product filters):

• The product search takes more named filters: the sales estimate of a month or a day (minEstMonthlySales, minEstDailySales and their maximums; a day's bound is 30 days of it), units sold a month or a day (minUnitsSoldMonthly, minUnitsSoldDaily), sellingCountries (a product that sells to any of them), shopCountries, the review score (minRating, maxRating), minAdsLaunched (Meta ads launched in the last 30 days), minSpendShare, minEuReach (the EU reach over 30 days), hasPartnershipAds, promoTypes (percent-off) and minShopProductsCount, each with its maximum where it has one; GET /v1/filters/products lists the shops' countries too.
• sortBy takes estSales (the sales estimate), adPressure (the ad share) and bestSelling (the best seller rank in its shop, rank 1 first), and searchType takes productDescription and url.
• Each product has its latest ads (advertising.latestAds, with their pictures in advertising.previewUrls) and its weeks (weeks: live ads, ad share, EU spend and reach a day), and bestSeller.rankPercent is its rank as a percent of the shop's products (low is better).

Changed on October 24, 2026 (parameters, failed reads and deep pages):

• A query parameter a route does not read is refused with 400 validation_failed, whose message names it and lists the parameters the route takes, where it used to be dropped without a word (a misspelt name, or a filter sent to a route that has none, answered as if it was never sent). Searches refuse an unknown named filter as before. A plain parameter (country, mediaType, active, type) that sets a filter a named filter also sets, to another value, is refused too.
• Brand trackers: /ads and /timeline/metadata refuse a past snapshotDate (they read the ad library as it is now), /partnership-ads an unknown sortBy, /v1/workspace/scaling-ads an unknown period, and the tracker lists a hasNewAdsSince more than 30 days back (the new-ad counters cover 30 days). /v1/workspace/hooks, /ad-copies and /landing-pages read each brand's rows in the sortBy and order asked before merging them. The website's across-brands reports send euOnly only to the reports that read it.
• Similar shops refuse displayInTrending in filters (the list has no shop-index flag) and read its growth bounds as percentages, as a shop search does; an offset past what one request can read (600 shops on from those already read) is refused with a 400 that says how deep it can go, and a page the read stopped in has meta.partial with a warning. A shop's TikTok library refuses profile and site filters (the shop's own scope takes their place).
• A part of an answer the data source could not read this time sets meta.partial with a warning (and the answer is not cached), never a silent gap or an empty list; an answer of the data source that is not JSON is a 503 upstream_error, and a saved shop, a new tracker or an email option list whose read fails answers the error, never not_found. A page deeper than one read of a list that leaves rows out reaches has meta.partial and hasMore true, and a brand's ad copies, partners and creative tests say with meta.partial when one read does not cover the brand.
• GET /v1/google-ads/facets/networks takes search, limit and offset, as the other option lists. metric of /v1/shops/compare is required (the reference said optional).
• MCP: a tool refuses an argument its chosen kind does not read (shop_report, lookup_filter_ids, market_overview, scan_advertiser) and arguments that disagree (trend_signal with sort_by, active_only with status, a named argument with filters); creative_inspiration_pack ranks every keyword's ads together.

Also changed on October 24, 2026 (search by image):

• New: POST /v1/products/image-search finds the store products that look like a picture, each with its shop, the closest first. Send the picture as multipart/form-data: a PNG, JPG or WEBP file of 10 MB at most (image), or a direct image URL (imageUrl), which we download ourselves. Each row is a product row as the product search answers it, with similarity (0.7 to 1) and matchOnly (a match the product index has no record of: its title, picture, price, launch date and shop only).
• The search takes the product search's named filters, sortBy (relevance, estSales, activeAds, adPressure, newest, spend, spend14d) and maxPerShop (the closest 1, 3, 5, 10 or 20 matches of each shop), in pages of up to 32. GET /v1/products/image-search/{searchId} reads its other pages, sorts, filters and results per shop without sending the picture again, and GET /v1/products/image-search/history lists your own recent image searches.
• The picture is written again before it is searched, as a JPEG without its metadata (EXIF, location, comments), and an image URL never leaves our servers. New errors: 400 invalid_image, 400 unsupported_url and 422 unreadable_image.
• On the Free plan, image search is ranked by relevance, with no filters. The MCP server has 67 tools: search_products_by_image is new.

Changed on October 25, 2026 (credits):

• The API and the MCP server are metered in credits instead of requests: 1 credit = 1 result returned: one brand's details, one ad, or one row of a list. An empty result is free. A call costs the results it returns, and the plans' monthly allowance is in credits.
• Metered answers send X-Usage-Cost, X-Credits-Used, X-Credits-Remaining and X-Credits-Source; GET /v1/usage reports the top-up credits under credits.topup.balance.
• 402 insufficient_credits comes once the month's credits and the top-up credits are both used up, with details.upgradeUrl and details.topUpUrl.
• The rate limit is shared by the whole workspace.

Share links (shareUrl) open a web page on https://sellwinners.com that anyone can view. The same record is available as JSON from /v1/shared/ads/{token} and /v1/shared/boards/{token}. A link whose owner is on the Free plan answers 403 forbidden until the owner is back on a paid plan.

The identity endpoints /v1/me, /v1/usage and /v1/workspace return their objects at the top level, next to requestId. The system endpoints /v1, /v1/health and /v1/system/freshness carry no requestId, and /v1 and /v1/health answer a plain object without data. The request id is also sent in the X-Request-Id header. Quote it when you contact support.

Boards, favorites and brand trackers also have POST, PATCH and DELETE endpoints. They take a JSON body, sent with Content-Type: application/json.

Pagination

List endpoints take limit (up to 100 on searches; facet listings take up to 500 and a brand's /snapshots up to 365) and either page (1, 2, 3...) or offset. When both are sent, offset is used. The default page size is listed with each endpoint. Ad, Google ad, TikTok, email and media listings answer with:

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

Shop, product and advertiser listings, and the ads of one advertiser, answer with:

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

To get the next page, repeat the same request with page plus one, or with offset plus limit. In a POST …/query body, send "page" or "offset" as fields. hasMore is false on the last page. When the data source will not continue a search past some point, the page that reaches it answers hasMore false with meta.partial true and a warning that says how many results can be read. Paging reaches the first 5,000 results of a search (an advertiser search, its first 100). Narrow the search with filters or change the sort to see other results.

Google ad listings return an exact total, except a list the status or days-running rule narrows (see the Google ads search). A "totalEstimated": true marks a total (and its totalPages) that is an estimate until the list is read to its end, as on a shop's similar shops and a Meta ad search of a shop (websiteIds).

Boards, favorites and brand tracker reports take page and limit and answer with page, limit, total, totalPages and hasMore. Facet lists, a shop's /products and its /similar shops take limit and offset and answer with limit, offset, total and hasMore.

Sorting & filters

Search endpoints accept sortBy and order (desc by default). When you pass a search term, results are sorted by relevance unless you choose another sort; without a search term the default is newest (shops and products: relevance, media: reach). Google and TikTok ad searches are always ranked by relevance; there, sortBy applies when you browse without a search term.

Each data source has a POST …/query endpoint that takes a JSON body with query, filters, sortBy, order, limit and page (or offset) for advanced filtering. Use the facet endpoints to see the values and ids the filters take.

Filters can be sent by name: as extra query parameters on a GET search (?status=active&minDaysRunning=30&mainCountries=US,GB) or as top-level fields of a POST …/query body ({"status": "active", "minDaysRunning": 30}). Each endpoint below lists the names it takes. On the search endpoints a filter name the endpoint doesn't support returns a 400 validation_failed that lists the supported ones, so a typo never silently returns unfiltered results; the brand tracker reports ignore names they don't know. Lists take comma-separated values or a JSON array, dates use 2026-01-31, and the raw filters object still works alongside named filters.

Growth filters (trafficGrowth, adsGrowth, pageReachGrowth, adReachGrowth) take rules written as {"comparison": "greater" | "lower", "value": 50} or {"operator": "gte" | "lte", "value": 50}. Values are percentages over the last 30 days; other periods are not available. minRankDelta is the minimum number of positions an ad gained over rankDeltaWindow (7d unless you send 14d or 30d). hideSavedAds leaves out the ads you already saved. Category ids for every categoryIds filter come from /v1/facets/categories.

Rate limits & credits

1 credit = 1 result returned: one brand's details, one ad, or one row of a list. An empty result is free. Each plan includes credits for the month, renewed at 00:00 UTC on the 1st. A call costs the results it returns, so a smaller limit costs less, and an MCP tool call costs the results it returns, like the API. Credits and the rate limit are per workspace: everyone in it, all its keys, the API and the MCP server share one pool of credits and one rate limit. On a paid plan, the workspace's owner can buy top-up credits on the billing page (€1 buys 120, from €10): they are used after the month's credits, carry over and never expire.

Every metered response includes:

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

Over the per-minute rate limit you get 429 rate_limited with a Retry-After header (in seconds). When the month's credits and the top-up credits are both used up you get 402 insufficient_credits, with details.upgradeUrl and details.topUpUrl, until the monthly credits renew. Check your credits any time with GET /v1/account or GET /v1/usage. These calls cost nothing, still send X-Usage-Cost: 0, X-Credits-Used: 0 and X-Credits-Remaining, and work even when the credits are used up.

These limits apply to the API and the MCP server, on paid plans and on Free. The web app on the website is not metered: on paid plans it is unlimited within fair use.

The Free plan

The Free plan includes the web app and the MCP server (150 credits a month), without the API. A Free account makes a key for the MCP server (AI agents) in its dashboard, within 150 credits a month and 10 requests a minute; the REST API is on paid plans: with a Free key it answers 403 plan_not_eligible, with details.feature, details.requiredPlan and details.upgradeUrl, on every endpoint except GET /v1/account, and nothing is counted. A key made on a paid plan is paused on Free, and it works again as soon as the account is back on a paid plan. On Free, a search answers its first results and a tool or endpoint whose data Free does not include answers with the paid plans' message. The plan comparison shows what Free includes. The demo brands are open in full on the website.

Errors

Errors use standard HTTP status codes and a JSON body:

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

code is stable and safe to branch on, message is written for people, and details carries extra data when there is some (the rejected fields of a 400; the monthly credits, their renewal date, upgradeUrl and topUpUrl of a 402).

Media URLs

Images and videos in responses are served from our CDN at https://api.sellwinners.com/v1/media/file/…. These URLs don't need an API key and don't use credits, so you can embed them directly in <img> and <video> tags. A file the data source no longer has is sent as null for a day, and a missing file answers an empty 404 of its media type. Product images and app icons hosted on Shopify's CDN are served from our CDN too. To show an image small, add ?w=96 (thumbnails) or ?w=480 (cards): a JPEG, PNG, WebP or GIF image is then sent as WebP at that width at most, never made larger; an animation, a smaller image or a video comes as it is. For a flat, display-ready list of creatives, use /v1/media.

To show an image at its own size but lighter, add ?w=full: a JPEG, PNG, WebP or GIF image is then sent as WebP at its own width and height, at a quality that looks the same, when that saves at least a tenth of the file; otherwise, and for an animation or a video, the original comes as it is. Without w, the original file is sent.

Discovery

Turn a name, a domain or a page id into the ids the other endpoints take.

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"

Shops

Find Shopify stores and get products, traffic, sales, socials and ads.

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"

Market

The whole market's daily totals, and its Q4 season.

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"

Meta Ads

Facebook and Instagram ad creatives with media, reach and rank.

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

Google ad creatives.

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

TikTok ads and organic posts.

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

Render-ready creatives: image and video URLs on our 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"

Advertisers

Advertisers (Facebook pages) and their activity.

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"

Emails

Brands' marketing and newsletter emails.

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"

Products

Store products with their price, sales, reviews, ads and EU reach.

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"

Facets

The values and ids the search filters take.

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"

Boards

Save ads, shops, products, emails and advertisers on boards, and share them.

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"

Favorites

Favorite ads, shops and emails, in folders.

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"}'

Saved views

The searches you saved on the website's list pages, by page.

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"

Brand trackers

Follow brands and read reports on their ads, creatives and landing pages.

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}'