Back to Details

apify-ads-intelligence

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Ads Intelligence Cluster

广告情报集群

Answer natural language questions about ads, ad libraries, and competitor advertising activity by routing to the right Apify Actor and delivering a synthesized answer.
CLI rules: Always pass 
--user-agent apify-awesome-skills/apify-ads-intelligence
, 
--json
(or the relevant 
--format
flag on 
datasets get-items
), and 
2>/dev/null
. The 
--user-agent
flag is critical for telemetry — never omit it.
通过将请求路由到正确的 Apify Actor 并提供综合答案，使用自然语言回答有关广告、广告库和竞争对手广告活动的问题。
CLI 规则： 始终传入 
--user-agent apify-awesome-skills/apify-ads-intelligence
、
--json
（或 
datasets get-items
上相应的 
--format
标志）以及 
2>/dev/null
。
--user-agent
标志对于遥测至关重要——切勿省略。

Note on platform coverage

平台覆盖范围说明

  • Meta, Google, TikTok, LinkedIn: real public ad libraries with rich data (creatives, targeting, dates, reach where disclosed).
  • X (Twitter): no public ad library exists. Coverage is a best-effort workaround that scrapes a brand's tweets and flags items with non-empty 
    card
    field or 
    source
    containing "Ads" as likely promoted. Always include the caveat in synthesis output.
  • Meta、Google、TikTok、LinkedIn：真实可用的公开广告库，包含丰富数据（创意、定向、日期，以及已披露时的触达量）。
  • X (Twitter)：不存在公开广告库。覆盖采用尽力而为的替代方案：抓取品牌的推文，并将 
    card
    字段非空或 
    source
    字段包含 
    Ads
    的项目标记为可能的推广内容。综合输出中始终必须包含此免责声明。

Note on overlap with 
apify-ecommerce

与 
apify-ecommerce
的重叠说明

That skill has an 
ads-intelligence
intent that routes to 
apify/facebook-ads-scraper
for shallow Meta-ad lookups. This skill is the deep dive across all five platforms. If you only need Meta ads as a side detail of an ecommerce question, stay in 
apify-ecommerce
. If ads are the main task, use this skill.
该 skill 有一个 
ads-intelligence
intent，会将请求路由到 
apify/facebook-ads-scraper
以进行浅层 Meta 广告查询。本 skill 则深入覆盖全部五个平台。如果只需将 Meta 广告作为电商问题的附带信息，请使用 
apify-ecommerce
。如果广告是主要任务，请使用本 skill。

Prerequisites

前置条件

(No need to check it upfront)
  • Apify CLI v1.5.0+ (
    npm install -g apify-cli
    )
  • jq
    (recommended for response parsing and filtering; 
    brew install jq
    on macOS, 
    apt install jq
    on Linux)
  • Authentication via one of:
Verify auth: 
apify info --user-agent apify-awesome-skills/apify-ads-intelligence
— should show username and userId.
（无需提前检查）
  • Apify CLI v1.5.0+（
    npm install -g apify-cli
    ）
  • jq
    （推荐用于解析和筛选响应；在 macOS 上使用 
    brew install jq
    ，在 Linux 上使用 
    apt install jq
    ）
  • 通过以下任一方式进行身份验证：
验证身份：
apify info --user-agent apify-awesome-skills/apify-ads-intelligence
——应显示 username 和 userId。

Workflow

工作流

Copy this checklist and track progress:
Task Progress:
- [ ] Step 1: Detect intent and select Actor(s)
- [ ] Step 2: Fetch Actor schema
- [ ] Step 3: Ask user preferences (output format, result count, country)
- [ ] Step 4: Run the Actor (or Actors in parallel for cross-platform-audit) and fetch results
- [ ] Step 5: Synthesize a direct answer (not a data dump)
复制此检查清单并跟踪进度：
Task Progress:
- [ ] Step 1: Detect intent and select Actor(s)
- [ ] Step 2: Fetch Actor schema
- [ ] Step 3: Ask user preferences (output format, result count, country)
- [ ] Step 4: Run the Actor (or Actors in parallel for cross-platform-audit) and fetch results
- [ ] Step 5: Synthesize a direct answer (not a data dump)

