meta-api-reference

Meta Marketing API - 完全リファレンス

設定

• API バージョン： v22.0
• ベース URL： https://graph.facebook.com/v22.0/
• .env 内の 2 つのトークン：
  • ADS_MANAGER_ACCESS_TOKEN - Marketing API（キャンペーン管理、インサイト、レポート）
  • AD_LIBRARY_ACCESS_TOKEN - Ad Library API（競合他社の調査）
• トークンの有効期限： 最後に更新してから約 60 日（更新日については .env のコメントを確認してください）

---

アカウント階層

Ad Account (act_XXXX)
  -> Campaign (objective, budget if CBO, bid strategy)
    -> Ad Set (targeting, budget if ABO, optimization, schedule)
      -> Ad (creative reference, status)
        -> Ad Creative (media, copy, CTA, url_tags)

---

キャンペーンのスキーマ

エンドポイント： POST /{account_id}/campaigns

必須フィールド

フィールド	型	説明
name	string	キャンペーン名
objective	enum	マーケティングの目的（ODAX フレームワーク）
status	enum	キャンペーンのステータス
special_ad_categories	array	特別カテゴリの申告（該当しない場合は [] を指定）

任意フィールド

フィールド	型	説明
daily_budget	int (cents)	CBO の日予算（5000 = $50.00）
lifetime_budget	int (cents)	CBO の通算予算
bid_strategy	enum	入札戦略
buying_type	enum	購入タイプ
is_adset_budget_sharing_enabled	string	CBO の場合は "true"、ABO の場合は "false"
execution_options	array	["validate_only"] または ["include_recommendations"]

目的（ODAX フレームワーク）

値	説明	用途
OUTCOME_AWARENESS	ブランド認知度、リーチ	ファネル上部
OUTCOME_ENGAGEMENT	投稿エンゲージメント、動画再生数、ページへの「いいね！」	ファネル中部
OUTCOME_TRAFFIC	リンククリック、ランディングページビュー	ファネル中部
OUTCOME_LEADS	リード獲得フォーム、コンバージョン（リード）	ファネル下部
OUTCOME_SALES	コンバージョン（購入）、カタログ販売	ファネル下部
OUTCOME_APP_PROMOTION	アプリのインストール、アプリのエンゲージメント	アプリキャンペーン

従来の目的（新しいキャンペーンでは非推奨ですが、古いキャンペーンでは API から返されます）：CONVERSIONS、LEAD_GENERATION、LINK_CLICKS、BRAND_AWARENESS、REACH、POST_ENGAGEMENT、VIDEO_VIEWS、MESSAGES、APP_INSTALLS、PAGE_LIKES、EVENT_RESPONSES、STORE_VISITS、PRODUCT_CATALOG_SALES

入札戦略

値	説明
LOWEST_COST_WITHOUT_CAP	上限なしで最小コスト（デフォルト）
COST_CAP	コスト上限 - 結果あたりの最大コストを設定
LOWEST_COST_WITH_BID_CAP	入札上限 - オークションごとの最大入札額を設定
LOWEST_COST_WITH_MIN_ROAS	最小 ROAS - 目標とする最低リターンを設定

特別広告カテゴリ

値	説明
CREDIT	クレジットのオファー
EMPLOYMENT	求人
HOUSING	住宅・不動産
ISSUES_ELECTIONS_POLITICS	社会問題、選挙、政治
FINANCIAL_PRODUCTS_SERVICES	金融商品
ONLINE_GAMBLING_AND_GAMING	ギャンブル・ゲーム
NONE	特別カテゴリなし

購入タイプ

値	説明
AUCTION	標準のオークション方式（デフォルト。通常は 99% のケースで使用）
RESERVED	予約・配信保証（リーチ＆フリークエンシー）

キャンペーンのステータス

ACTIVE、PAUSED、DELETED、ARCHIVED

CBO と ABO

CBO（キャンペーン予算の最適化）：

• キャンペーンに daily_budget または lifetime_budget を設定します
• キャンペーンに is_adset_budget_sharing_enabled: "true" を設定します
• 広告セットには予算を設定しないでください
• Meta が広告セット間で予算を自動的に配分します

ABO（広告セット予算の最適化）：

• キャンペーンに is_adset_budget_sharing_enabled: "false" を設定します
• 各広告セットに daily_budget または lifetime_budget を設定します
• キャンペーンには予算を設定しないでください
• 各広告セットに個別の予算が割り当てられます

---

広告セットのスキーマ

エンドポイント： POST /{account_id}/adsets

