reddit-ads

Reddit 広告キャンペーン

Reddit Ads API v3 を利用して Reddit 広告を管理するための戦略ガイドです。このツールキットは raw-HTTP クライアントのため、パラメーターの型はドキュメントどおりに送信する必要があります。文字列は文字列として、整数は整数として、金額はすべてマイクロ通貨で指定してください。

必要条件

• Hyper MCP がインストールされ、接続されていること。 https://app.hyperfx.ai/mcp
• https://app.hyperfx.ai/apps で Reddit Ads のインテグレーションが接続されていること（広告アカウントにアクセスできる Reddit Ads ビジネスアカウントが必要です）。

search で reddit_ads_get_me／reddit_ads_list_businesses が見つからない場合は、そこで停止し、Hyper MCP を有効にして Reddit Ads を接続するようユーザーに伝えてください。広告の配信には、広告アカウントに有効な資金調達手段も必要です。資金調達手段がなくてもキャンペーンと広告グループは作成できますが、広告を配信するにはアカウントに資金が必要です。

このスキルのツールの実行方法

このスキルの各ツールは、正式なツール名で指定されています。利用するインターフェースに応じた呼び出し方法で実行してください。

インターフェース	ツールを探す	実行する
MCP クライアント（Claude、Cursor、Codex、ChatGPT）	search("<what you want to do>") を実行し、続けて describe("<name>")	call("<name>", {...})
Hyper CLI	hyperai search "<what you want to do>" を実行し、続けて hyperai describe <name>	hyperai call <name> --json '{...}'

ツールが見つからない場合、そのインテグレーションは接続されていないか、ワークスペースで有効になっていません。そこで停止し、接続するインテグレーションをユーザーに伝えてください。

対象外 — 他のスキルに委ねる

• オーガニックな Reddit リサーチ（サブレディットの議論、課題、顧客の声の調査）→ customer-research。
• クリエイティブの生成（広告コピー、画像）→ ad-creative-generation。
• 複数プラットフォームでのキャンペーン開始 → Reddit にはこのスキルを使い、その後 meta-ads／google-ads／tiktok-ads を個別に呼び出してください。

重要なルール

重要：すべての予算と入札額はマイクロ通貨で指定します。$1.00 = 1,000,000 マイクロです。1 日あたり $50 の予算は goal_value=50000000、CPC $0.50 は bid_value=500000 です。ドルの金額をそのまま渡さないでください。

重要：キャンペーン、広告グループ、広告は configured_status="PAUSED"（ツールキットのデフォルト値）で作成してください。ユーザーが明示的に確認する前に、配信を開始しないでください。すべてのデフォルトが PAUSED なので、費用をかけずにキャンペーン全体を作成してアーカイブできます。デモに最適です。

重要：データの探索はフラットなアカウント一覧ではなく、ビジネスを経由します。reddit_ads_get_me → reddit_ads_list_businesses → reddit_ads_list_ad_accounts(business_id=...) の順に実行してください。最上位の「すべての広告アカウントを一覧表示する」呼び出しはありません。

重要：広告は投稿を宣伝するものです。post_id（または profile_id と投稿の作成）が必要であり、クリエイティブのフィールドを直接指定するものではありません。広告を作成する前に、既存の投稿を探す（reddit_ads_list_posts）か、新しい投稿を作成してください（reddit_ads_create_post）。API で宣伝できるのはコミュニティ投稿のみです。

重要：広告グループの targeting.communities 配列には、search_targeting が返す t5_ ID ではなく、サブレディットの名前を指定します。検索結果の name フィールドを使ってください。例："communities": ["marketing", "SaaS", "Entrepreneur"] — t5_... ID を渡すと「You cannot set invalid communities」というエラーになります（interests には ID を使用し、geolocations には "US" のような国コードを使用します）。

重要：キャンペーンの設定前に reddit_ads_search_targeting でターゲティングを確認してください。値を推測してはいけません。targeting は create_ad_group の名前付きパラメーターです。オーディエンスやスケジュールなど、バリエーションが多いその他のフィールドは input_data で渡してください。

重要：広告グループの作成時には start_time（ISO 8601）が必須です。キャンペーンで start_time が有効なのは、CBO を有効にした場合のみです。CBO を有効にしないキャンペーンでは、キャンペーンレベルで start_time を省略し、広告グループに設定してください。そうしないと「Cannot set start_time for a campaign without having campaign budget optimization enabled」というエラーが発生します。 重大：bid_type が CPC/CPM/CPV/CPV6 の場合、bid_value は常に必須です。bid_strategy="MAXIMIZE_VOLUME" の場合も同様です。上限額を設定する（例：bid_value=600000 = $0.60）か、reddit_ads_generate_bid_suggestion から取得してください。