Step 1: Detect Intent and Select Actor

第 1 步：检测意图并选择 Actor

Classify the user's message into an intent, then pick the right Actor.
Intent signals:
Signals in user messageIntent
"what ads is X running", "competitor [brand] ads", "[brand] FB/Google/TikTok/LinkedIn/X/Twitter ads", "show ads from [page]", "promoted tweets from [brand]"
competitor-ads
"ads about [topic]", "find [keyword] ads", "ads for [vertical]", "fitness/fintech/saas ads"
keyword-ads
"trending ads", "winning ads", "top ads", "best performing", "long-running ads", "creative inspiration"
top-creatives
"where do these ads go", "landing pages from ads", "click destinations", "ad funnels"
landing-page-audit
"compare X's ads across platforms", "all ads from [brand]", "cross-platform ad audit"
cross-platform-audit
If multiple intents detected, ask: "Do you want [intent A] or [intent B]?"
Actor routing — always try Primary first, switch to Fallback only if it fails or returns 0 results:
IntentPlatformPrimary ActorFallback Actor
competitor-ads
Meta (FB/IG)
apify/facebook-ads-scraper
brilliant_gum/facebook-ads-library-scraper
competitor-ads
Google
dz_omar/google-ads-scraper
solidcode/ads-transparency-scraper
competitor-ads
TikTok
brilliant_gum/tiktok-ads-library-scraper
(
source: library
)
silva95gustavo/tiktok-ads-scraper
competitor-ads
LinkedIn
silva95gustavo/linkedin-ad-library-scraper
dz_omar/linkedin-ads-scraper
competitor-ads
X (workaround)
apidojo/twitter-scraper-lite
(
twitterHandles: [<brand>]
) + heuristic filter
apidojo/tweet-scraper
keyword-ads
Meta
brilliant_gum/facebook-ads-library-scraper
apify/facebook-ads-scraper
keyword-ads
Google
apify/google-search-scraper
(
focusOnPaidAds: true
)		—
keyword-ads
TikTok
brilliant_gum/tiktok-ads-library-scraper
—
keyword-ads
LinkedIn
silva95gustavo/linkedin-ad-library-scraper
—
keyword-ads
X (workaround)
apidojo/twitter-scraper-lite
(
searchTerms: [<keyword>]
) + heuristic filter
apidojo/tweet-scraper
top-creatives
Meta
brilliant_gum/facebook-ads-library-scraper
(rank by 
daysRunning
)		—
top-creatives
TikTok
burbn/tiktok-top-ads-spy
(sort by CTR / impressions / likes)
brilliant_gum/tiktok-ads-library-scraper
(
source: creative_center
)
top-creatives
Googlen/a — fall back to 
competitor-ads
route, filter to active ads		—
top-creatives
LinkedInn/a — fall back to 
competitor-ads
route, rank by 
impressionsPerCountry
reach		—
top-creatives
Xn/a in v1 — no reliable promoted-content signal across timelines—
landing-page-audit
Meta
brilliant_gum/facebook-ads-library-scraper
(
resolveSnapshotUrls: true
)		—
landing-page-audit
Google
apify/google-search-scraper
(
focusOnPaidAds: true
, 
directUrl
)
dz_omar/google-ads-scraper
(
destinationUrl
)
landing-page-audit
Xn/a in v1 — heuristics not reliable enough for landing-page extraction—
cross-platform-audit
All fiveRun Meta + Google + TikTok + LinkedIn primaries in parallel; X workaround runs separately with caveat. Merge by advertiser.—
X (Twitter) heuristic filter — after scraping, flag a tweet as likely promoted if any of the following hold:
  • card
    field is non-empty (website cards / CTAs are commonly attached to promoted tweets)
  • source
    field contains "Ads" (e.g. "Twitter Ads")