必須フィールド

フィールド	型	説明
name	string	広告セット名
campaign_id	string	親キャンペーン ID
optimization_goal	enum	最適化の対象
billing_event	enum	課金のタイミング
targeting	JSON object	ターゲティングの指定
status	enum	広告セットのステータス
daily_budget or lifetime_budget	int (cents)	予算（ABO のみ）

任意フィールド

フィールド	型	説明
bid_amount	int (cents)	入札額（cost_cap または bid_cap では必須）
bid_strategy	enum	キャンペーンの入札戦略を上書きします
start_time	ISO 8601	配信開始日時
end_time	ISO 8601	配信停止日時
promoted_object	JSON object	コンバージョン最適化のピクセル／イベント
destination_type	enum	広告の遷移先
is_dynamic_creative	bool	ダイナミッククリエイティブを有効にします
pacing_type	array	["standard"] または ["day_parting"]
dsa_beneficiary	string	DSA 準拠 — 受益者名（EU）
dsa_payor	string	DSA 準拠 — 支払者名（EU）
targeting_automation	JSON object	Advantage+ オーディエンス設定

最適化の目標（34 種類）

最も一般的に使用される値：

値	使用する目的	説明
OFFSITE_CONVERSIONS	OUTCOME_LEADS, OUTCOME_SALES	ピクセル経由のウェブサイトコンバージョン
LEAD_GENERATION	OUTCOME_LEADS	プラットフォーム内のリードフォーム送信
LINK_CLICKS	OUTCOME_TRAFFIC	リンククリック
LANDING_PAGE_VIEWS	OUTCOME_TRAFFIC	ランディングページビュー（ピクセルが必要）
REACH	OUTCOME_AWARENESS	最大のユニークリーチ
IMPRESSIONS	OUTCOME_AWARENESS	最大のインプレッション数
AD_RECALL_LIFT	OUTCOME_AWARENESS	広告想起の最適化
POST_ENGAGEMENT	OUTCOME_ENGAGEMENT	投稿へのインタラクション
PAGE_LIKES	OUTCOME_ENGAGEMENT	ページへの「いいね！」
THRUPLAY	OUTCOME_ENGAGEMENT	動画視聴（15 秒以上）
VALUE	OUTCOME_SALES	コンバージョン値（ROAS）
APP_INSTALLS	OUTCOME_APP_PROMOTION	アプリのインストール
CONVERSATIONS	OUTCOME_LEADS	メッセージの会話
QUALITY_LEAD	OUTCOME_LEADS	質の高いリード（CRM 最適化）

全リスト（その他）： ADVERTISER_SILOED_VALUE、APP_INSTALLS_AND_OFFSITE_CONVERSIONS、AUTOMATIC_OBJECTIVE、DERIVED_EVENTS、ENGAGED_USERS、EVENT_RESPONSES、IN_APP_VALUE、MEANINGFUL_CALL_ATTEMPT、MESSAGING_APPOINTMENT_CONVERSION、MESSAGING_PURCHASE_CONVERSION、NONE、PROFILE_AND_PAGE_ENGAGEMENT、PROFILE_VISIT、QUALITY_CALL、REACH、REMINDERS_SET、SUBSCRIBERS、VISIT_INSTAGRAM_PROFILE

課金イベント

値	説明
IMPRESSIONS	インプレッションごとに課金（最も一般的で、95％以上のケースで使用）
LINK_CLICKS	リンククリックごとに課金
APP_INSTALLS	アプリのインストールごとに課金
THRUPLAY	動画視聴ごとに課金
CLICKS	すべてのクリックごとに課金
PAGE_LIKES	ページへの「いいね！」ごとに課金
POST_ENGAGEMENT	エンゲージメントごとに課金

全リスト（その他）： LISTING_INTERACTION、NONE、OFFER_CLAIMS、PURCHASE

遷移先の種類（最も一般的なもの）

値	説明
WEBSITE	ウェブサイト URL へ遷移（最も一般的）
ON_AD	広告内の遷移先（リードフォーム、インスタントエクスペリエンス）
MESSENGER	Messenger の会話
WHATSAPP	WhatsApp の会話
INSTAGRAM_DIRECT	Instagram の DM
APP	モバイルアプリ
FACEBOOK	Facebook の遷移先
ON_POST	投稿内
ON_VIDEO	動画内
SHOP_AUTOMATIC	自動ショップ

