电商数据 API 文档

SellWinners API 通过 HTTPS 以 JSON 响应为您提供电商和广告情报：Shopify 店铺及其商品和流量；店铺商品及其价格、销量估算、评价和广告；Meta、Google 和 TikTok 广告；广告主；以及品牌发送的邮件。所有端点也可以通过我们托管的 MCP 服务器供 AI 智能体使用。本页介绍身份验证、响应格式、分页、排序和筛选、速率限制和点数、错误和媒体 URL，然后列出每个端点及其参数和请求示例，以及 MCP 服务器的工具。

快速入门

1. 创建账户，确认您的邮箱并选择付费套餐：API 和 MCP 服务器从付费套餐开始提供。
2. 打开API 密钥并创建一个密钥。请立即复制：它只显示一次。
3. 发出您的第一个请求：

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

身份验证

在每个请求的 X-API-Key 请求头中发送您的 API 密钥，或作为 Bearer 令牌发送：

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

密钥以 ak_live_ 开头。请妥善保密：不要将其放入前端代码或公开代码仓库。您可以创建多个密钥（每个应用或环境一个），并在控制台中撤销任意密钥；被撤销的密钥会立即失效。

响应

所有响应均为 JSON。响应包含一个 requestId，结果位于 data 下：搜索和列表返回数组，单条记录返回一个对象。列表还会附带 pagination 对象，部分响应还会附带 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 }
}

记录是嵌套对象：广告包含 media、advertiser、content、metrics、audience、rank 和 flags，店铺、广告主、Google 广告、TikTok 条目和邮件也以同样的方式分组。未知的值为 null。没有固定位置的其他字段放在 extra 下。上面的示例已做删减。

在广告中，content.title 是标题，content.callToAction 是可读文本，例如「Shop now」。metrics.estimatedSpend 在已有支出估算时取该估算（通过 /v1/ads/{adId} 获取的单条广告会读取它），否则为覆盖人数 x 9 / 1000（每覆盖 1,000 人 9 USD）；支出估算在 10 USD 以下保留两位小数，10 USD 及以上取整数美元。rank.rankDelta 是当前排名减去之前的排名，因此负值表示广告排名上升；rank.improvementPct 是一个比例（0.25 表示四分之一）。

品牌追踪排名报告（/ad-rank、/scaling-ads、/v1/workspace/scaling-ads 以及 MCP 工具 get_brandtracker_scaling_ads）带有各自的 metrics：其中 metrics.rankDelta 是之前的排名减去当前排名（正值表示名次上升），metrics.improvementPct 是相对之前排名上升的比例，与广告中的含义相同（0.875 表示 87.5%）。在单条广告中，metrics.reachDelta1d、reachDelta7d 和 reachDelta30d 根据其覆盖人数历史计算得出。店铺会注明其品类：列表中为 catalog.mainCategory，单个店铺还包含 catalog.categories。

在 Google 广告中，media.type 和 media.format 的值为 text、image 或 video，media.url 是广告的图片：视频广告则为其缩略图（没有视频文件）。transparencyUrl 是该广告在 Google 广告透明度中心的页面，视频广告可在那里播放；广告没有 Google ID 时为 null。network 的值为 search、youtube、shopping、maps 或 other，extra.networks 的值也是如此。

2026年10月19日更新：

• Google 广告的 media.format 原为格式代码，现在为 text、image 或 video；其 media.type 可以是 text 或 video；extra.networks 使用 network 的小写名称。
• 即使 media.type 为 video，Google 的 media.url 也绝不会是视频文件。
• 在 Google 的 formats 筛选中，image 现在表示图片广告（之前表示文字广告），因此文字广告请使用 text。之前的代码 static_image、html5_iframe 和 responsive_display 及其简称仍然可用。

只有在 Google 展示广告期间，Google 广告的 status 才为 active：Google 超过 7 天未展示的广告为 unknown。daysRunning 统计从 firstSeenAt 到 lastSeenAt 的天数（两端都计入）；extra.servedDays 是另一种独立计数，在广告停止后仍会继续累计。筛选条件与每条广告显示的内容一致：status=active 保留 Google 在最近 7 天内展示过的广告，status=inactive 保留被标记为已停止的广告，因此 unknown 的广告不属于其中任何一类；minDaysRunning 和 maxDaysRunning 保留 daysRunning 在范围内的广告。此类列表的 pagination.total 为 null；当读取的广告中匹配的很少时，列表会提前结束，并附带 meta.partial 和一条警告。

没有搜索文本时，sortBy=relevance 列出最新的广告；sortBy=reach 仅支持 order=desc。使用 status=active 时，sortBy=reach 列出的广告很少：按覆盖人数排序时，排在前面的大多是 Google 已停止展示的广告，因此要查看 Google 当前展示的广告，请按最新排序（其警告中也会说明）。Google 广告不支持 sortBy=longestRunning：该排序按广告停止后仍继续累计的天数排名，会列出 Google 已不再展示的广告，因此会返回 400 并说明原因。

extra.startIsFloor 标记首次出现于 2018年5月31日（Google 广告数据的第一天）的广告，因此该广告的实际投放时间可能更早。audience.countries 列出所有受众国家，只有仅在一个国家展示的广告才带有 percentage；remarketing 和 interest 在未知时为 null。

Google 只对部分在欧盟展示的广告报告覆盖人数，而且通常只报告 10,000,000，即其刻度的上限（一千万或更多）：大多数广告没有覆盖人数，nullReasons 会说明 reach.value 为 null 的原因（not_reported：在欧盟展示但 Google 未报告覆盖人数的广告；eu_only：在其他地区展示的广告），套餐不包含覆盖人数的情况除外。extra.networks 是该广告所在平台的列表，其中可能不包含 network。extra.shop.google 包含广告主网站的 Google 汇总数据；对于不是店铺的网站（应用商店、社交网站、短链接服务），advertiser.domain 和 websiteId 为 null。

2026年10月20日更新：

• 域名（GET /v1/shops/{domain}、lookup、TikTok 的 domain、竞争对手简报）指的是域名完全一致的网站，也包括店铺索引之外的网站；无法获取的域名返回 404。
• GET /v1/lookup 按匹配度从高到低排列结果：对于域名，依次是该域名自己的网站、它自己的 Facebook 主页（主主页优先），然后是名称相似的主页；对于名称，依次是该品牌自己的网站和主页（主主页优先），然后是按名称找到的店铺和主页。
• 找到品牌网站后，名称只出现在某个单词内部的店铺或主页会被排除；同名网站只有在投放广告时才算精确匹配；否则，名称匹配只有在有流量或广告时才算精确匹配。名称不同且没有在投广告的官方主页排在按名称找到的主页之后。
• 店铺行的 signals.activeAdsSource 说明其 activeAds 的取值方式：page（其主主页的在投广告，实时读取，见于店铺自己的行）或 index（店铺索引中的计数，可能较旧）。
• 店铺域名搜索（searchType=domain）会把完全匹配的网站排在最前面，并附带 extra.exactDomainMatch（当店铺索引中没有该网站时，extra.inShopIndex 为 false）。
• 对于不是店铺的网站（应用商店、社交或即时通讯网站、短链接服务或跟踪重定向），广告主行的 extra.domain 为 null，广告主记录会在 extra.nonShopSite 中注明该网站，不包含 extra.platforms，并从其落地页获取 linkedShops（fromLandingPages），而广告则没有 shops。
• 未带时区的日期时间均为 UTC，现在会附带 +00:00。
• 在邮件统计中，emailsByDayOfWeek 以星期几的编号为键：0 表示星期日，6 表示星期六。
• lookup 结果行可能带有 nullReasons；当店铺的列表数据无法读取时，店铺记录会带有 meta.partial。