Surface results with the explicit caveat: "X has no public ad library; results below are tweets from the brand's own timeline that match promoted-content heuristics. They will miss promoted-only ads that appear in other users' feeds."
将用户消息归类为一种 intent，然后选择正确的 Actor。
意图信号：
用户消息中的信号意图
X 正在投放哪些广告
、
[品牌] 的竞品广告
、
[品牌] 的 FB/Google/TikTok/LinkedIn/X/Twitter 广告
、
显示 [页面] 的广告
、
[品牌] 的推广推文
competitor-ads
关于 [主题] 的广告
、
查找 [关键词] 广告
、
[垂直行业] 的广告
、
健身/金融科技/SaaS 广告
keyword-ads
热门广告
、
胜出广告
、
最佳广告
、
表现最佳
、
长期投放广告
、
创意灵感
top-creatives
这些广告指向哪里
、
广告落地页
、
点击目标
、
广告漏斗
landing-page-audit
比较 X 在各平台的广告
、
[品牌] 的所有广告
、
跨平台广告审计
cross-platform-audit
如果检测到多个 intent，询问：“您想要 [intent A] 还是 [intent B]？”
Actor 路由——始终先尝试主要 Actor，仅在其失败或返回 0 条结果时切换到备用 Actor：
意图平台主要 Actor备用 Actor
competitor-ads
Meta (FB/IG)
apify/facebook-ads-scraper
brilliant_gum/facebook-ads-library-scraper
competitor-ads
Google
dz_omar/google-ads-scraper
solidcode/ads-transparency-scraper
competitor-ads
TikTok
brilliant_gum/tiktok-ads-library-scraper
（
source: library
）
silva95gustavo/tiktok-ads-scraper
competitor-ads
LinkedIn
silva95gustavo/linkedin-ad-library-scraper
dz_omar/linkedin-ads-scraper
competitor-ads
X（替代方案）
apidojo/twitter-scraper-lite
（
twitterHandles: [<brand>]
）+ 启发式筛选
apidojo/tweet-scraper
keyword-ads
Meta
brilliant_gum/facebook-ads-library-scraper
apify/facebook-ads-scraper
keyword-ads
Google
apify/google-search-scraper
（
focusOnPaidAds: true
）		—
keyword-ads
TikTok
brilliant_gum/tiktok-ads-library-scraper
—
keyword-ads
LinkedIn
silva95gustavo/linkedin-ad-library-scraper
—
keyword-ads
X（替代方案）
apidojo/twitter-scraper-lite
（
searchTerms: [<keyword>]
）+ 启发式筛选
apidojo/tweet-scraper
top-creatives
Meta
brilliant_gum/facebook-ads-library-scraper
（按 
daysRunning
排名）		—
top-creatives
TikTok
burbn/tiktok-top-ads-spy
（按 CTR、展示量或点赞数排序）
brilliant_gum/tiktok-ads-library-scraper
（
source: creative_center
）
top-creatives
Google不适用——回退到 
competitor-ads
路由，并筛选活跃广告		—
top-creatives
LinkedIn不适用——回退到 
competitor-ads
路由，并按 
impressionsPerCountry
触达量排名		—
top-creatives
Xv1 中不适用——无法跨时间线可靠识别推广内容—
landing-page-audit
Meta
brilliant_gum/facebook-ads-library-scraper
（
resolveSnapshotUrls: true
）		—
landing-page-audit
Google
apify/google-search-scraper
（
focusOnPaidAds: true
、
directUrl
）
dz_omar/google-ads-scraper
（
destinationUrl
）
landing-page-audit
Xv1 中不适用——启发式规则不足以可靠提取落地页—
cross-platform-audit
全部五个平台并行运行 Meta、Google、TikTok、LinkedIn 的主要 Actor；X 替代方案单独运行并附带免责声明。按广告主合并结果。—
X (Twitter) 启发式筛选——抓取后，如果满足以下任一条件，则将推文标记为可能为推广内容：
  • card
    字段非空（推广推文通常会附加网站卡片或 CTA）
  • source
    字段包含 
    Ads
    （例如 
    Twitter Ads
    ）
展示结果时必须明确说明：“X 没有公开广告库；以下结果是该品牌自身时间线中符合推广内容启发式规则的推文。它们会遗漏仅在其他用户信息流中出现的推广广告。”

Step 2: Fetch Actor Schema

第 2 步：获取 Actor Schema