全リスト（その他）： APPLINKS_AUTOMATIC、FACEBOOK_LIVE、FACEBOOK_PAGE、IMAGINE、INSTAGRAM_LIVE、INSTAGRAM_PROFILE、INSTAGRAM_PROFILE_AND_FACEBOOK_PAGE、MESSAGING_INSTAGRAM_DIRECT_MESSENGER、MESSAGING_INSTAGRAM_DIRECT_MESSENGER_WHATSAPP、MESSAGING_INSTAGRAM_DIRECT_WHATSAPP、MESSAGING_MESSENGER_WHATSAPP、ON_EVENT、ON_PAGE

プロモーションオブジェクト

コンバージョン最適化に必須です。

# For pixel conversions (OUTCOME_LEADS or OUTCOME_SALES)
'promoted_object': json.dumps({
    'pixel_id': 'YOUR_PIXEL_ID',
    'custom_event_type': 'LEAD'  # or PURCHASE, COMPLETE_REGISTRATION, etc.
})

# For lead gen forms (OUTCOME_LEADS with LEAD_GENERATION goal)
'promoted_object': json.dumps({
    'page_id': 'YOUR_PAGE_ID'
})

# For app installs
'promoted_object': json.dumps({
    'application_id': 'YOUR_APP_ID',
    'object_store_url': 'https://apps.apple.com/...'
})

custom_event_type の値

LEAD、PURCHASE、COMPLETE_REGISTRATION、ADD_TO_CART、ADD_TO_WISHLIST、INITIATE_CHECKOUT、ADD_PAYMENT_INFO、CONTACT、CUSTOMIZE_PRODUCT、DONATE、FIND_LOCATION、SCHEDULE、START_TRIAL、SUBMIT_APPLICATION、SUBSCRIBE、SEARCH、VIEW_CONTENT、OTHER

---

ターゲティング仕様

完全な構造

targeting = {
    # GEOGRAPHIC (required)
    'geo_locations': {
        'countries': ['US', 'CA', 'GB'],           # ISO country codes
        'country_groups': ['north_america', 'europe'],  # OR use region codes
        'regions': [{'key': '3847'}],               # State/province
        'cities': [{'key': '2430536', 'radius': 10, 'distance_unit': 'mile'}],
        'zips': [{'key': 'US:10001'}],
        'location_types': ['home', 'recent']        # home, recent, travel_in
    },

    # DEMOGRAPHICS
    'age_min': 25,                  # 13-65
    'age_max': 55,                  # 13-65
    'genders': [1],                 # 1=male, 2=female, omit or [0]=all
    'locales': [6],                 # Language codes (6=English)

    # INTEREST/BEHAVIOR TARGETING
    'flexible_spec': [
        {
            'interests': [{'id': '6003107902433', 'name': 'SaaS'}],
            'behaviors': [{'id': '6002714895372', 'name': 'Small business owners'}]
        }
    ],
    # flexible_spec logic:
    #   Within one object: fields are OR'd (interest1 OR behavior1)
    #   Multiple objects in array: OR'd together
    #   Use 'exclusions' for AND NOT logic

    'exclusions': {
        'interests': [{'id': '123', 'name': 'Excluded Interest'}]
    },

    # AUDIENCES
    'custom_audiences': [{'id': 'YOUR_AUDIENCE_ID'}],
    'excluded_custom_audiences': [{'id': 'YOUR_EXCLUDED_AUDIENCE_ID'}],

    # ADVANTAGE+ AUDIENCE
    'targeting_optimization': 'expansion_all',  # Enable Advantage+ expansion

    # PLATFORMS & PLACEMENTS (usually omit for Advantage+ Placements)
    'publisher_platforms': ['facebook', 'instagram', 'audience_network', 'messenger'],
    'device_platforms': ['mobile', 'desktop'],
    'facebook_positions': ['feed', 'story', 'facebook_reels', 'right_hand_column', 'search', 'marketplace', 'video_feeds', 'instream_video', 'profile_feed', 'biz_disco_feed', 'facebook_reels_overlay'],
    'instagram_positions': ['stream', 'story', 'reels', 'profile_reels', 'ig_search', 'explore', 'explore_home', 'profile_feed'],
    'messenger_positions': ['story', 'inbox'],
    'audience_network_positions': ['classic', 'rewarded_video'],

    # CONNECTIONS
    'connections': [{'id': 'YOUR_PAGE_ID'}],           # Connected to page
    'excluded_connections': [{'id': 'YOUR_PAGE_ID'}]   # Not connected to page
}

Advantage+ オーディエンス（v23.0+）

'targeting_automation': {
    'advantage_audience': 1   # 1 = enabled, 0 = disabled
}