重大：即時の完全削除はできません。Reddit では、エンティティを完全に削除するには、3 時間以上 ARCHIVED にする必要があります。reddit_ads_delete_* は実際の削除を試み、まだ削除できない場合はアーカイブに切り替えます（配信は停止します）。返された configured_status（ARCHIVED または DELETED）を確認し、アーカイブから約 3 時間後に完全削除できることをユーザーに伝えてください。

重大：レポート（reddit_ads_get_report）には、fields、starts_at、ends_at が必要です。費用指標はマイクロ通貨単位で返されます。

重要：キャンペーンには name、objective、および（配信するには）funding_instrument_id が必要です。reddit_ads_list_funding_instruments で一覧表示してください。コンバージョン最適化された広告グループには conversion_pixel_id が必要です（reddit_ads_list_pixels）。2026-07-13 以降、広告グループと CBO キャンペーンには conversion_pixel_id が必要です。

重要：リード獲得はキャンペーンの目的（LEAD_GENERATION）として利用できますが、このツールキットではリード獲得フォームの管理はできません（機能制限付きのスコープが必要です）。リード獲得フォームは Reddit Ads Manager で作成してください。

重大（CONVERSIONS キャンペーン）：広告グループの optimization_goal は必須であり、標準（CBO ではない）CONVERSIONS キャンペーンで受け付けられる値は CLICKS のみです。SIGN_UP、PAGE_VISIT、PURCHASE などは有効な列挙値ですが、このキャンペーンタイプでは拒否されます（「Conversion goal ... is not valid for Conversions Campaigns」）。Reddit は、まず列挙値への適合性、次にキャンペーンタイプでの許可という 2 つの層で検証します。optimization_goal="CLICKS" を使用してください。配信は引き続き CONVERSIONS 目的によって決まります。

重大（投稿タイプ）：有効な投稿の type 値は IMAGE、VIDEO、CAROUSEL、TEXT であり、LINK ではありません。TEXT 投稿は「自由形式広告」であり、click_url を指定できず、CONVERSIONS キャンペーンの広告には使用できません。遷移先がある広告（特に CONVERSIONS）では、IMAGE / VIDEO / CAROUSEL 投稿を宣伝してください。

重大（新しいメディアを使った投稿の作成）：reddit_ads_create_structured_post を優先してください。メディアを URL として受け取り、Reddit がダウンロードして再ホストするため、事前アップロード済みのアセットは不要です。作成は非同期ジョブです。このツールは wait_seconds（デフォルトは 45）までポーリングしてジョブを返します。status="SUCCESS" の場合は job.post_id を広告の post_id として使用し、それ以外の場合は reddit_ads_get_structured_post_job をポーリングしてください。IMAGE には media_url と destination_url が必要です。VIDEO にも thumbnail_url が必要です。CAROUSEL では {image_url, destination_url, ...} カードを 1～6 枚指定します。PROMOTED_POST は既存の SFW コミュニティ投稿を ID で宣伝します。call_to_action は表示用ラベル（"Sign Up"、"Learn More"）であり、"SIGN_UP" ではありません。従来の reddit_ads_create_post は URL からメディアを取得できません。content[].media_url にはすでにアップロード済みの Reddit アセット（reddit_ads_list_creative_assets）を指定する必要があります。CTA は content[] 内に設定し、TEXT 投稿の content[] は空にしてください。従来のツールは既存アセットを再利用する場合にのみ使用してください。

重要：投稿は作成後、コメント以外は変更できません。見出し、メディア、遷移先を変更するには、新しい構造化投稿を作成してください。reddit_ads_update_post(post_id=..., allow_comments=...) はコメントの有効・無効のみを切り替えます（構造化投稿には is_structured_post=True を設定してください）。

ツール一覧