Fetch the Actor summary, input schema, and README:
bash
undefined
获取 Actor 摘要、输入 schema 和 README：
bash
undefined

Summary (title, description, pricing, stats)

Summary (title, description, pricing, stats)

apify actors info "ACTOR_ID" --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null
apify actors info "ACTOR_ID" --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null

Input schema (required and optional parameters; schema lives in

Input schema (required and optional parameters; schema lives in

.taggedBuilds.latest.build.inputSchema as an escaped JSON string)

.taggedBuilds.latest.build.inputSchema as an escaped JSON string)

apify actors info "ACTOR_ID" --user-agent apify-awesome-skills/apify-ads-intelligence --input --json 2>/dev/null
apify actors info "ACTOR_ID" --user-agent apify-awesome-skills/apify-ads-intelligence --input --json 2>/dev/null

README (capabilities, examples, gotchas)

README (capabilities, examples, gotchas)

apify actors info "ACTOR_ID" --user-agent apify-awesome-skills/apify-ads-intelligence --readme 2>/dev/null

Replace `ACTOR_ID` with the selected Actor (e.g., `apify/facebook-ads-scraper`).
apify actors info "ACTOR_ID" --user-agent apify-awesome-skills/apify-ads-intelligence --readme 2>/dev/null

将 `ACTOR_ID` 替换为选定的 Actor（例如 `apify/facebook-ads-scraper`）。

Step 3: Ask User Preferences

第 3 步：询问用户偏好

Before running, ask:
  1. Output format:
    • Quick answer (default) — synthesized answer in chat, no file saved
    • CSV — full export saved to disk
    • JSON — full export saved to disk
  2. Result count — defaults by intent:
    IntentDefault count
    competitor-ads
    		30
    keyword-ads
    		30
    top-creatives
    		20
    landing-page-audit
    		50
    cross-platform-audit
    		15 per platform
  3. Country — default 
    US
    . For TikTok library specifically, default 
    DE
    (EU-only) and warn the user; for global TikTok use 
    source: creative_center
    . X routes are global by handle/keyword, no country parameter.
Cost safety: Always set a sensible result limit in the Actor input (e.g., 
maxResults
, 
resultsLimit
, or the equivalent field per Actor schema). Warn the user before runs of 500+ ads — 
apify/facebook-ads-scraper
charges per ad and X primaries charge per tweet.
运行前，询问：
  1. 输出格式：
    • 快速回答（默认）——在聊天中提供综合答案，不保存文件
    • CSV——将完整导出保存到磁盘
    • JSON——将完整导出保存到磁盘
  2. 结果数量——根据 intent 使用以下默认值：
    意图默认数量
    competitor-ads
    		30
    keyword-ads
    		30
    top-creatives
    		20
    landing-page-audit
    		50
    cross-platform-audit
    		每个平台 15
  3. 国家/地区——默认值为 
    US
    。对于 TikTok Ads Library，默认使用 
    DE
    （仅限欧盟），并警告用户；如果需要全球 TikTok 数据，则使用 
    source: creative_center
    。X 路由通过 handle 或关键词覆盖全球范围，不提供国家参数。
成本控制：始终在 Actor 输入中设置合理的结果数量上限（例如 
maxResults
、
resultsLimit
，或各 Actor schema 中的等效字段）。在运行 500 条以上广告前警告用户——
apify/facebook-ads-scraper
按广告条数收费，X 的主要 Actor 按推文条数收费。

Step 4: Run the Actor and Fetch Results

第 4 步：运行 Actor 并获取结果

Two steps: run the Actor (blocks until done), then fetch dataset items in the requested format.
Run the Actor — returns run metadata as JSON; extract 
defaultDatasetId
for the next step:
bash
apify actors call "ACTOR_ID" -i 'JSON_INPUT' \
  --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null
From the output use 
.id
(run ID), 
.status
(should be 
SUCCEEDED
), and 
.defaultDatasetId
.
Fetch results — pick the variant based on the user's preference:
bash
undefined
分为两个步骤：先运行 Actor（阻塞至完成），再按用户要求的格式获取数据集条目。
运行 Actor——返回以 JSON 格式表示的运行元数据；从中提取 
defaultDatasetId
，供下一步使用：
bash
apify actors call "ACTOR_ID" -i 'JSON_INPUT' \
  --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null