有効にすると、Meta の AI は定義したターゲティングの範囲を超えて、購入意欲の高いユーザーを見つけます。基本のターゲティング（地域、年齢など）は指定しますが、Meta はその範囲を超えてターゲティングできます。API v23.0+ ではデフォルトで有効です。

地域ターゲティングのルール

• 個別の国には countries を使用します：['US', 'CA', 'GB']
• 地域には country_groups を使用します：['north_america', 'europe']
• 地域でカバーできる場合、30 か国以上を個別に列挙しないでください
• 地域を重複させないでください（例：US と New York City の両方を指定するとエラーになります）
• 規制コンプライアンス項目を避けるため、Singapore を除外してください

興味・行動の検索

# Search for targeting interests
GET /search?type=adinterest&q=KEYWORD&limit=10000&locale=en_US&access_token=TOKEN

# Response:
# { "data": [{ "id": "6003107902433", "name": "SaaS", "audience_size": 123456, "path": ["..."], "topic": "..." }] }

# Alternative: interest suggestions
GET /search?type=adinterestsuggestion&interest_list=["SaaS"]&access_token=TOKEN

API では、Ads Manager のオートコンプリートに表示されない数千件の興味・関心を確認できます（オートコンプリートには約 25 件のみ表示されます）。

2026 年の注記： 2025 年 6 月以降、多くの詳細なターゲティングの興味・関心が統合されています。2025 年 10 月 8 日より前に作成された興味・関心を使用するキャンペーンは、配信が停止される場合があります。

---

広告クリエイティブのスキーマ

エンドポイント： POST /{account_id}/adcreatives

主なフィールド

フィールド	型	説明
name	文字列	クリエイティブ名
object_story_spec	JSON オブジェクト	メインのクリエイティブコンテンツコンテナー
url_tags	文字列	URL パラメーター（作成時のみ設定可能。更新できません）
instagram_user_id	文字列	IG ビジネスアカウント ID（ここ AND object_story_spec の両方に設定）
threads_user_id	文字列	Threads プロフィール ID（クリエイティブレベルに設定。object_story_spec 内には設定しません）
asset_feed_spec	JSON オブジェクト	配置のカスタマイズまたはダイナミッククリエイティブ用

object_story_spec - 2 つのパターン

パターン A：シンプルな広告（link_data）

'object_story_spec': json.dumps({
    'page_id': 'YOUR_PAGE_ID',
    'instagram_user_id': 'YOUR_IG_USER_ID',
    'link_data': {
        'image_hash': 'HASH',
        'link': 'https://landing-page.com',
        'message': 'Body text',
        'name': 'Headline',
        'description': 'Description',
        'call_to_action': {
            'type': 'SIGN_UP',
            'value': {'link': 'https://landing-page.com'}
        }
    }
})

パターン B：配置のカスタマイズ（asset_feed_spec）

'object_story_spec': json.dumps({
    'page_id': 'YOUR_PAGE_ID',
    'instagram_user_id': 'YOUR_IG_USER_ID'
    # NO link_data - all content goes in asset_feed_spec
})

重要： asset_feed_spec を使用する場合、object_story_spec は最小限（page_id と instagram_user_id のみ）にする必要があります。link_data を含めるとエラーになります。

link_data フィールド

フィールド	型	説明
link	文字列	遷移先 URL
message	文字列	広告本文
name	文字列	見出し
description	文字列	見出しの下に表示する説明
caption	文字列	リンクのキャプション／ドメイン表示
image_hash	文字列	アップロードした画像のハッシュ
picture	文字列	画像 URL（image_hash の代替）
call_to_action	オブジェクト	CTA ボタンの設定
child_attachments	配列	カルーセルカード（2～10 件）
multi_share_optimized	bool	Meta にパフォーマンスが最も高いカードを表示させる
multi_share_end_card	bool	カルーセルにエンドカードを表示する

video_data フィールド

'video_data': {
    'video_id': 'VIDEO_ID',           # From video upload (required)
    'image_url': 'THUMBNAIL_URL',      # From /{video_id}/thumbnails (required)
    'title': 'Video title',
    'message': 'Body text',
    'link_description': 'Description',
    'call_to_action': {
        'type': 'LEARN_MORE',
        'value': {'link': 'https://landing.com'}
    }
}

カルーセルの child_attachments