2026年10月20日的其他更新（TikTok）：

• TikTok 条目的 publishedAt 为 UTC。之前它晚了 1 或 2 小时，因此在 UTC 日最后几个小时发布的帖子会显示为第二天，daysRunning 也少算一天。
• 筛选条件与之一致：publishedAfter 和 publishedBefore 为 UTC（只写日期表示当天开始，publishedBefore 列出该时间之前的帖子），minDaysRunning 和 maxDaysRunning 与 daysRunning 一样按 UTC 日计算，sortBy=longestRunning 从 2016年8月31日 22:00 UTC 开始。

2026年10月20日的其他更新（Google 广告）：

• GET /v1/google-ads、POST /v1/google-ads/query 和 MCP 工具不支持 sortBy=longestRunning（也不支持 daysRunning），会返回 400 并说明原因：该排序按广告停止后仍继续累计的天数排名，会列出 Google 已不再展示的广告。
• Free 搜索中，如果 status=active 使前几个结果不足，响应会带有 meta.partial 和一条警告，说明在读取的广告中列出了多少条。
• 在 extra.shop 中，没有流量数据的网站不带 monthlyVisits（之前为 0），trafficGrowth30d 只在访问量大于 0 时出现；extra.shop.google 不包含为 0 的 totalReach 或 weeklyReach（从未报告），在没有统计到任何广告时也不包含为 0 的计数。
• 保存到看板的 Google 广告读取结果相同。

2026年10月20日的其他更新（店铺）：

• 在 GET /v1/shops/{shopId} 中，advertising.summary.reach30d 是最近 30 天按日期汇总的欧盟覆盖人数（之前是自开始追踪以来的总数，现在为 totalReach），spend30d 为该覆盖人数 x 9 / 1000，extra.estimatedSpendUsd 是自开始追踪以来的支出，extra.adsLaunched30d 汇总最近 30 天上线的广告；对于没有欧盟或英国覆盖人数的店铺，这些值均为 null。
• 店铺记录、店铺列表和邮件统计带有 nullReasons，它将字段路径映射到其为 null 的原因：not_shopify（销量和商品只对 Shopify 店铺进行估算）、no_estimate、not_measured、eu_uk_only、not_linked（没有 TikTok 主页）、not_on_tp、no_reviews、none_found。
• 在记录、列表和销量历史中，售出件数旁为零的销量估算记为 null；销量历史的 period=week 每周一个数据点。
• traffic.growth30d 是一个比例（-0.1543 表示 -15.4%），traffic.history 从第一个有访问量的月份开始。
• catalog.mainCategory 取自分类 ID（主分支中最具体的一个），并附带 catalog.categoryLeaves 和 productsCountCapped（25,001 是计数上限，表示 25,000 或更多）。
• 没有评价的 Trustpilot 页面，其评分为 null。
• 当 TikTok 数据是通过店铺的社交媒体资料，或通过按账号名找到的主页匹配到的时，tiktok.matchedBy 为 socials 或 handle（这是匹配结果，而非已有的关联）。
• advertising.mainPageActiveAds 是主主页的在投广告数（取自其广告概览的读数，与 linkedAdvertisers 中其主主页显示的一致；店铺列表中的计数仅在没有该读数时显示），linkedAdvertisers[].rank 是该主页的排名。
• 相似店铺不包含店铺本身及其自有网站，每一页会用列表中更靠后的店铺补足（offset 和 limit 按排除它们之后的列表计数）。
• 按热度排序的商品会把店铺的畅销商品排在最前面（meta.order）。
• 店铺的邮件和邮件统计会计入所有营销活动类型，其 90 天数据在未知时为 null。
• 按销量排序时，每个 Shopify 店铺只列出一行（extra.sharedSalesWith），sortBy=estMonthlySales&order=asc 会排除没有估算值的店铺。

2026年10月20日的其他更新（店铺数据）：

• GET /v1/shops 按销量排序时，会继续读取被合并为每个 Shopify 店铺一行的域名之后的内容（之前在最初几行后就停止了），也会合并列表中更靠后的同一店铺的域名，并且在列表读取到末尾之前，其 pagination.total 为 null；sortBy=estMonthlySales&order=asc 从 100 USD 的估算值开始（minMonthlySales 100）。
• 在记录、列表和销量历史中，每件售出商品低于 0.50 USD 的销量估算记为 null（no_estimate）。
• 对于尚未测量的网站，traffic.monthlyVisits 为 null；当上个月没有访问量时，traffic.growth30d 为 null（not_measured）；当社交网络的 growth30d 为 0 或缺失时，会根据其粉丝历史计算，0 个粉丝记为 null（not_measured）。
• 店铺列表会说明 catalog.productsCount 和 sales.unitsSold 为 null 的原因。
• extra.storeWide 标记访问量为 0 但承载其店铺销量的域名（测得为 0，或该店铺的另一个域名拥有这些访问量，并在 extra.sharedSalesWith 中注明；Free 套餐的店铺记录中不显示该名称）。
• advertising.mainPageActiveAds 是其广告概览读取到的主主页在投广告数（店铺列表中的计数仅在没有该读数时显示）。
• 相似店铺也不包含该店铺的品牌店；对于相似度索引中没有的店铺，extra.similarIndexed 为 false。
• catalog.mainCategory 仅当原有标签是某个分类的名称时才保留该标签。
• 如果响应中链接的媒体文件已不存在，请求会返回 200、空响应体和 X-Media-Missing: true。

2026年10月20日的其他更新（广告主和 Meta 广告）：