从输出中获取 
.id
（运行 ID）、
.status
（应为 
SUCCEEDED
）和 
.defaultDatasetId
。
获取结果——根据用户偏好选择对应形式：
bash
undefined

Quick answer: total count + fields + top 5 in chat (no file)

Quick answer: total count + fields + top 5 in chat (no file)

apify datasets info DATASET_ID --json
--user-agent apify-awesome-skills/apify-ads-intelligence 2>/dev/null
| jq '{itemCount, fields, consoleUrl}' apify datasets get-items DATASET_ID --limit 5
--user-agent apify-awesome-skills/apify-ads-intelligence --format json 2>/dev/null
apify datasets info DATASET_ID --json
--user-agent apify-awesome-skills/apify-ads-intelligence 2>/dev/null
| jq '{itemCount, fields, consoleUrl}' apify datasets get-items DATASET_ID --limit 5
--user-agent apify-awesome-skills/apify-ads-intelligence --format json 2>/dev/null

CSV file

CSV file

apify datasets get-items DATASET_ID
--user-agent apify-awesome-skills/apify-ads-intelligence --format csv 2>/dev/null > YYYY-MM-DD_filename.csv
apify datasets get-items DATASET_ID
--user-agent apify-awesome-skills/apify-ads-intelligence --format csv 2>/dev/null > YYYY-MM-DD_filename.csv

JSON file

JSON file

apify datasets get-items DATASET_ID
--user-agent apify-awesome-skills/apify-ads-intelligence --format json 2>/dev/null > YYYY-MM-DD_filename.json

Other `--format` options: `jsonl`, `xlsx`, `xml`, `rss`, `html`. Use `--offset N` to paginate large datasets.

**Tip:** for anything more than a quick peek, save the dataset to a local file first (with `> file.json` / `> file.csv`) and run further analysis from disk. `apify datasets get-items` always streams over the network, so piping it straight into `jq` re-downloads the whole thing every iteration.

**Cross-platform audit (parallel runs):** For `cross-platform-audit`, kick off Meta + Google + TikTok + LinkedIn primaries in parallel by backgrounding each `apify actors call ...` invocation with `&` and calling `wait` before fetching results. Example:

```bash
apify actors call "apify/facebook-ads-scraper" -i '<META_INPUT>' \
  --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null > meta_run.json &
apify actors call "dz_omar/google-ads-scraper" -i '<GOOGLE_INPUT>' \
  --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null > google_run.json &
apify actors call "brilliant_gum/tiktok-ads-library-scraper" -i '<TIKTOK_INPUT>' \
  --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null > tiktok_run.json &
apify actors call "silva95gustavo/linkedin-ad-library-scraper" -i '<LINKEDIN_INPUT>' \
  --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null > linkedin_run.json &
wait
apify datasets get-items DATASET_ID
--user-agent apify-awesome-skills/apify-ads-intelligence --format json 2>/dev/null > YYYY-MM-DD_filename.json

其他 `--format` 选项包括：`jsonl`、`xlsx`、`xml`、`rss`、`html`。使用 `--offset N` 对大型数据集进行分页。

**提示：** 对于快速查看以外的任何分析，先将数据集保存到本地文件（使用 `> file.json` / `> file.csv`），然后从磁盘继续分析。`apify datasets get-items` 始终通过网络流式传输数据，因此直接将其输出管道到 `jq` 会在每次迭代时重新下载完整数据集。

**跨平台审计（并行运行）：** 对于 `cross-platform-audit`，通过将每次 `apify actors call ...` 调用放入后台并使用 `&`，并行启动 Meta、Google、TikTok、LinkedIn 的主要 Actor，然后调用 `wait`，再获取结果。示例：

```bash
apify actors call "apify/facebook-ads-scraper" -i '<META_INPUT>' \
  --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null > meta_run.json &
apify actors call "dz_omar/google-ads-scraper" -i '<GOOGLE_INPUT>' \
  --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null > google_run.json &