'child_attachments': [
    {
        'link': 'https://product1.com',
        'name': 'Card 1 Headline',
        'description': 'Card 1 description',
        'image_hash': 'IMAGE_HASH_1',
        'call_to_action': {
            'type': 'SHOP_NOW',
            'value': {'link': 'https://product1.com'}
        }
    },
    {
        'link': 'https://product2.com',
        'name': 'Card 2 Headline',
        'description': 'Card 2 description',
        'image_hash': 'IMAGE_HASH_2'
    }
    # 2-10 cards total, each card needs image_hash + link at minimum
]

CTA タイプ（全種類）

B2B で最もよく使われるタイプ：

値	説明
SIGN_UP	登録
LEARN_MORE	詳細を見る
DOWNLOAD	ダウンロード
SUBSCRIBE	購読する
APPLY_NOW	今すぐ申し込む
GET_QUOTE	見積もりを依頼する
CONTACT_US	お問い合わせ
BOOK_NOW	今すぐ予約する
REGISTER_NOW	今すぐ登録する
SHOP_NOW	今すぐ購入する
MESSAGE_PAGE	メッセージを送信する

カテゴリ別の全種類：

コマース：BUY_NOW、BUY_TICKETS、ORDER_NOW、SELL_NOW、GET_OFFER、ADD_TO_CART、PURCHASE_GIFT_CARDS、PAY_TO_ACCESS

情報：SEE_MENU、GET_SHOWTIMES、GET_DIRECTIONS

アプリ：INSTALL_APP、INSTALL_MOBILE_APP、USE_APP、USE_MOBILE_APP、GET_MOBILE_APP、PLAY_GAME、UPDATE_APP

エンゲージメント：BOOK_TRAVEL、REQUEST_TIME、SEND_INVITES、REFER_FRIENDS、OPEN_MESSENGER_EXT、INSTAGRAM_MESSAGE、CALL、CALL_NOW、CALL_ME

メディア：WATCH_VIDEO、WATCH_MORE、LISTEN_MUSIC、LISTEN_NOW、GO_LIVE、RECORD_NOW

ソーシャル：LIKE_PAGE、VIEW_INSTAGRAM_PROFILE、INTERESTED、SAVE、SEND_TIP、DONATE、DONATE_NOW、EVENT_RSVP、VOTE_NOW

その他：OPEN_LINK、NO_BUTTON、BET_NOW、PRE_REGISTER、GET_EVENT_TICKETS、SEARCH_MORE

url_tags

• クリエイティブの作成時にのみ設定できます。更新はできないため、クリエイティブを再作成する必要があります
• 標準形式：utm_source=meta&utm_medium=paid-social&utm_campaign={{adset.name}}&utm_content={{ad.name}}
• 動的パラメーター：{{campaign.name}}、{{campaign.id}}、{{adset.name}}、{{adset.id}}、{{ad.name}}、{{ad.id}}、{{placement}}、{{site_source_name}}

---

広告スキーマ

エンドポイント： POST /{account_id}/ads

フィールド	型	必須	説明
name	string	はい	広告名
adset_id	string	はい	親広告セットの ID
creative	JSON object	はい	{"creative_id": "CREATIVE_ID"}
status	enum	はい	PAUSED（ACTIVEには絶対に設定しないでください）
tracking_specs	JSON array	いいえ	追加のコンバージョントラッキング

---

カスタムオーディエンスのスキーマ

エンドポイント： POST /{account_id}/customaudiences

顧客リストのアップロード

# Step 1: Create audience
'name': 'My Customer List',
'subtype': 'CUSTOM',
'customer_file_source': 'USER_PROVIDED_ONLY'

# Step 2: Add users via /{audience_id}/users
'schema': ['EMAIL', 'FN', 'LN'],   # or 'PHONE', 'MOBILE_ADVERTISER_ID', 'UID'
'data': [
    ['sha256_hashed_email', 'sha256_hashed_firstname', 'sha256_hashed_lastname'],
    # ... up to 10,000 per batch
]

すべての個人識別情報（PII）フィールドは、送信前に SHA-256 でハッシュ化する必要があります。正規化するには、小文字に変換して空白を削除し、電話番号は E.164 形式にします。

ウェブサイトカスタムオーディエンス

'name': 'Website Visitors - Last 30 Days',
'subtype': 'WEBSITE',
'rule': json.dumps({
    'inclusions': {
        'operator': 'or',
        'rules': [{'event_sources': [{'id': 'YOUR_PIXEL_ID', 'type': 'pixel'}], 'retention_seconds': 2592000}]
    }
})

類似オーディエンス