グループ	ツール
アイデンティティと検出	reddit_ads_get_me, reddit_ads_list_businesses, reddit_ads_list_ad_accounts, reddit_ads_get_ad_account, reddit_ads_list_funding_instruments
キャンペーン	reddit_ads_list_campaigns, reddit_ads_get_campaign, reddit_ads_create_campaign, reddit_ads_update_campaign, reddit_ads_delete_campaign
広告グループ	reddit_ads_list_ad_groups, reddit_ads_get_ad_group, reddit_ads_create_ad_group, reddit_ads_update_ad_group, reddit_ads_delete_ad_group
広告	reddit_ads_list_ads, reddit_ads_get_ad, reddit_ads_create_ad, reddit_ads_update_ad, reddit_ads_delete_ad
投稿とクリエイティブ	reddit_ads_list_profiles, reddit_ads_get_profile, reddit_ads_list_posts, reddit_ads_create_post, reddit_ads_get_post, reddit_ads_update_post, reddit_ads_list_creative_assets, reddit_ads_get_creative_asset
構造化投稿（URL によるメディア）	reddit_ads_create_structured_post, reddit_ads_get_structured_post_job, reddit_ads_list_structured_posts, reddit_ads_get_structured_post
ターゲティング	reddit_ads_search_targeting, reddit_ads_suggest_keywords, reddit_ads_validate_keywords, reddit_ads_validate_geolocations
オーディエンス	reddit_ads_list_custom_audiences, reddit_ads_create_custom_audience, reddit_ads_get_custom_audience, reddit_ads_delete_custom_audience, reddit_ads_update_custom_audience_users, reddit_ads_list_saved_audiences, reddit_ads_create_saved_audience, reddit_ads_get_saved_audience, reddit_ads_update_saved_audience
ピクセルとコンバージョン API	reddit_ads_list_pixels, reddit_ads_list_pixels_by_business, reddit_ads_post_conversion_events, reddit_ads_get_pixel_last_fired_at
予測とアクセス	reddit_ads_generate_bid_suggestion, reddit_ads_get_reach_forecast, reddit_ads_get_feature_access
アプリ／SKAdNetwork	reddit_ads_list_apps, reddit_ads_get_skan_availability, reddit_ads_get_app_last_fired_at_report
レポートと履歴	reddit_ads_get_report, reddit_ads_get_account_history

すべてのリファレンスファイルは references/ にあります。 references/<file> のパスで参照してください（例：references/discovery.md）。

ルーティング表

ユーザーの目的	最初に読むファイル
Reddit キャンペーンを開始する（目的を問わない）	references/discovery.md → references/campaign-creation.md
投稿をプロモーションする／投稿を作成する（URL によるメディアを含む）	references/campaign-creation.md
開始前にリーチを予測する	references/discovery.md
カスタムまたは保存済みオーディエンスを管理する／ターゲティングを解決する	references/audiences-and-targeting.md
ピクセル／コンバージョン API のトラッキングを設定する	references/conversions-and-reporting.md
レポートを取得する／エンティティを更新または削除する	references/conversions-and-reporting.md
目標がまだ明確でない	references/discovery.md — 検出によって目標を明確にします

キャンペーンのワークフロー

ビジネス／アカウントを検出 → アカウントを監査 → 調査（目的、ターゲティング、予算、投稿） → ターゲティング ID を解決 → 戦略を確認 → キャンペーンを作成（PAUSED） → 広告グループを作成 → 投稿を検索／作成 → 広告を作成 → ユーザーと確認 → 有効化（update_* を ACTIVE に設定）。

既知の制限