apify actors call "brilliant_gum/tiktok-ads-library-scraper" -i '<TIKTOK_INPUT>' \
  --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null > tiktok_run.json &
apify actors call "silva95gustavo/linkedin-ad-library-scraper" -i '<LINKEDIN_INPUT>' \
  --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null > linkedin_run.json &
wait

Then extract each .defaultDatasetId and fetch items per platform; X workaround runs separately with caveat.

Then extract each .defaultDatasetId and fetch items per platform; X workaround runs separately with caveat.


**Combining with `jq` for quick extraction:**

Treat `jq` as a complement to `apify datasets get-items`, not a replacement: server-side `--limit` / `--offset` / `--format` keeps cost and bandwidth down. Use `jq` on a sample item or on a file you already saved.

```bash

**结合 `jq` 进行快速提取：** 将 `jq` 视为 `apify datasets get-items` 的补充工具，而不是替代品：使用服务端的 `--limit` / `--offset` / `--format` 可以减少成本和带宽消耗。对单个样本项或已保存到本地的文件使用 `jq`。

```bash

Discover real field names from one sample item (Actor outputs vary —

Discover real field names from one sample item (Actor outputs vary —

use this before composing further jq queries)

use this before composing further jq queries)

apify datasets get-items DATASET_ID --limit 1 --format json
--user-agent apify-awesome-skills/apify-ads-intelligence 2>/dev/null
| jq '.[0]'
apify datasets get-items DATASET_ID --limit 1 --format json
--user-agent apify-awesome-skills/apify-ads-intelligence 2>/dev/null
| jq '.[0]'

X heuristic filter on a saved tweets file: keep items with non-empty card

X heuristic filter on a saved tweets file: keep items with non-empty card

or source containing "Ads"

or source containing "Ads"

jq '[.[] | select((.card != null and .card != "") or (.source != null and (.source | contains("Ads"))))]'
YYYY-MM-DD_x_tweets.json
undefined
jq '[.[] | select((.card != null and .card != "") or (.source != null and (.source | contains("Ads"))))]'
YYYY-MM-DD_x_tweets.json
undefined

Step 5: Analyze Results and Deliver Answer

第 5 步：分析结果并提供答案

Synthesize, don't dump. Patterns by intent:
IntentWhat the synthesis surfaces
competitor-ads
Total ads found, active vs inactive split, top creative formats, top 5 ad copy snippets, list of unique landing-page domains. For X specifically: total tweets scraped, count flagged as likely-promoted, top 5 flagged tweets with the heuristic-detection caveat.
keyword-ads
Top 5 advertisers running ads on this keyword, total ads, country split
top-creatives
Top 5 by 
daysRunning
(Meta) or CTR (TikTok), with creative summary, link to Ad Library entry
landing-page-audit
List of unique landing URLs, grouped by domain, with ad counts pointing at each
cross-platform-audit
Per-platform ad count and tone summary, then a "where they're spending most" inference
Suggested follow-ups — keyed off the intent that just ran:
If user just ran…Suggest next
competitor-ads
(Meta)		Stack with 
apify-competitor-intelligence
to add their FB Page posts, IG profile, and Google Maps reviews
landing-page-audit
(any)		Stack with 
apify-ecommerce
(
tech-stack
intent) to detect the platform behind the landing pages, or with 
apify-lead-generation
to enrich destination domains with contact info
top-creatives
(TikTok / Meta)		Stack with 
apify-influencer-discovery
if any creatives are influencer collabs
keyword-ads
(Google / Meta)		Stack with 
apify-trend-analysis
to see whether the keyword is rising or falling on Google Trends / Instagram / TikTok
cross-platform-audit
Stack with 
apify-content-analytics
for the brand's organic content side; combined paid + organic picture
进行综合分析，不要直接倾倒数据。按 intent 归纳的模式：
意图综合答案应呈现的内容
competitor-ads
找到的广告总数、活跃与停用广告分布、主要创意格式、前 5 条广告文案片段，以及唯一落地页域名列表。对于 X：抓取到的推文总数、被标记为可能为推广内容的数量、前 5 条被标记的推文，以及启发式检测免责声明。
keyword-ads
使用该关键词投放广告的前 5 个广告主、广告总数以及国家/地区分布
top-creatives
Meta 上按 
daysRunning
、TikTok 上按 CTR 排名前 5 的广告，并附创意摘要和 Ad Library 条目链接
landing-page-audit
唯一落地页 URL 列表，按域名分组，并显示指向每个域名的广告数量
cross-platform-audit
各平台的广告数量和广告语气摘要，随后推断“主要在哪些平台投放”
建议的后续操作——根据刚运行的 intent 提供：
如果用户刚运行了……建议下一步
competitor-ads
（Meta）		与 
apify-competitor-intelligence
搭配使用，补充其 Facebook Page 帖子、IG 主页和 Google Maps 评价
landing-page-audit
（任意平台）		与 
apify-ecommerce
（
tech-stack
intent）搭配使用，检测落地页背后的技术平台；或与 
apify-lead-generation
搭配使用，为目标域名补充联系信息
top-creatives
（TikTok / Meta）		如果创意包含网红合作，可与 
apify-influencer-discovery
搭配使用
keyword-ads
（Google / Meta）		与 
apify-trend-analysis
搭配使用，查看该关键词在 Google Trends、Instagram 或 TikTok 上是上升还是下降
cross-platform-audit
与 
apify-content-analytics
搭配使用，分析品牌的自然流量内容；结合付费与自然内容形成完整视图