'name': '1% Lookalike - US - Customer List',
'subtype': 'LOOKALIKE',
'origin_audience_id': 'SOURCE_AUDIENCE_ID',   # min 100 members, recommended 1000-5000
'lookalike_spec': json.dumps({
    'ratio': 0.01,          # 1% similarity (0.01 to 0.20)
    'country': 'US',        # Single country per lookalike
    'starting_ratio': 0.00  # Optional: for tiered lookalikes (e.g., 1-2% tier)
})

段階的なパターン： まず 0～1％（ratio=0.01）、次に 1～2％（ratio=0.02、starting_ratio=0.01）、続いて 2～3％（ratio=0.03、starting_ratio=0.02）を作成します。

2026 年の注意事項： 新しい類似オーディエンスを作成するには、lookalike_specが必須です（2026 年 1 月 6 日以降）。

---

リーチの推定

エンドポイント： GET /{account_id}/reachestimate

params = {
    'access_token': token,
    'currency': 'USD',
    'optimize_for': 'OFFSITE_CONVERSIONS',
    'targeting_spec': json.dumps({
        'geo_locations': {'countries': ['US']},
        'age_min': 25,
        'age_max': 55
    })
}

推定オーディエンス規模を範囲で返し、1 日あたりの推定結果と入札額の推定値も返します。

---

インサイト／レポート

エンドポイント： GET /{object_id}/insights（アカウント、キャンペーン、広告セット、広告の各レベルで使用できます）

主なパラメーター

パラメーター	型	説明
fields	string	カンマ区切りの指標
date_preset	enum	定義済みの日付範囲
time_range	JSON	カスタム日付範囲 {"since":"2026-01-01","until":"2026-01-31"}
level	enum	campaign、adset、ad（内訳レベル）
breakdowns	string	カンマ区切りの配信内訳
action_breakdowns	string	カンマ区切りのアクション内訳
time_increment	int or string	1～90（日）、"monthly"、"all_days"
limit	int	1 ページあたりの結果数（デフォルトは 25）
filtering	JSON array	フィルター条件

日付プリセット

today、yesterday、last_3d、last_7d、last_14d、last_28d、last_30d、last_90d、this_week_mon_today、this_week_sun_today、last_week_mon_sun、last_week_sun_sat、this_month、last_month、this_quarter、last_quarter、this_year、last_year、maximum、lifetime

一般的な指標

spend、impressions、clicks、reach、frequency、ctr、cpc、cpm、actions、cost_per_action_type、action_values、conversions、cost_per_conversion、conversion_values、purchase_roas

配信の内訳

内訳	説明
age	年齢層
gender	性別
country	国
region	地域／州
dma	DMA（米国のみ）
publisher_platform	Facebook、Instagram など
platform_position	フィード、ストーリーズ、リールなど
device_platform	モバイル、デスクトップ
impression_device	デバイスの種類
frequency_value	フリークエンシーの分布
hourly_stats_aggregated_by_advertiser_time_zone	時刻（広告主のタイムゾーン）
hourly_stats_aggregated_by_audience_time_zone	時刻（オーディエンスのタイムゾーン）
product_id	商品カタログ ID

ダイナミッククリエイティブの内訳： ad_format_asset、body_asset、call_to_action_asset、description_asset、image_asset、link_url_asset、title_asset、video_asset

重要： 1 つのリクエストで配信の内訳と action_breakdowns を組み合わせることはできません。それぞれ別にリクエストしてください。

アクションの内訳

内訳	説明
action_type	アクションの種類（リード、購入など）
action_device	アクションが発生したデバイス
action_destination	アクションの遷移先

action_type の値

よく使われる値：

action_type	説明
lead	プラットフォーム内のリードフォーム送信
link_click	リンクのクリック
landing_page_view	ランディングページの表示
post_engagement	投稿へのエンゲージメント
video_view	動画の視聴
page_engagement	ページへのエンゲージメント
onsite_conversion.lead_grouped	プラットフォーム内のリードイベント（グループ化）
offsite_conversion.fb_pixel_lead	ピクセルのリードイベント
offsite_conversion.fb_pixel_purchase	ピクセルの購入イベント
offsite_conversion.fb_pixel_add_to_cart	ピクセルのカート追加
offsite_conversion.fb_pixel_initiate_checkout	ピクセルのチェックアウト開始
offsite_conversion.fb_pixel_complete_registration	ピクセルの登録
offsite_conversion.fb_pixel_view_content	ピクセルのコンテンツ表示
offsite_conversion.fb_pixel_custom	ピクセルのカスタムコンバージョン
omni_purchase	クロスチャネルの購入
omni_add_to_cart	クロスチャネルのカート追加