• 广告主的覆盖人数是欧盟和英国的覆盖人数，采用广告主搜索自己的时间窗口：对于没有欧盟或英国广告且没有覆盖人数的主页，或尚未统计的时间窗口，advertising.reach30d、extra.reach14d、reach90d 和 totalReach 为 null，nullReasons 会说明原因（eu_uk_only、not_measured）；在某个时间窗口内创建的主页，其全部覆盖人数都计入该窗口（之前为 0）。
• 在 GET /v1/advertisers/{advertiserId} 中，覆盖人数与广告主列表中显示的一致（之前读取的是 30 个读数之前的值，而读数会跳过某些日期），支出估算随之为 null；extra.avgSpendUsd14d 是 14 天的日均支出；extra.avgActiveAds14d 是其在投广告的 14 天平均值（之前是 14 天内的新广告），在没有现成计算值时，对于 14 天内创建的主页，根据其创建首日以来读取的在投广告计算（extra.averagedFrom），否则为 null；在时间窗口内创建的主页，其新广告计数会计入它的每一条广告。
• advertising.countryDistribution 是其在投广告中定向各个国家的占比（一条广告会定向多个国家），extra.reachCountries 包含各国家在欧盟覆盖人数中的占比，extra.platforms.meta 包含该主页自己的广告（之前包含的是店铺主主页的广告），没有数值的 TikTok 或 Google 计数会被省略，extra.mainLandingPages 会回退到新主页落地页的预览；对于广告搜索尚未收录其广告的主页，lastAds 为其广告主行列出的最新广告，并附带 meta.indexing，与 GET /v1/advertisers/{advertiser_id}/ads 一致（附带 meta.liveAds）。
• 新增：GET /v1/advertisers/{advertiserId}/history，按日列出主页的在投广告及其新增的欧盟覆盖人数。
• Instagram 粉丝数为 0 时记为 null（主页没有已知的 Instagram 账户时会记为 0）。
• 对于未在欧盟或英国展示的广告（eu_uk_only；之前为 0 或 null），以及覆盖人数尚未统计的欧盟广告（not_measured；之前为 0），Meta 广告的 metrics.reach 及其支出为 null，媒体行会在 nullReasons.reach 中说明原因；包含多张图片或多个视频的广告，其 media.type 为 carousel；extra.startIsFloor 标记开始于 2018年1月1日（Meta 广告日期数据的第一天）的广告。
• 无论排序方向如何，sortBy=adRank 都会把最佳排名（1）排在最前面。
• 单条广告（GET /v1/ads/{adId}）采用最新报告的覆盖人数及其支出，在其覆盖人数历史为最新时按日期计算覆盖人数增量（否则为 null），像其搜索结果行一样列出其图片和视频，填充 advertiser.reach30d 和 pageAnalytics.instagramFollowersHistory，新增 pageAnalytics.reachHistory（与 impressionsHistory 为同一序列），并为记录中仅给出 ID 的店铺补上名称（网站尚未测量时，其 traffic 为 null，并带有 nullReasons shops.traffic）；其 audience.gender、ageMin、ageMax 和 metrics.aggregatedReach 始终为 null，因为单条广告不提供这些数据。
• 在广告主搜索中，sortBy=reach 按自开始追踪以来的总覆盖人数排名，newAds 按 14 天内的新广告排名。
• Meta 广告的定向决定了其覆盖人数为 null 的原因：只有不定向任何欧盟或英国国家的广告才是 eu_uk_only；定向了其中某个国家、或定向尚不明确的广告，在前 7 天为 not_measured，之后为 not_reported（之前为 eu_uk_only），这适用于广告列表、媒体行和单条广告。
• 单条广告会把其覆盖人数历史和支出历史作为同一个序列读取，每天一个读数（其增量也是如此）；当记录中的覆盖人数超过该序列最后读数的两倍、且该序列一直延续到广告的最后一天时，采用该序列的最后读数及其支出；其 media 会回退到其列出的第一个文件，advertiser.totalReach 会回退到主页详情中的欧盟覆盖人数。
• 如果广告主记录的行中没有读取到覆盖人数，而主页详情中读取到了，则采用主页详情的覆盖人数（extra.totalReach、其支出，以及据此计算的 advertising.reach30d）；其 extra.reachCountries 占比绝不会被四舍五入为 0，extra.averagedFrom 绝不会早于主页的创建日期，其每日历史（extra.history、GET /v1/advertisers/{advertiserId}/history）不包含缺失的读数（两个大于 0 的读数之间连续 14 天或更短的 0）。
• 采用序列读数的单条广告会把记录中的覆盖人数保留在 extra.recordReach 中（即广告列表显示的数字）；在广告主搜索中，如果某一行没有读取到欧盟覆盖人数，而主页详情中读取到了，则与其记录一样采用主页详情的覆盖人数；对于目前没有欧盟广告、但在所请求的日期之前获得过覆盖人数的主页，GET /v1/advertisers/{advertiserId}/history 会保留其为 0 的读数（它没有新增覆盖人数；之前这些读数作为 not_measured 被省略）。
• 在 Free 套餐中，覆盖人数未知的广告会像在付费套餐中一样说明原因；只有套餐不包含的覆盖人数没有原因。

2026年10月20日的其他更新（支出估算）：

• 低于 10 USD 的预估支出保留两位小数：按每覆盖 1,000 人 9 USD 计算，覆盖人数 140 对应 1.26（之前为 1），日均值也保留自己的美分；10 USD 及以上的支出估算取整数美元（覆盖人数 2,000 对应 18）。
• 这适用于广告主记录的 extra.estimatedSpendUsd 和 extra.avgSpendUsd14d、店铺的 advertising.summary.spend30d 和 extra.estimatedSpendUsd、Meta 广告的 metrics.estimatedSpend，以及品牌追踪的 statistics.euData.estimatedSpend30d 和每个 /time-series 数据点的 estimatedSpend（这两者之前在任何金额下都保留两位小数），API 和 MCP 工具均是如此。如果原有数值是以整数美元表示的该估算，也会以同样的方式保留美分。

2026年10月20日的其他更新（广告主覆盖人数和每日历史）：

• GET /v1/advertisers/{advertiserId} 新增 extra.reachScope：对于按国家统计的覆盖人数大部分出现在欧盟和英国以外的主页，其值为 outside_eu_uk（部分在其他地区展示的广告也会报告覆盖人数；此时其覆盖人数及据此得出的估算即为该覆盖人数，而非欧盟覆盖人数），否则为 eu_uk。对于 14 天内创建的主页，其 extra.avgSpendUsd14d 为创建以来完整天数内的支出（至少一天；之前在广告主行有数据时，是 14 天覆盖人数除以 14 天）。
• 广告主记录的 extra.history 和 GET /v1/advertisers/{advertiserId}/history 从主页创建当天开始；extra.history.newAds 不包含缺失日期的 0，extra.followersHistory 以及广告的 pageAnalytics 中的点赞数和粉丝数不包含两个大于 0 的读数之间的 0 或此类日期的 0，每日支出估算在 10 USD 以下保留两位小数。
• 如果某个主页的在投广告尚未被任何列表收录，其记录会带有 meta.indexing，GET /v1/advertisers/{advertiser_id}/ads 的第一页为空，并带有 meta.indexing 和 meta.liveAds。
• 单条广告（GET /v1/ads/{adId}）：extra.spendHistory 从广告开始投放当天开始，每个 spendUsd 在 10 USD 以下保留两位小数；advertiser.totalReach 绝不会低于 pageAnalytics.reachHistory 的最后读数（此时 extra.pageRecordReach 保存记录中的总数，即广告主列表显示的数字）；extra.recordSpend 是 extra.recordReach 对应的支出；extra.reachScope 和 extra.pageReachScope 说明广告及其主页的大部分覆盖人数出现在哪里。

2026年10月20日的其他更新（品牌追踪）：

• 在 GET /v1/brandtrackers 和 GET /v1/brandtrackers/{id} 中，如果最近 7 天有新投放，而 advertising.newAdsLastDay 为 0，系统会对照店铺昨天的新投放进行核对：取其数量，若当天没有读数则为 null（not_measured）；列表每次调用最多核对 20 个品牌，即所请求页面上的品牌。
• 在 /top-ads 和 /v1/workspace/top-ads 中，metrics.totalReach 是广告的欧盟覆盖人数：对于在欧盟和英国以外展示的广告（eu_uk_only）或尚未统计的欧盟广告（not_measured），其值为 null 并带有 nullReasons，在按覆盖人数排序时排在最后（之前为 0）。
• /testing 根据覆盖人数已知的广告计算其覆盖人数统计；对于没有此类广告的批次，带有 nullReasons stats.reach。
• 在 /hooks、/transcripts、/landing-pages 以及工作区的开头钩子和落地页中，为 0 的 totalImpressions 记为 null，并带有新的原因 no_eu_reach（其广告没有统计到欧盟或英国覆盖人数；与 euOnly 一起时为 not_measured），在排序中排在最后。
• 在 /ad-rank、/scaling-ads 和 /v1/workspace/scaling-ads 中，如果广告的排名历史开始于 14 天或 30 天时间窗口之内，metrics.previousRank 和 rankDelta 从其在窗口内最早的读数开始计算：metrics.since 为该日期，meta.windowNote 会加以说明，无法给出的数值为 null 并带有 nullReasons。
• 在 /partners 中，对于店铺的主主页、与品牌同名的官方主页以及以品牌命名的主页（创作者也可能被列为官方），isOwnPage 为 true；为 null 的覆盖人数或支出带有 nullReasons。
• 带有 adCopyHashes 的 /ads 第一页包含 meta.latestAdDate 和 dataFreshnessLagDays，使用 status=active 时还包含 meta.stoppedCount。
• /demography 是欧盟和英国的受众，低于第一名国家万分之一的国家会从 countryDistribution 移到 otherCountries。
• /ad-copy-evolution 和 /headline-evolution 在每个有记录的日期都有一个数据点（未使用该文本时为 0，在按保留的文本截断的日期为 null），按最新日期对文本排名，并且不包含读数有误的日期（在投广告不到前后日期的十分之一，单日或连续 2 到 3 天，或文本数量远少于两侧日期），正如 meta.periodNote 所说明的；meta.recordedDays 统计日期数。每周和每月 /time-series 的在投广告同样不包含连续 2 或 3 个此类读数。