問題	回避策
即時の完全削除はできません。「削除するには、キャンペーンをアーカイブする必要があります」／「アーカイブしてから3時間経過するまでは削除できません」	仕様どおりです。delete_* は自動的にアーカイブ（配信を停止）します。アーカイブの約3時間後に完全削除が可能になります。後で削除を再実行すると、完全に削除されます。
広告の作成には post_id が必要です	既存のコミュニティ投稿を宣伝する（list_posts）か、新しく作成してください（create_post）。API 経由で宣伝できるのはコミュニティ投稿のみです。
ピクセルがないとコンバージョン広告グループが拒否されます	conversion_pixel_id を設定してください（list_pixels から取得）。2026-07-13 以降、広告グループ／CBO で必須になります。
キャンペーンが配信されません	funding_instrument_id を指定してください（list_funding_instruments から取得）。アカウントに資金がある必要があります。
API 経由ではリード獲得フォームを作成できません	フォームは Reddit Ads Manager で作成してください。API では LEAD_GENERATION の目的のみ設定できます。
バリアント作成時のフィールド（ターゲティング、スケジュール、クリエイティブ）は名前付きパラメーターではありません	input_data（辞書）で渡してください。リクエスト本文にマージされます。
広告アカウントの一覧を一括取得できません	get_me → list_businesses → list_ad_accounts(business_id) の順に確認してください。
"You cannot set invalid communities: {t5_...}"	targeting.communities 配列には、search_targeting の t5_ ID ではなく、サブレディットの名前が必要です。name フィールドを使用してください。
"Cannot set start_time ... without ... campaign budget optimization"	キャンペーンレベルの start_time は CBO 専用です。CBO 以外のキャンペーンでは省略し、広告グループに start_time を設定してください。
広告グループの作成時に start_time で "Input should be a valid datetime" が表示されます	広告グループでは start_time が必須です。必ず渡してください。
MAXIMIZE_VOLUME を指定しているのに bid_value が要求されます	CPC／CPM／CPV／CPV6 では、常に bid_value が必須です。上限額を指定するか、generate_bid_suggestion を使用してください。
generate_bid_suggestion：「Additional fields not permitted」／"'start_time' is a required property"	duration は ISO 形式の開始・終了日時範囲（{"start_time": ..., "end_time": ...}）であり、{"days": N} ではありません。
作成時に Varnish 503 が発生します	Reddit バックエンドの一時的なエラーです。再試行する前に、重複して作成されていないか（list_campaigns）確認してください。
作成直後に effective_status が PENDING_APPROVAL と表示されます	PAUSED エンティティでも（広告審査のため）正常な状態です。自動的に解除されるため、失敗ではありません。
CONVERSIONS 広告グループ：「Conversion goal (optimization goal) is required」／"... is not valid for Conversions Campaigns"	optimization_goal が必須です。また、CBO 以外の CONVERSIONS では CLICKS を指定する必要があります（このキャンペーンタイプでは SIGN_UP／PAGE_VISIT／PURCHASE は拒否されます）。
"'LINK' is not one of [CAROUSEL, IMAGE, TEXT, VIDEO]"	投稿の type は IMAGE／VIDEO／CAROUSEL／TEXT である必要があります。LINK タイプはありません。
広告作成時：「Posts used for ads in Conversion campaigns cannot be free-form ad」／「Free form ads cannot have a click url」	TEXT 投稿は自由形式です。CONVERSIONS 広告には IMAGE／VIDEO／CAROUSEL を使用してください。
IMAGE 投稿：「Image is required」	従来の create_post では、アセットを content[].media_url に指定してください（list_creative_assets で取得した、Reddit にアップロード済みのアセット）。post_url だけでは不十分です。新しいメディア URL から作成する場合は、代わりに reddit_ads_create_structured_post を使用してください。
構造化投稿ジョブがまだ完了していません（status が QUEUED／PROCESSING）	作成は非同期です。作成ツールは wait_seconds（既定値は45）までポーリングします。まだ保留中の場合は、reddit_ads_get_structured_post_job(post_creation_job_id=...) を SUCCESS（その後 post_id を使用）または CLIENT_ERROR／SERVER_ERROR（error_message を確認）になるまでポーリングしてください。
投稿の見出し／メディア／リンク先を変更したい	変更できません。投稿は不変です。新しい構造化投稿を作成してください。reddit_ads_update_post で切り替えられるのは allow_comments のみです。
投稿：「call_to_action "Additional fields not permitted"」	call_to_action はトップレベルではなく、content[] 内に指定します。また、列挙定数（"SIGN_UP"）ではなく、表示ラベル（"Sign Up"）を使用してください。
TEXT 投稿：「Post content must be empty for this post type」	TEXT 投稿には content[] ブロックを指定できません。指定できるのは IMAGE／VIDEO／CAROUSEL のみです。
ドル金額	常にマイクロ通貨単位です（×1,000,000）。

安全ルール

決して次のことを行わないでください：

• ビジネス、広告アカウント、キャンペーン、投稿、ピクセル、ターゲティングの ID を推測しないでください。検索するか、ユーザーに確認してください。
• アカウント監査のフェーズを省略しないでください。
• ユーザーの明示的な承認なしに、キャンペーン、広告グループ、広告を作成しないでください。
• ユーザーの同意なしに、何かを ACTIVE に設定しないでください。
• マイクロ通貨単位ではなく、ドル金額を渡さないでください。
• 有効な post_id なしに広告を作成しないでください。
• 即時に完全削除できると約束しないでください。Reddit では、まず 3 時間以上 ARCHIVED にする必要があります。
• ターゲティング ID を推測しないでください。reddit_ads_search_targeting で特定してください。