アクションからコンバージョンを抽出する

actions = row.get('actions', [])
leads = sum(int(a['value']) for a in actions if a['action_type'] == 'lead')
pixel_leads = sum(int(a['value']) for a in actions if a['action_type'] == 'offsite_conversion.fb_pixel_lead')

非同期レポート（大規模データセット）

日付範囲が広い場合や、複雑な内訳を使用する場合：

# Request async report
params['async'] = True
r = requests.get(url, params=params)
report_id = r.json()['report_run_id']

# Poll for completion
status_url = f'https://graph.facebook.com/v22.0/{report_id}'
r = requests.get(status_url, params={'access_token': token})
# Check async_status: "Job Completed", "Job Running", etc.

# Download results
results_url = f'https://graph.facebook.com/v22.0/{report_id}/insights'
r = requests.get(results_url, params={'access_token': token})

データの保持期間（2026年）

• ユニークカウントのフィールド：過去 13 か月分のデータ
• フリークエンシーの内訳：6 か月分
• 時間単位の内訳：13 か月分
• 100 を超える指標が非推奨（unique_actions を含む）

---

アトリビューション設定（2026年）

attribution_spec

'attribution_spec': json.dumps([
    {'event_type': 'CLICK_THROUGH', 'window_days': 7},
    {'event_type': 'VIEW_THROUGH', 'window_days': 1}
])

利用可能な期間（2026年1月12日以降）

クリックスルー	ビュースルー
1日	1日
7日（デフォルト）	7日 削除
	28日 削除

デフォルト：7日間のクリック＋1日間の表示（7d_click / 1d_view）。

影響： 7日間および28日間のビュースルー期間は、2026年1月12日に削除されました。これらの期間を使用した過去のレポートでは、データが返されなくなりました。

---

Conversions API（CAPI）- サーバーサイドイベント

エンドポイント： POST /{pixel_id}/events

イベント構造

{
    'data': [
        {
            'event_name': 'Lead',               # Standard event name
            'event_time': 1709568234,            # Unix timestamp
            'event_id': 'unique-event-12345',    # For deduplication with pixel
            'action_source': 'website',          # website, app, offline, etc.
            'event_source_url': 'https://site.com/page',
            'user_data': {
                'em': ['sha256_hashed_email'],   # MUST be hashed
                'ph': ['sha256_hashed_phone'],   # MUST be hashed, E.164 format
                'fn': ['sha256_hashed_first'],   # MUST be hashed, lowercase
                'ln': ['sha256_hashed_last'],    # MUST be hashed, lowercase
                'fbp': 'fb.1.123.456',           # NOT hashed (browser cookie)
                'fbc': 'fb.1.123.456',           # NOT hashed (click cookie)
                'external_id': ['sha256_hashed_id'],
                'client_ip_address': '1.2.3.4',
                'client_user_agent': 'Mozilla/5.0...'
            },
            'custom_data': {
                'value': 99.99,                  # Required for Purchase
                'currency': 'USD',               # Required for Purchase
                'content_ids': ['product123'],
                'content_type': 'product',
                'order_id': 'order-456'
            }
        }
    ],
    'access_token': token
}

標準イベント名

Purchase、Lead、ViewContent、AddToCart、InitiateCheckout、CompleteRegistration、AddPaymentInfo、AddToWishlist、Contact、FindLocation、Schedule、Search、StartTrial、SubmitApplication、Subscribe、CustomizeProduct、Donate

重複排除

• Pixel と CAPI の両方で、同一の event_name と event_id を送信する必要があります
• Meta は一致するイベントを自動的に重複排除します
• 重複排除しない場合、コンバージョンが二重にカウントされます
• サーバーで event_id を生成し、Pixel と CAPI の両方に渡してください

user_data のハッシュ化ルール

フィールド	ハッシュ化？	備考
em（メールアドレス）	SHA-256	まず小文字に正規化します
ph（電話番号）	SHA-256	E.164 形式にし、スペースやハイフンを除きます
fn（名）	SHA-256	小文字にします
ln（姓）	SHA-256	小文字にします
external_id	SHA-256	顧客 ID
fbp	いいえ	ブラウザーの Cookie のため、生の値を送信します
fbc	いいえ	クリック Cookie のため、生の値を送信します
client_ip_address	いいえ	生の値を送信します
client_user_agent	いいえ	生の値を送信します

重要： fbp または fbc をハッシュ化すると、照合が完全に機能しなくなります。

---

画像のアップロード