2026年10月20日的其他更新（品牌追踪报告、lookup 和 Google 覆盖人数）：

• 在 /ad-rank、/scaling-ads 和 /v1/workspace/scaling-ads 中，每一行的所有排名都来自广告的排名历史：metrics.currentRank 是广告库读取排名当天的读数（即 /top-ads 显示的排名；广告库可能比历史晚一天），否则为其最新读数；trajectory 截止到该日期；如果时间窗口开始当天没有读数，则以窗口内最早的读数为准（不再使用原有的窗口期变化值）。
• 广告库的前 50 条广告（跨品牌时每个品牌 10 条）会根据这些数值重新排名：按这些数值计算，上升幅度小于 minRankDelta 或排名低于 maxCurrentRank 的广告会被排除（即按广告库自身的计数，排名历史显示没有上升的广告），pagination 涵盖保留的广告，meta.rankNote 说明读取和排除了哪些内容，跨品牌时也是如此。
• 每日 /time-series（以及概览的 graph）在以下日期为 null：在投广告读数有误的日期（低于其前后两侧日期的十分之一；最新一天保持读取值，文本演变中也是如此），这些日期的新投放也是如此；当后一天的新投放几乎全是其在投广告时，后一天的新投放同样为 null；周和月数据不包含这些新投放，leftOut 列出这些日期。/landing-page-evolution 会从每个页面中排除这些日期，以及页面自身低于两侧读数十分之一的读数，正如其 meta.periodNote 所说明的，并在历史滞后时注明历史所到达的日期。
• 没有统计到覆盖人数的 /testing 批次带有 nullReasons stats.reach no_eu_reach，除非其中某条广告尚未统计（not_measured）或所有广告都在欧盟和英国以外展示（eu_uk_only）；/partners 行中缺失的覆盖人数和支出，仅在其 launchDate 之后 7 天内为 not_measured，之后为 no_eu_reach。
• /creatives 把包含多张图片或多个视频的广告标为 carousel（之前为 unknown）。
• 在 GET /v1/lookup 中，对于尚未测量的网站，店铺的 signals.monthlyVisits 为 null（nullReasons not_measured；之前为 0）；精确匹配的店铺行的在投广告（所有 type，包括 shop）为其广告概览读取到的主主页在投广告，即其 mainPageActiveAds，店铺自有主页的行也以同样方式读取；对于尚未测量的网站，追踪品牌的 signals.monthlyVisits（以及 GET /v1/brandtrackers 中的 totalTraffic）为 null，并说明缺失原因（not_measured，或对于没有店铺的主页为 no_shop）；在 Free 套餐中，任何套餐都没有的主页覆盖人数会保留其原因（eu_uk_only、not_measured），广告主列表中也是如此。
• Google 广告为 null 的 reach.value 带有 nullReasons（not_reported、eu_only），套餐不包含的覆盖人数除外。
• 在 GET /v1/shops/{shopId} 中，advertising.mainPageActiveAds 是其广告概览读取到的主主页在投广告数，即 linkedAdvertisers 中其主主页显示的数字（之前是店铺索引中的计数，可能晚一天）。

2026年10月20日的其他更新（TikTok 和邮件）：

• TikTok 行的 metrics.engagementRate 为（点赞 + 评论 + 分享 + 收藏）/ 观看次数，以比例表示（0.0513 表示 5.13%；之前搜索返回的是百分比，GET /v1/tiktok/library/{itemId} 返回的是另一项指标），daysRunning 在两者中都是帖子发布以来的天数。
• metrics.rank 是该帖子在其创作者所有帖子中的排名（1 为最佳）。
• 尚未统计粉丝数时，profile.followers 为 null（之前返回 0）；对于兜底分类 All，content.category 为 null；content.hashtags 是帖子的标签，每个只出现一次，拼写与描述中一致，且不带其后的标点（记录中的标签取自原有的标签列表，搜索结果行中的标签取自描述）。
• TikTok 记录新增 profile.adsCount、organicCount 和 avgPostsPerWeek90d，填充 profile.pageCreation；对于背后没有对应 TikTok 内容的数据行（ID 少于 15 位，或发布于 2016年8月31日 22:00 UTC 之前），links 为 null。
• sortBy=longestRunning 从最早的 TikTok 开始（2016年8月31日 22:00 UTC）。
• 邮件记录会注明其促销类型、分类和节日活动，其店铺的月访问量、在投广告、商品和 90 天数据与邮件列表中显示的一致，邮件统计的 last90Days 数据也是如此。
• 对于没有广告总数的 0，邮件行会省略 extra.shopActiveAds（其 nullReasons 为 not_measured），此时邮件记录的 shop.marketing.activeAds 为 null；当店铺数据无法读取时，记录会带有 meta.partial、一条警告以及针对这些数据的 nullReasons failed。
• 在 MCP 工具 analyze_shop_emails 中，dominant 会分别对营销活动类型、分类、促销类型和节日活动进行排名，并排除 No Promotion 和 No Event。

2026年10月21日更新：

• 在搜索和 GET /v1/tiktok/library/{itemId} 中，如果返回的观看次数为 0，而点赞、评论、分享或收藏大于 0，则 TikTok 条目的 metrics.views 以及旁边读数为 0 的 likes 和 saves 为 null，并带有 nullReasons not_measured（engagementRate 也是如此）；sortBy=views 或 likes 配合 order=asc 时，会列出已统计观看次数的帖子（minViews 1）。
• 带有 websiteIds 的 Meta 广告搜索会列出店铺自己的广告：店铺主主页及与其同名的官方主页的所有广告，以及其他主页（为其投放广告的创作者、发布者和合作方）中链接到该店铺或其域名下网站的广告；在列表读取到末尾之前，此时搜索的 pagination.total 为所搜索的店铺自有主页的广告数，是一个估算值（pagination.totalEstimated 为 true），如果搜索未包含其任何自有主页，则为 null。
• 使用 sortBy=longestRunning 时，每批读取的广告都会按 daysRunning 排序。
• 在 GET /v1/shops/{shopId} 中，advertising.activeAds 统计店铺自有主页（linkedAdvertisers[].isOwnPage）的在投广告；在其 /products 中，排名靠前的畅销商品采用 catalog.bestSellers 中的标题、价格和图片（畅销商品的价格可能是其各变体中的最低价）。
• 在记录、店铺列表、相似店铺和 lookup 中，如果店铺的流量历史在有大于 0 的销量估算和售出件数时降为 0，导致读数为 0，则其 traffic.monthlyVisits（以及 growth30d）为 null，并带有 not_measured；此类域名仍为 extra.storeWide。
• 在 GET /v1/ads/{adId} 中，当 pageAnalytics.reachHistory 的最后读数不超过 2 天时，advertiser.totalReach 为该读数（此时 extra.pageRecordReach 保存记录中的总数）；extra.advertiserTotalAds 取自主页的列表数据（没有时为 not_measured）；在时间窗口内开始投放的广告，其 7 天和 30 天覆盖人数增量即为其全部覆盖人数；低于更短天数增量的增量为 null（not_measured）。
• 品牌追踪的 statistics.ctaCount 会像 content.callToAction 一样命名每个行动号召（「Shop now」）。