Quirks

特殊行为与注意事项

  • TikTok keyword search is loose. Searching "Nike" can return ads from unrelated advertisers (Interactive Brokers, Shopify in our test). Always post-filter by 
    advertiserName
    matching the user's intended brand; warn the user if zero matches after filter.
  • TikTok Ads Library is EU/EEA/UK only. The 
    library
    source needs an EU country code (DE / FR / IT / ES / NL / PL / SE etc.). For US/global coverage, switch to 
    creative_center
    source — different fields (CTR, impression ranges, no targeting data).
  • dz_omar/google-ads-scraper
    requires 
    resultsPerQuery >= 10
    .     Smaller values fail validation. Always set 10+ even for small intents.
  • apify/facebook-ads-scraper
    takes URLs, not keywords.     For 
    competitor-ads
    : build 
    https://www.facebook.com/<PageName>
    from the brand name. For 
    keyword-ads
    : build a Meta Ad Library URL with 
    q=<keyword>&country=<XX>
    .
  • apify/google-search-scraper
    paid-ads mode     has a built-in retry (up to 3) when no paid results are found — sometimes a query genuinely has no paid results. Treat empty 
    paidResults
    as a valid answer, not an error.
  • LinkedIn Ad Library URL construction: company URL 
    https://www.linkedin.com/company/<slug>/
    is allowed but slow and ignores filters. For 
    competitor-ads
    use 
    https://www.linkedin.com/ad-library/search?accountOwner=<slug>&countries=<XX>
    . For 
    keyword-ads
    use 
    ?keyword=<term>&countries=<XX>
    .
  • X has no public ad library. Coverage is heuristic only. The route uses 
    apidojo/twitter-scraper-lite
    to scrape a brand's own tweets (or keyword search results), then flags items with non-empty 
    card
    field or 
    source
    containing "Ads" as likely promoted. This will miss promoted-only tweets that never appear in the brand's own timeline.
  • X session sensitivity. If the primary X Actor returns only 
    noResults
    sentinels, switch to the fallback before declaring zero results.
  • Pricing. Most primaries are FREE in our pricing tier; 
    apify/facebook-ads-scraper
    charges per ad ($0.001 - $0.0058); X primaries charge per tweet (~$0.0004 / 1k). Default counts (30 / 20 / 50) keep cost negligible. Warn before runs of 500+ ads.
  • TikTok 关键词搜索不够精确。 搜索“Nike”可能返回来自无关广告主的广告（在我们的测试中包括 Interactive Brokers、Shopify）。始终根据 
    advertiserName
    与用户目标品牌的匹配情况进行后置筛选；如果筛选后为零匹配，则警告用户。
  • TikTok Ads Library 仅覆盖 EU/EEA/UK。 
    library
    来源需要欧盟国家代码（DE、FR、IT、ES、NL、PL、SE 等）。如需美国或全球范围的数据，请改用 
    creative_center
    来源——该来源的字段有所不同（包含 CTR、展示量区间，不包含定向数据）。
  • dz_omar/google-ads-scraper
    要求 
    resultsPerQuery >= 10
    。     更小的值会触发验证失败。即使意图范围较小，也始终设置为 10 或以上。
  • apify/facebook-ads-scraper
    接受 URL，而不是关键词。     对于 
    competitor-ads
    ：根据品牌名称构建 
    https://www.facebook.com/<PageName>
    。对于 
    keyword-ads
    ：构建带有 
    q=<keyword>&country=<XX>
    的 Meta Ad Library URL。
  • apify/google-search-scraper
    的付费广告模式    内置了最多 3 次的重试机制，以处理未找到付费结果的情况——有时查询确实没有付费结果。将空的 
    paidResults
    视为有效答案，而不是错误。
  • LinkedIn Ad Library URL 构建： 公司 URL 
    https://www.linkedin.com/company/<slug>/
    可以使用，但速度慢且会忽略筛选条件。对于 
    competitor-ads
    ，使用 
    https://www.linkedin.com/ad-library/search?accountOwner=<slug>&countries=<XX>
    。对于 
    keyword-ads
    ，使用 
    ?keyword=<term>&countries=<XX>
    。
  • X 没有公开广告库。 覆盖仅依靠启发式规则完成。该路由使用 
    apidojo/twitter-scraper-lite
    抓取品牌自己的推文（或关键词搜索结果），然后将 
    card
    字段非空或 
    source
    字段包含 
    Ads
    的项目标记为可能为推广内容。这会遗漏从未出现在品牌自身时间线中的纯推广推文。
  • X 对会话状态敏感。 如果主要的 X Actor 仅返回 
    noResults
    哨兵值，在声明零结果前切换到备用 X Actor。
  • 定价。 在我们的定价层级中，大多数主要 Actor 均为免费；
    apify/facebook-ads-scraper
    按广告条数收费（$0.001–$0.0058/条）；X 的主要 Actor 按推文条数收费（约 $0.0004/1k）。默认数量（30 / 20 / 50）可保持成本极低。运行 500 条以上广告前应发出警告。

