Reddit Ads CLI 技能

你可使用 reddit-ads-cli —— 一款面向 Reddit Ads API（v3）的只读命令行工具。可用于查询广告账户、列出广告系列与广告、生成效果报告、检查创意素材（creatives）、管理自定义受众（custom audiences）、追踪转化像素（conversion pixels），以及探索定向选项（子版块、兴趣、地理位置等）。

快速上手

# 检查 CLI 是否可用
reddit-ads-cli --help

# 列出当前可访问的广告账户
reddit-ads-cli accounts

# 列出某账户下的广告系列
reddit-ads-cli campaigns t2_abc123

若尚未安装该 CLI，请执行以下命令安装：

npm install -g reddit-ads-cli

身份认证

该 CLI 需要 Reddit 的 OAuth 访问令牌（access token）。凭证将按如下顺序解析：

1. --credentials 参数（每次命令单独指定）
2. 环境变量：REDDIT_ADS_ACCESS_TOKEN
3. 自动识别的配置文件：~/.config/reddit-ads-cli/credentials.json

凭证文件格式如下：

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "username": "your_reddit_username"
}

其中仅 access_token 为必需字段。username 字段用于构建 User-Agent 字符串（格式为：cli:reddit-ads-cli:v (by /u/)）。Reddit 对未提供合法 User-Agent 的请求实施速率限制。

若通过环境变量方式配置凭证，则支持以下变量：

• REDDIT_ADS_ACCESS_TOKEN — 必需
• REDDIT_ADS_CLIENT_ID — 可选
• REDDIT_ADS_CLIENT_SECRET — 可选
• REDDIT_ADS_USERNAME — 可选，用于构造 User-Agent

在运行任意命令前，请先执行 reddit-ads-cli accounts 验证凭证是否已正确配置。若因凭证问题报错，请提示用户完成身份认证配置。

实体层级结构

广告账户（Ad Account，t2_XXXXX）
 +-- 广告系列（Campaign）
 |    +-- 广告组（Ad Group）
 |         +-- 广告（Ad）
 +-- 创意素材（Creative）
 +-- 自定义受众（Custom Audience）
 +-- 转化像素（Pixel）
      +-- 像素事件（Pixel Events）

广告账户 ID 以 t2_ 为前缀（例如：t2_abc123）。

输出格式

所有命令默认输出格式化后的 JSON。如需单行紧凑格式（便于管道操作），请使用 --format compact 参数。

命令参考

账户发现

# 列出当前认证用户可访问的所有广告账户
reddit-ads-cli accounts

# 获取指定广告账户的详细信息
reddit-ads-cli account t2_abc123

广告系列层级结构

# 列出广告系列（可选：按状态过滤）
reddit-ads-cli campaigns t2_abc123
reddit-ads-cli campaigns t2_abc123 --status ACTIVE

# 列出广告组（可选：按广告系列或状态过滤）
reddit-ads-cli adgroups t2_abc123
reddit-ads-cli adgroups t2_abc123 --campaign-id campaign_abc
reddit-ads-cli adgroups t2_abc123 --status PAUSED

# 列出广告（可选：按广告组、广告系列或状态过滤）
reddit-ads-cli ads t2_abc123
reddit-ads-cli ads t2_abc123 --ad-group-id adgroup_abc
reddit-ads-cli ads t2_abc123 --campaign-id campaign_abc
reddit-ads-cli ads t2_abc123 --status ACTIVE

campaigns 参数说明

• --status — 按状态过滤（如 ACTIVE、PAUSED 等）

adgroups 参数说明

• --campaign-id — 按广告系列 ID 过滤
• --status — 按状态过滤（如 ACTIVE、PAUSED 等）

ads 参数说明

• --ad-group-id — 按广告组 ID 过滤
• --campaign-id — 按广告系列 ID 过滤
• --status — 按状态过滤（如 ACTIVE、PAUSED 等）

效果报告

report 命令通过 POST 请求生成效果报告。--start-date 与 --end-date 均为必需参数。

# 广告系列级报告（默认层级）
reddit-ads-cli report t2_abc123 
  --start-date 2026-03-01 
  --end-date 2026-03-15 
  --metrics impressions,clicks,spend,ecpm,ctr

# 广告组级报告（含时区设置）
reddit-ads-cli report t2_abc123 
  --start-date 2026-03-01 
  --end-date 2026-03-15 
  --level AD_GROUP 
  --metrics impressions,clicks,spend 
  --campaign-id campaign_abc 
  --timezone America/New_York

# 账户级报告
reddit-ads-cli report t2_abc123 
  --start-date 2026-03-01 
  --end-date 2026-03-15 
  --level ACCOUNT

# 广告级报告（限定于特定广告组）
reddit-ads-cli report t2_abc123 
  --start-date 2026-03-01 
  --end-date 2026-03-15 
  --level AD 
  --ad-group-id adgroup_abc