2026年10月21日的其他更新（店铺）：

• 在 GET /v1/shops/{shopId} 中，所有套餐的 advertising.history 都是主主页每日的在投广告（在 Free 套餐中之前统计的是所有主页的），文档说明 advertising.summary 的覆盖人数和支出、extra.adsLaunched30d、extra.totalAds 和 extra.estimatedSpendUsd 涵盖店铺的所有主页，而 advertising.activeAds 统计的是其自有主页。
• 在记录、店铺列表以及 GET /v1/shops/{shopId}/products 的 meta.productsCount 中，如果店铺的 catalog.productsCount 为 0 且没有列出任何商品，但有访问量、销量估算或售出件数，则其值为 null，并带有 not_measured；sortBy=productsCount 会排除这些店铺，配合 order=asc 时，除非指定了商品数量下限，否则会发送 minProductsCount 1。
• 如果某个店铺的 Meta 广告搜索被限定在非其自有的主页（trackedPages）并提前结束，会在 meta.warnings 中说明原因，而不会要求缩小范围。
• 当没有可列出的取值时，GET /v1/filters/shops 会在 meta.warnings 中说明，并指出提供这些取值的列表。

2026年10月21日的其他更新（分页、邮件和广告列表）：

• 当广告主搜索无法继续翻页时，分页不再失败（之前会返回 503，重试也无济于事）：前 100 个结果会在一次调用中读取，到达可读取内容末尾的那一页返回 hasMore false，并带有 meta.partial true 和一条说明搜索可读取范围的警告。
• 起始位置超过搜索精确 total 的页面为空，hasMore 为 false。
• 按 views 或 likes 排序且 order=asc 的 TikTok 搜索，与 longestRunning 一样从最早的 TikTok 开始（2016年8月31日 22:00 UTC）；当 TikTok 条目的观看次数少于点赞数时，其 metrics.views（以及 engagementRate）为 null，并带有 not_measured。
• 如果返回的是尚未读取正文时的占位内容，邮件的 content.bodyPreview 和 bodyLength 以及记录的 content.body 为 null，并带有 not_measured。
• 以 UTC 表示的日期时间在列表和记录中采用统一的写法，带有 +00:00，且秒的小数部分不带末尾的零（2026-09-30T00:20:11.507+00:00；您自己的看板、收藏、品牌追踪和分享链接的创建或修改时间与以前一样以 Z 结尾）；邮件行会像邮件记录一样带有其分类、促销类型和节日活动的 ID。
• 所有分页列表都会返回 pagination.hasMore，GET /v1/google-ads/facets/countries 会返回一个 pagination 对象。
• 请求体不是有效 JSON 时，会返回 400 validation_failed，消息为「The request body is not valid JSON.」，并附带 details.position，即中断处的字符位置。
• 在 Meta 广告列表中，行的覆盖人数是广告索引的读数，可能比广告记录晚一天；在没有增量数据时，已知覆盖人数旁的覆盖人数增量为 null（not_measured），但广告在其中开始投放的时间窗口除外，此时它获得了其行读数中的全部覆盖人数；在 GET /v1/ads/{adId} 中，已知覆盖人数旁为 null 的增量同样带有 not_measured。

2026年10月22日更新（Free 套餐）：

• API 和 MCP 服务器改为仅限付费套餐：当时，Free 套餐账户的密钥在除 GET /v1/account 外的所有端点都会返回 403 plan_not_eligible，并附带 details.upgradeUrl，且不计任何用量。当时 Free 套餐无法创建任何密钥。
• 此后 Free 套餐已有变化：Free 套餐一节说明了它现在包含的内容。
• 在付费套餐中创建的密钥会被保留，账户恢复付费套餐后即可立即恢复使用。Free 套餐账户创建的分享链接也会以同样的方式暂停。

2026年10月22日的其他更新（店铺报告和记录）：

• 在 GET /v1/shops/{shopId}/ad-ranking/series 中，rankDelta 是结束排名减去开始排名（广告排名上升时为负值，与所有广告一致；之前是上升的名次数），improvementPercent 现在改为 improvementPct，以比例表示；/ad-ranking 的每一行都会在 rank 中带有排名窗口期内的这两个数值。
• 在追踪品牌的 /activity/calendar、日历中的某一天以及 /activity/calendar/days 中，meta.partial 为 true 或 false，meta.partialSources 列出仅读取了部分内容的渠道（见于 /calendar 和单日），预览时间为 UTC，TikTok 帖子的预览时间也是如此。
• 在 GET /v1/shops/{shopId}/landing-pages/detail 中，activeAds 会回退到该页面的广告，shareOfAds 为 linkedAdsTotal 占 shopActiveAds 的比例，snapshots 统计该页面被截取的天数，lifetimeAds 和 impressions 已移除（展示次数其实就是覆盖人数），为 0 的覆盖人数记为 null，并带有 nullReasons.reach no_eu_reach，linkedAds 带有广告搜索结果行的字段。
• 店铺的 /feed 会像其广告搜索一样列出它自己的 Meta 广告。
• GET /v1/market/q4-overview 接受旺季内的任意 from 和 to。
• 在 /q4-season 中，winners 列出每个促销节点的键及其素材，落地页 URL 带有协议头。
• Shopify 检测器按不带 www. 的域名读取店铺。
• GET /v1/advertisers/{advertiserId} 以及追踪品牌的落地页、受众和媒体构成会在 meta.snapshotDate 中返回过去的某一天。
• 当店铺的 Meta 广告统计数据暂时无法读取时，GET /v1/shops/{shopId} 会返回 meta.partial true 和一条警告：其覆盖人数、据此得出的支出估算以及媒体和格式构成为 null，并带有 nullReasons failed；其各国家广告按搜索结果行的数据计算；该响应不会被缓存，因此下一次调用会重新读取（竞争对手简报带有同样的 meta.partial 和警告）。
• 位于店铺自有域名或其子域名上的落地页，在 /v1/shops/{shopId}/advertisers 和 /advertisers/{advertiserId}/landing-pages 中为 toShop true；当店铺的域名中没有该域名时，meta.domains 会根据其主页的落地页把它列在最前面（fromLandingPages true，为下限），主页的 shopAds 绝不会少于其落地页指向该店铺的在投广告数（被调高时 shopAdsAtLeast 为 true）。
• 在 GET /v1/tiktok/library/{itemId} 中，profile.latestPosts[].mediaUrl 是帖子的视频，或为 null 并带有 nullReasons not_reported（之前是封面图片）。
• 广告主搜索读取其前 100 个结果，并在到达第 100 个结果的那一页说明已结束（hasMore false 及警告），而不是在其后的空白页上说明。
• 按 views 或 likes 排序且 order=asc 的 TikTok 搜索，现在会排除观看次数未统计（观看次数少于点赞数）的帖子，在列表读取到末尾之前，其 pagination.total 是一个估算值（totalEstimated）；其他所有排序都会列出这些帖子，其观看次数为 null。

