ClawHub

Ads Data Get

Data & APIs

广告平台数据查询工具。获取 Facebook、TikTok 等广告账号的余额、消耗数据，支持多层级分析（Account/Campaign/AdSet/Ad）和国家维度 breakdown。适用场景：(1) 查询广告账号余额或可用额度，(2) 查询昨日消耗，(3) 获取广告账号汇总报告，(4) 多维度数据分析，(5) ROAS/CTR/CPM/CVR 指标计算。

Install

openclaw skills install ads-data-get

Ads Data Get

广告平台数据查询工具，支持 Facebook、TikTok 平台。

支持平台

平台功能环境变量
Facebook余额、消耗、多层级分析、国家维度facebook_access_token
TikTok余额、消耗、多层级分析、国家维度tiktok_access_token, tiktok_app_id

TikTok 广告数据分析

1. 快速汇总报告

# 获取所有账号余额/消耗汇总
python scripts/tiktok_ads.py

# JSON 格式输出
python scripts/tiktok_ads.py --json

2. 单账号全方位分析

# 分析指定账号（最近 7 天）
python scripts/tiktok_ads.py --analyze --account <advertiser_id>

# 指定时间范围
python scripts/tiktok_ads.py --analyze --account <advertiser_id> --since 2026-03-01 --until 2026-03-13

# 分析最近 30 天
python scripts/tiktok_ads.py --analyze --account <advertiser_id> --days 30

3. 单层级数据查询

# Campaign 级别数据
python scripts/tiktok_ads.py --account <advertiser_id> --level campaign --json

# AdGroup 级别数据
python scripts/tiktok_ads.py --account <advertiser_id> --level adgroup --json

# Ad 级别数据
python scripts/tiktok_ads.py --account <advertiser_id> --level ad --json

# 按国家分组
python scripts/tiktok_ads.py --account <advertiser_id> --level account --breakdown country --json

Facebook 广告数据分析

1. 快速汇总报告

# 获取所有账号余额/消耗汇总
python scripts/facebook_ads.py

# JSON 格式输出
python scripts/facebook_ads.py --json

2. 单账号全方位分析

# 分析指定账号（最近 7 天）
python scripts/facebook_ads.py --analyze --account act_586806297825353

# 指定时间范围
python scripts/facebook_ads.py --analyze --account act_586806297825353 --since 2026-03-01 --until 2026-03-13

# 分析最近 30 天
python scripts/facebook_ads.py --analyze --account act_586806297825353 --days 30

3. 单层级数据查询

# Campaign 级别数据
python scripts/facebook_ads.py --account act_586806297825353 --level campaign --json

# AdSet 级别数据
python scripts/facebook_ads.py --account act_586806297825353 --level adset --json

# Ad 级别数据
python scripts/facebook_ads.py --account act_586806297825353 --level ad --json

# 按国家分组
python scripts/facebook_ads.py --account act_586806297825353 --level account --breakdown country --json

命令行参数

参数说明示例
--analyze执行全方位分析--analyze
--account, -a指定账号 ID--account act_123456
--level, -l数据层级: account/campaign/adset/ad--level campaign
--breakdown, -b分组维度 (可多次使用)--breakdown country
--since开始日期--since 2026-03-01
--until结束日期--until 2026-03-13
--days最近 N 天--days 30
--top显示 Top N 结果--top 20
--json, -jJSON 格式输出--json

Python 调用示例

TikTok

from scripts.tiktok_ads import (
    get_summary,
    analyze_account,
    get_insights
)

# 获取所有账号汇总
summary = get_summary()
print(f"总可用额度: ${summary['total_available']:,.2f}")
print(f"昨日总消耗: ${summary['total_yesterday_spend']:,.2f}")

# 全方位账号分析
analysis = analyze_account(
    "<advertiser_id>",
    date_range={"start_date": "2026-03-01", "end_date": "2026-03-13"},
    include_country_breakdown=True
)

Facebook

from scripts.facebook_ads import (
    get_summary, 
    analyze_account,
    get_insights,
    get_account_benchmarks
)

# 获取所有账号汇总
summary = get_summary()
print(f"总可用额度: ${summary['total_available']:,.2f}")
print(f"昨日总消耗: ${summary['total_yesterday_spend']:,.2f}")

# 全方位账号分析
analysis = analyze_account(
    "act_586806297825353",
    date_range={"since": "2026-03-01", "until": "2026-03-13"},
    include_country_breakdown=True
)

环境变量配置

在 ~/.openclaw/openclaw.json 的 env 中配置：

{
  "env": {
    "facebook_access_token": "EAAC...",
    "tiktok_access_token": "...",
    "tiktok_app_id": "..."
  }
}

注意事项

  • Facebook Access Token 有过期时间，长期使用需要定期刷新
  • TikTok 需要 Access Token 和 App ID
  • 金额单位为美元 (USD)
  • API 有调用频率限制，建议合理控制请求频率
More in Data & APIs