report 参数说明

• --start-date — 开始日期，格式为 YYYY-MM-DD（必需）
• --end-date — 结束日期，格式为 YYYY-MM-DD（必需）
• --level — 报告层级：ACCOUNT、CAMPAIGN、AD_GROUP、AD（默认为 CAMPAIGN）
• --metrics — 逗号分隔的指标列表（默认为 impressions,clicks,spend）。示例中还包含 ecpm、ctr。CLI 将指标名称直接透传至 Reddit Ads API，不进行校验。完整可用指标请参阅 Reddit Ads API 文档。
• --campaign-id — 按广告系列 ID 过滤
• --ad-group-id — 按广告组 ID 过滤
• --timezone — 时区（例如：America/New_York）

创意素材（Creatives）

# 列出某账户下的广告创意（支持分页）
reddit-ads-cli creatives t2_abc123
reddit-ads-cli creatives t2_abc123 --limit 50 --offset 10

# 获取指定创意详情
reddit-ads-cli creative t2_abc123 creative_xyz

creatives 参数说明

• --limit — 每页返回结果数（默认：25）
• --offset — 起始索引（默认：0）

自定义受众（Custom Audiences）

# 列出自定义受众（支持分页）
reddit-ads-cli custom-audiences t2_abc123
reddit-ads-cli custom-audiences t2_abc123 --limit 50 --offset 10

custom-audiences 参数说明

• --limit — 每页返回结果数（默认：25）
• --offset — 起始索引（默认：0）

转化像素（Pixels）与转化追踪

# 列出某账户下的转化像素
reddit-ads-cli pixels t2_abc123

# 列出指定像素所追踪的事件
reddit-ads-cli pixel-events t2_abc123 pixel_xyz

定向选项

# 搜索可用于定向的子版块（--query 参数为必需）
reddit-ads-cli subreddits --query gaming
reddit-ads-cli subreddits --query technology --limit 50

# 列出兴趣定向分类
reddit-ads-cli interests

# 列出地理位置定向选项（可选：支持搜索）
reddit-ads-cli geos
reddit-ads-cli geos --query "United States"

subreddits 参数说明

• --query — 搜索关键词（必需）
• --limit — 每页返回结果数（默认：25）

geos 参数说明

• --query — 搜索关键词（可选）

分页机制汇总

支持 --limit 和 --offset 分页的命令有：creatives、custom-audiences、subreddits。

不支持分页的命令有：accounts、account、campaigns、adgroups、ads、pixels、pixel-events、interests、geos。

工作流指引

当用户请求快速概览时

1. 运行 reddit-ads-cli accounts 获取可访问的广告账户列表
2. 运行 reddit-ads-cli campaigns 列出对应账户下的广告系列
3. 使用 reddit-ads-cli report --start-date ... --end-date ... 获取效果快照

当用户请求深度分析时

1. 首先执行账户级报告（--level ACCOUNT）以掌握整体表现
2. 下钻至广告系列层级（--level CAMPAIGN）识别表现最优/最差的广告系列
3. 进一步下钻至广告组（--level AD_GROUP）或广告（--level AD）层级，定位低效广告系列的具体问题
4. 通过 --campaign-id 或 --ad-group-id 参数聚焦于特定实体
5. 交叉比对 creatives 命令结果，审查广告内容本身

当用户询问创意素材表现时

1. 使用 report 命令并指定 --level AD，获取广告粒度的效果指标
2. 使用 ads 命令获取广告详细信息
3. 使用 creatives 和 creative 命令检查实际创意内容

当用户询问定向选项时

1. 使用 subreddits --query 发现可定向的子版块
2. 使用 interests 查看可用的兴趣分类
3. 使用 geos 探索地理位置定向选项

当用户询问转化追踪时

1. 运行 pixels 列出当前启用的转化像素
2. 使用 pixel-events 加像素 ID 查看具体追踪的事件类型
3. 在 report 中加入转化相关指标（如 conversions、conversion_rate 等）评估转化效果

当用户询问受众管理时

1. 使用 custom-audiences 列出现有自定义受众
2. 通过 --limit 和 --offset 分页浏览全部结果

错误处理

• 身份认证错误 — 提示用户验证其 access token；确认 ~/.config/reddit-ads-cli/credentials.json 文件存在且包含有效的 access_token
• 未找到凭证 — CLI 会依次检查命令行参数、环境变量、默认配置文件三个位置；请确保至少一种方式已正确配置
• 报告为空 — 检查日期范围、实体状态，以及该时间段内账户是否投放过有效广告
• 速率限制错误 — Reddit 对缺失合法 User-Agent 的请求实施限流；请确保凭证中设置了 username
• 未知命令 — 运行 reddit-ads-cli --help 查看所有可用命令

API 文档参考

• reddit-ads-cli 文档
• Reddit Ads API v3 文档
• Reddit OAuth2 身份认证文档