2026年10月22日的其他更新（已保存内容和广告开头钩子）：

• 新增：GET /v1/boards/search 可在所有看板和您的收藏中查找您保存的内容，依据每个已保存副本所显示的文字（每个词都必须出现，顺序不限；忽略大小写和重音）、其 ID 或其看板名称，并接受 sourceType、boardId、savedFrom 和 savedTo；它只读取您保存的内容，不会查询实时数据（MCP find_saved_items）。
• 新增：POST /v1/tools/ad-hooks 为您商品的广告撰写三句简短的开头文案，GET /v1/tools/ad-hooks 返回您的额度：付费套餐没有每月上限，但有每分钟限制（429，附带 Retry-After）；读取额度不计入用量（MCP write_ad_hooks）。
• MCP 服务器共有 64 个工具。

2026年10月23日的其他更新（已保存视图和店铺筛选）：

• 新增：GET /v1/views 列出您在网站列表页面上保存的搜索，每个都附带其执行的搜索（request：搜索内容、searchType、sortBy、order 和命名筛选项，格式与搜索端点接受的一致）；POST /v1/views 保存一个视图，PATCH /v1/views/{viewId} 重命名、移动或修改视图，DELETE /v1/views/{viewId} 删除视图。它们只读写您自己的视图，不会查询实时数据（MCP list_saved_views）。
• 店铺搜索接受 excludeCurrencies（货币代码，例如 EUR）、socialNetworks（instagram 或 tiktok：拥有其中任意一个的店铺）和 shopifyPlan（headless）。trafficGrowth 还可读取 90 天（min90、max90），adsGrowth 可读取 7 天（min7、max7），或规则的 period（last90d、last7d）；min 和 max 仍为最近 30 天。
• MCP 服务器共有 65 个工具。

2026年10月23日的其他更新（商品链接）：

• 在 GET /v1/shops/{shopId} 中，catalog.bestSellers 的每一项都带有 handle 和 productUrl，即该商品在店铺自有网站上的页面：当已有地址位于店铺域名（或其子域名）或其 myshopify 域名上时，取该地址；否则在已知其 handle 时为 https://<domain>/products/<handle>；否则为 null。
• 在 GET /v1/shops/{shopId}/products 中，productUrl 遵循同样的规则，因此不再给出其他网站上的地址；当 handle 不是地址中单独的一段时，其值为 null。

2026年10月23日的其他更新（店铺行、相似店铺和商品）：

• 店铺的 createdAt（店铺记录、店铺行和相似店铺）仅表示 Shopify 店铺的创建日期。对于非 Shopify 网站，给出的日期是开始追踪该网站的日期，而非其创建日期：createdAt 现在为 null（nullReasons tracking_date），该日期改为新的 trackedSince。2000年1月1日或更早的日期是占位值，记为 null（not_reported）。
• 店铺行的 catalog.bestSellers 带有 handle、productUrl（规则与店铺记录相同）和 rank（1 为最畅销），各行还会像店铺记录一样带有 profile.isHeadless 和 catalog.myShopifyDomain。
• 店铺行的 googleAds.reach.value 为 null：店铺行不包含 Google 覆盖人数，该数据位于店铺记录中（extra.googleAds.reach）。
• 相似店铺（GET /v1/shops/{shopId}/similar、记录中的 similarShops）保留其 extra（标志、Trustpilot、销量历史）。如果相似店铺列表在到达末尾前中断，到达该处的那一页会返回 meta.partial 和一条警告。
• 在 GET /v1/shops/{shopId}/products 中，createdAt 和 publishedAt 之前是以 UTC 形式发送的店铺本地时间（对于使用美国太平洋时间的店铺，早了 8 小时）。现在它们是根据店铺相对 UTC 的时差（meta.shopUtcOffset，例如 -08:00）换算的 UTC 时间，并新增 updatedAt。无法读取时差时，这三个值为 null（local_time），createdAtLocal、publishedAtLocal 和 updatedAtLocal 给出不带时区的店铺本地时间。
• 仅出现在店铺详情畅销商品中的商品，其 publishedAt 和 updatedAt 为 null（not_reported）：原有的这两个值只是其创建时间的副本。
• 每个商品都会说明它出现在哪些列表中（lists：bestSellers、newest），以及它在畅销商品中的位置（listPosition，1 到 100）。

2026年10月23日的其他更新（店铺记录）：

• 在 GET /v1/shops/{shopId} 中，extra.googleAds.reach.value 之前始终为 null：现在它是店铺的 Google 欧盟覆盖人数，带有 lowerBound 和 upperBound，extra.googleAds 新增 reachHistory、history（按周统计的被标记为在投的 Google 广告）、updatedAt 和 latestAds。
• 社交网络的 growth30d 现在是粉丝概览的 30 天变化（之前对部分 Facebook 主页使用的是另一个时间窗口：变化为 0.2898 时显示的是 0.3636）。GET /v1/shops/{shopId}/socials 也以 growth30d 提供该值。
• 店铺的 X 主页为 socials.x。socials.twitter 已更名为 socials.x，但在一个版本内仍会保留，且为同一对象。每个网络都有 url，socials.others 列出店铺的其他链接。
• tiktok.profileMetrics.percentAds 是百分比（0 到 100）；新增的 adsShare 是同一数值的比例形式。tiktok 新增 avatarUrl、history、postsChange30d、postsChange30dPct 和 latestAds；之前为 null 的 tiktok.activity.avgActiveAds7d 和 avgActiveAds30d 现在按日计算其 TikTok 广告的平均值。
• 付费套餐新增：advertising.summary.firstAdSeenAt、longestRunningDays、medianRunningDays、landingPagesCount，以及在投广告、新投放广告和欧盟覆盖人数的 30 天变化（activeAdsChange30d、launchedChange30d、reachChange30d，每项也有以 Pct 结尾的比例形式），还有 advertising.runningDaysMix、reachCountries、reachHistory、topLandingPages、adsByAgeRange 和 adsByGender。所有套餐新增：advertising.allPagesHistory 和 advertising.topCountries[].ads。
• 新增：catalog.bestSellers[].rank、sales.hasSubscription、technology.apps[].appStoreUrl 和 categories、profile.isHeadless、extra.updatedAt，以及上述店铺日期中的 createdAt 和 trackedSince。
• GET /v1/shops/{shopId}/advertisers 新增每个主页的 logoUrl 和 moreLandingPages、在广告概览中没有时补上的 profileUrl，以及每个域名的 landingPagesCount 和 moreLandingPages。

2026年10月23日的其他更新（商品）：

• 新增：GET /v1/products 和 POST /v1/products/query 可搜索和浏览店铺商品，每个商品都附带价格、销量估算、售出件数、评价、畅销排名、Meta 广告、欧盟覆盖人数和支出、销售国家、上架日期和所属店铺，可按 relevance、newest（上架日期）、activeAds 或 spend（最近 30 天的欧盟广告支出）排序（MCP search_products）。searchType 将文本与商品名称或其店铺域名进行匹配，命名筛选项可限定以 USD 计的价格、在投广告数、广告占比、评价数和上架日期，并接受货币和订阅；GET /v1/filters/products 列出它们接受的货币。
• shop（某个店铺的域名或 ID）在商品搜索和 search_products 中只列出该店铺的商品，且不能同时带有搜索文本。看板会按搜索最后一次显示的样子保存商品（sourceType product），对所有已保存内容的搜索可按其标题和店铺找到它们。
• MCP 服务器共有 73 个工具。