エンドポイント： POST /{account_id}/adimages

要件

• 形式：JPG または PNG
• 最大サイズ：30MB
• 推奨：最小 1080x1080px
• アスペクト比：1:1（フィード）、4:5（フィード）、9:16（ストーリーズ／リール）

レスポンス

{
  "images": {
    "filename.jpg": {
      "hash": "a1b2c3d4e5f6...",
      "url": "https://scontent.xx.fbcdn.net/...",
      "height": 1080,
      "width": 1080
    }
  }
}

---

動画のアップロード

エンドポイント： POST /{account_id}/advideos

要件

• 形式：MP4、MOV（H.264 コーデックを推奨）
• 最大サイズ：4GB
• フィード：1 秒～240 分、アスペクト比 4:5 または 1:1
• ストーリーズ／リール：1～60 秒（15 秒を推奨）、アスペクト比 9:16
• 広告の作成にはサムネイルが必須です。GET /{video_id}/thumbnails から取得します

チャンク分割アップロード（100MB を超えるファイルの場合）

3 つのフェーズがあります。

1. upload_phase=start + file_size -> upload_session_id が返されます
2. upload_phase=transfer + upload_session_id + start_offset + video_file_chunk（繰り返し）
3. upload_phase=finish + upload_session_id + title -> 動画 ID が返されます

---

ページネーション

data = r.json()
results = data.get('data', [])

while 'paging' in data and 'next' in data['paging']:
    r = requests.get(data['paging']['next'])
    data = r.json()
    results.extend(data.get('data', []))

---

CRUD 操作

作成

r = requests.post(f'https://graph.facebook.com/v22.0/{parent_id}/{edge}', data={...})
# edge: campaigns, adsets, ads, adcreatives, adimages, advideos, customaudiences

読み取り

r = requests.get(f'https://graph.facebook.com/v22.0/{object_id}', params={
    'fields': 'field1,field2,...',
    'access_token': token
})

更新

r = requests.post(f'https://graph.facebook.com/v22.0/{object_id}', data={
    'name': 'New Name',
    'status': 'PAUSED',
    'access_token': token
})

削除

r = requests.delete(f'https://graph.facebook.com/v22.0/{object_id}', params={
    'access_token': token
})

---

主な注意点とルール

1. 必ず Python を使い、curl は使わないでください - トークンに含まれる文字がシェルによる展開で壊れることがあります
2. 必ず dotenv を介して .env からトークンを読み込んでください - コマンドにトークンを直接貼り付けないでください
3. 予算の単位はセントです - 5000 = $50.00
4. is_adset_budget_sharing_enabled は文字列です - "true" / "false" であり、ブール値ではありません
5. URL、広告文、その他のクリエイティブコンテンツを更新する場合 - 変更内容を含む完全な仕様のインライン creative JSON を指定して、広告（クリエイティブではなく）に POST します。この方法で url_tags も変更できます。
6. Instagram アカウントは 2 か所に指定します - トップレベルの instagram_user_id と object_story_spec の両方です
7. asset_feed_spec を使う場合の最小限の object_story_spec - page_id と instagram_user_id のみを指定し、link_data は指定しません
8. 配置ごとに異なる画像を使う場合は optimization_type: PLACEMENT、ダイナミッククリエイティブの場合は REGULAR を使います
9. REGULAR では広告セットごとに広告は 1 つに制限されます - 複数の広告が必要な場合は PLACEMENT を使います
10. 動画のサムネイルは必須です - アップロード後に /{video_id}/thumbnails から取得します
11. 100MB を超えるファイルは単一アップロードに失敗します - 大きな動画には必ずチャンク分割アップロードを使います
12. 規制遵守に関するフィールドを避けるため、ターゲティングからシンガポールを除外します
13. カスタムオーディエンスの利用規約 - エラー 1359208 が発生した場合は、Ads Manager の UI で利用規約への再同意が必要です（API ではこれを検出できません）
14. data: [] が空の場合は、その期間にアクティビティがなかったことを示し、エラーではありません
15. 配信とアクションの内訳は、同じインサイトリクエストに組み合わせられません
16. 広告文の書式 - 段落間には必ず \n\n、リスト内には \n を使います
17. Threads プロフィールの ID - threads_user_id はクリエイティブレベルに設定します（object_story_spec の中には設定しません）。Threads プロフィール ID を確認するには、既存の正常なクリエイティブを調べます：GET /{creative_id}?fields=threads_user_id。Threads プロフィールは Facebook ページに直接紐づくのではなく、Instagram アカウントに紐づきます。