Error Handling

错误处理

  • Auth error → run 
    apify login
    , or set 
    APIFY_TOKEN
    env var
  • Actor not found
    → check Actor ID against the routing table
  • Run status 
    FAILED
    → open the console URL (
    .consoleUrl
    from run metadata) for logs
  • Timeout / very long run → pass 
    --timeout <seconds>
    to 
    apify actors call
    , or reduce result count
  • 0 results → switch to the Fallback Actor; if still 0, try a different country code
  • TikTok library: no EU country supplied → default to 
    DE
    and warn the user
  • dz_omar/google-ads-scraper
    : validation error on 
    resultsPerQuery
    → bump to 10+
  • X scraper: only 
    noResults
    sentinels → switch to the fallback X Actor
  • proxy is required
    error → add 
    "proxy": {"useApifyProxy": true}
    to the input
  • 身份验证错误 → 运行 
    apify login
    ，或设置 
    APIFY_TOKEN
    环境变量
  • Actor not found
    → 根据路由表检查 Actor ID
  • 运行状态为 
    FAILED
    → 打开运行元数据中的控制台 URL（
    .consoleUrl
    ）查看日志
  • 超时或运行时间过长 → 向 
    apify actors call
    传入 
    --timeout <seconds>
    ，或减少结果数量
  • 0 条结果 → 切换到备用 Actor；如果仍然为 0，则尝试其他国家代码
  • TikTok library：未提供欧盟国家代码 → 默认使用 
    DE
    并警告用户
  • dz_omar/google-ads-scraper
    ：
    resultsPerQuery
    出现验证错误 → 增加到 10 或以上
  • X scraper：仅返回 
    noResults
    哨兵值 → 切换到备用 X Actor
  • proxy is required
    错误 → 在输入中添加 
    "proxy": {"useApifyProxy": true}