2026年10月23日的其他更新（商品筛选）：

• 商品搜索还支持更多命名筛选：某月或某日的销量估算（minEstMonthlySales、minEstDailySales 及对应的最大值；按日设置的界限按 30 天折算），每月或每日售出件数（minUnitsSoldMonthly、minUnitsSoldDaily），sellingCountries（销往其中任一国家的商品），shopCountries，评分（minRating、maxRating），minAdsLaunched（过去 30 天上线的 Meta 广告数），minSpendShare，minEuReach（30 天内的欧盟覆盖人数），hasPartnershipAds，promoTypes（百分比折扣）以及 minShopProductsCount，有最大值的筛选均可同时设置最大值；GET /v1/filters/products 也会列出店铺所在国家。
• sortBy 可取 estSales（销量估算）、adPressure（广告占比）和 bestSelling（在其店铺内的畅销排名，第 1 名在前），searchType 可取 productDescription 和 url。
• 每个商品都带有其最新广告（advertising.latestAds，图片在 advertising.previewUrls 中）和按周数据（weeks：在投广告、广告占比、欧盟每日支出和覆盖），bestSeller.rankPercent 是其排名占店铺商品总数的百分比（越低越好）。

2026年10月24日更新（参数、读取失败和深层分页）：

• 路由不读取的查询参数现在会以 400 validation_failed 拒绝，错误信息会指出该参数并列出该路由接受的参数；以前它会被直接忽略，不作任何提示（拼错的参数名，或发给不支持筛选的路由的筛选，都会被当作从未发送）。搜索仍像以前一样拒绝未知的命名筛选。普通参数（country、mediaType、active、type）若与某个命名筛选设置同一个筛选，且取值不同，同样会被拒绝。
• 品牌追踪：/ads 和 /timeline/metadata 拒绝过去的 snapshotDate（它们读取的是广告库的当前状态），/partnership-ads 拒绝未知的 sortBy，/v1/workspace/scaling-ads 拒绝未知的 period，追踪列表拒绝早于 30 天前的 hasNewAdsSince（新广告计数只覆盖 30 天）。/v1/workspace/hooks、/ad-copies 和 /landing-pages 会先按请求的 sortBy 和 order 读取每个品牌的行，再进行合并。网站的跨品牌报告只向会读取 euOnly 的报告发送该参数。
• 相似店铺拒绝 filters 中的 displayInTrending（该列表没有店铺索引标记），并像店铺搜索一样把增长界限读作百分比；超出单次请求可读范围的 offset（在已读取的店铺之后再往后 600 家）会以 400 拒绝，并说明最深可以读到哪里；读取中途停止的页面带有 meta.partial 和一条警告。店铺的 TikTok 广告库拒绝账号和网站筛选（由店铺自身的范围代替）。
• 应答中本次未能读取的部分会设置 meta.partial 并附一条警告（该应答不会被缓存），绝不会悄悄留空或返回空列表；读取到的应答不是 JSON 时，返回 503 upstream_error；已保存的店铺、新建的追踪或邮件选项列表读取失败时，返回该错误，绝不返回 not_found。对于单次读取会遗漏行的列表，超出单次读取深度的页面带有 meta.partial，且 hasMore 为 true；品牌的广告文案、合作方和素材测试在单次读取无法覆盖该品牌时，会通过 meta.partial 说明。
• GET /v1/google-ads/facets/networks 与其他选项列表一样，接受 search、limit 和 offset。/v1/shops/compare 的 metric 为必填（参考文档曾写作可选）。
• MCP：工具会拒绝其所选类型不读取的参数（shop_report、lookup_filter_ids、market_overview、scan_advertiser）以及相互矛盾的参数（trend_signal 与 sort_by、active_only 与 status、命名参数与 filters）；creative_inspiration_pack 会把所有关键词的广告放在一起排序。

2026年10月24日的其他更新（以图搜索）：

• 新增：POST /v1/products/image-search 查找与图片相似的店铺商品，每个结果附带其店铺，最相似的排在前面。以 multipart/form-data 发送图片：不超过 10 MB 的 PNG、JPG 或 WEBP 文件（image），或图片直链（imageUrl），由我们自行下载。每一行都与商品搜索返回的商品行相同，另含 similarity（0.7 至 1）和 matchOnly（商品索引中没有记录的匹配：仅有标题、图片、价格、上架日期和店铺）。
• 该搜索接受商品搜索的命名筛选、sortBy（relevance、estSales、activeAds、adPressure、newest、spend、spend14d）和 maxPerShop（每家店铺最相似的 1、3、5、10 或 20 个匹配），每页最多 32 条。GET /v1/products/image-search/{searchId} 无需再次发送图片，即可读取其他页、排序、筛选以及按店铺的结果；GET /v1/products/image-search/history 列出您自己最近的以图搜索。
• 图片在搜索前会被重新写入为不含元数据（EXIF、位置、注释）的 JPEG，图片 URL 绝不会离开我们的服务器。新增错误：400 invalid_image、400 unsupported_url 和 422 unreadable_image。
• 在 Free 套餐中，以图搜索按相关度排序，不支持筛选。MCP 服务器共有 67 个工具：search_products_by_image 为新增工具。

2026年10月25日更新（点数）：

• API 和 MCP 服务器改为按点数计量，不再按请求计量：1 点 = 返回 1 个结果：一个品牌的详情、一条广告或列表中的一行。空结果不收费。每次调用按其返回的结果计费，各套餐的每月额度以点数计。
• 计量的应答会发送 X-Usage-Cost、X-Credits-Used、X-Credits-Remaining 和 X-Credits-Source；GET /v1/usage 在 credits.topup.balance 下报告充值点数。
• 当月点数和充值点数都用完后，返回 402 insufficient_credits，并附 details.upgradeUrl 和 details.topUpUrl。
• 速率限制由整个工作区共享。

分享链接（shareUrl）会在 https://sellwinners.com 上打开一个任何人都能查看的网页。同一条记录也可通过 /v1/shared/ads/{token} 和 /v1/shared/boards/{token} 以 JSON 获取。所有者使用 Free 套餐的链接会返回 403 forbidden，直到所有者重新使用付费套餐。

身份端点 /v1/me、/v1/usage 和 /v1/workspace 在顶层返回各自的对象，与 requestId 并列。系统端点 /v1、/v1/health 和 /v1/system/freshness 不带 requestId，且 /v1 和 /v1/health 返回不含 data 的普通对象。请求 ID 也会在 X-Request-Id 响应头中发送。联系支持时请提供该 ID。

看板、收藏和品牌追踪还提供 POST、PATCH 和 DELETE 端点。它们接受 JSON 请求体，需以 Content-Type: application/json 发送。

分页

列表端点接受 limit（搜索最多 100；分面列表最多 500，品牌的 /snapshots 最多 365），以及 page（1、2、3…）或 offset 二者之一。两者同时发送时，使用 offset。默认每页条数在各端点下列出。广告、Google 广告、TikTok、邮件和媒体列表的应答格式为：

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

店铺、商品和广告主列表，以及单个广告主的广告，应答格式为：

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

要获取下一页，请重复同一请求，并将 page 加一，或将 offset 加上 limit。在 POST …/query 请求体中，以字段形式发送 "page" 或 "offset"。最后一页的 hasMore 为 false。当搜索在某个位置之后无法继续读取时，到达该位置的页面会返回 hasMore 为 false、meta.partial 为 true，并附一条警告，说明最多可以读取多少条结果。分页最多可读取一次搜索的前 5,000 条结果（广告主搜索为前 100 条）。如需查看其他结果，请用筛选缩小搜索范围或更改排序。

Google 广告列表返回精确的 total，但按状态或投放天数规则缩小范围的列表除外（参见 Google 广告搜索）。"totalEstimated": true 表示该 total（及其 totalPages）在列表读到末尾之前是估算值，例如店铺的相似店铺，以及针对某个店铺的 Meta 广告搜索（websiteIds）。

看板、收藏和品牌追踪报告接受 page 和 limit，并返回 page、limit、total、totalPages 和 hasMore。分面列表、店铺的 /products 及其 /similar 相似店铺接受 limit 和 offset，并返回 limit、offset、total 和 hasMore。

排序与筛选

搜索端点接受 sortBy 和 order（默认 desc）。传入搜索词时，结果按 relevance 排序，除非您选择其他排序；不带搜索词时，默认为 newest（店铺和商品为 relevance，媒体为 reach）。Google 和 TikTok 广告搜索始终按相关度排序；在这两者中，sortBy 仅在不带搜索词浏览时生效。

每类数据都有一个 POST …/query 端点，接受包含 query、filters、sortBy、order、limit 和 page（或 offset）的 JSON 请求体，用于高级筛选。请使用分面端点查看筛选所接受的取值和 ID。

筛选可以按名称发送：作为 GET 搜索的额外查询参数（?status=active&minDaysRunning=30&mainCountries=US,GB），或作为 POST …/query 请求体的顶层字段（{"status": "active", "minDaysRunning": 30}）。下文每个端点都列出了它接受的名称。在搜索端点上，端点不支持的筛选名称会返回 400 validation_failed，并列出支持的名称，因此拼写错误绝不会悄悄返回未经筛选的结果；品牌追踪报告则会忽略它们不认识的名称。列表取值可用逗号分隔或用 JSON 数组，日期格式为 2026-01-31，原始的 filters 对象仍可与命名筛选一起使用。

增长筛选（trafficGrowth、adsGrowth、pageReachGrowth、adReachGrowth）接受写作 {"comparison": "greater" | "lower", "value": 50} 或 {"operator": "gte" | "lte", "value": 50} 的规则。取值为过去 30 天的百分比；不支持其他周期。minRankDelta 是广告在 rankDeltaWindow 内至少上升的名次数（默认 7d，也可发送 14d 或 30d）。hideSavedAds 会排除您已保存的广告。所有 categoryIds 筛选的类目 ID 均可从 /v1/facets/categories 获取。

速率限制与点数

1 点 = 返回 1 个结果：一个品牌的详情、一条广告或列表中的一行。空结果不收费。每个套餐都包含当月点数，于每月 1 日 00:00 UTC 重置。每次调用按其返回的结果计费，因此较小的 limit 花费更少；MCP 工具调用与 API 一样，按返回的结果计费。点数和速率限制按工作区计算：工作区中的每个人、其所有密钥、API 和 MCP 服务器共享同一个点数池和同一个速率限制。在付费套餐中，工作区所有者可以在账单页面购买充值点数（€1 可购买 120，起购 €10）：充值点数在当月点数用完后使用，可以结转，永不过期。

每个计量的应答都包含：

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

超过每分钟速率限制时，您会收到 429 rate_limited，并附 Retry-After 响应头（以秒为单位）。当月点数和充值点数都用完后，您会收到 402 insufficient_credits，并附 details.upgradeUrl 和 details.topUpUrl，直到每月点数重置。您可以随时通过 GET /v1/account 或 GET /v1/usage 查看点数。这些调用不消耗点数，仍会发送 X-Usage-Cost: 0、X-Credits-Used: 0 和 X-Credits-Remaining，即使点数已用完也能使用。

这些限制适用于 API 和 MCP 服务器，付费套餐和 Free 套餐均是如此。网站上的网页应用不计量：在付费套餐中，可在合理使用范围内无限使用。

Free 套餐

Free 套餐包含网页应用和 MCP 服务器（每月 150 点），不含 API。Free 账户可在其控制台中创建用于 MCP 服务器（AI 智能体）的密钥，额度为每月 150 点、每分钟 10 次请求；REST API 仅限付费套餐：使用 Free 密钥时，除 GET /v1/account 外，所有端点都会返回 403 plan_not_eligible，并附 details.feature、details.requiredPlan 和 details.upgradeUrl，且不计任何用量。在付费套餐中创建的密钥在 Free 套餐下会暂停，账户恢复付费套餐后立即重新生效。在 Free 套餐中，搜索只返回前几条结果，Free 不包含其数据的工具或端点会返回付费套餐的提示信息。套餐对比列出了 Free 包含的内容。示例品牌在网站上完整开放。

错误

错误使用标准 HTTP 状态码和 JSON 正文：

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

code 保持稳定，可放心用于分支判断；message 面向人阅读；details 在有额外数据时携带这些数据（400 中被拒绝的字段；402 中的每月点数、其重置日期、upgradeUrl 和 topUpUrl）。

媒体 URL

应答中的图片和视频由我们的 CDN 提供，地址为 https://api.sellwinners.com/v1/media/file/…。这些 URL 无需 API 密钥，也不消耗点数，因此您可以直接嵌入 <img> 和 <video> 标签。已不再可用的文件会在一天内以 null 发送，缺失的文件会返回对应媒体类型的空 404。托管在 Shopify CDN 上的商品图片和应用图标也由我们的 CDN 提供。如需显示小图，请添加 ?w=96（缩略图）或 ?w=480（卡片）：JPEG、PNG、WebP 或 GIF 图片将以 WebP 格式发送，宽度不超过该值，绝不放大；动图、更小的图片或视频则原样发送。如需扁平、可直接展示的素材列表，请使用 /v1/media。

如需以原尺寸显示图片但减小文件体积，请添加 ?w=full：JPEG、PNG、WebP 或 GIF 图片将以 WebP 格式按原有宽度和高度发送，画质看起来相同，前提是这样至少能节省十分之一的文件大小；否则，以及动图或视频，将原样发送原文件。不带 w 时发送原文件。

发现

把名称、域名或主页 ID 转换为其他端点所需的 ID。

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"

店铺

查找 Shopify 店铺，获取商品、流量、销量、社交媒体和广告。

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"

市场

整个市场的每日汇总及其 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"

Meta 广告

Facebook 和 Instagram 广告素材，附媒体文件、覆盖人数和排名。

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 广告

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

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"

媒体

可直接渲染的素材：托管在我们 CDN 上的图片和视频 URL。

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"

广告主

广告主（Facebook 主页）及其动态。

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"

邮件

品牌的营销邮件和新闻简报。

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"

商品

店铺商品及其价格、销量、评价、广告和欧盟覆盖人数。

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"

筛选项

搜索筛选条件可用的值和 ID。

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"

看板

把广告、店铺、商品、邮件和广告主保存到看板并分享。

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"

收藏

按文件夹收藏广告、店铺和邮件。

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

已保存视图

您在网站各列表页上保存的搜索，按页面归类。

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"

品牌追踪

关注品牌，查看其广告、素材和落地页的报告。

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