這份文件已更新。
中文(台灣) 的翻譯尚未完成。

英文更新時間：2025年5月26日

洞察報告 API

為擷取廣告統計資料提供單一且一致的介面。

資料解析 - 將結果分組
動作資料解析 - 瞭解動作資料解析的回應。
非同步工作 - 對於有大量結果的要求，使用非同步工作
限制和最佳作法 - 呼叫限制、篩選條件和最佳作法。

在取得廣告成效資料之前，您應設定廣告，以便追蹤感興趣的衡量指標。為此，您可以使用網址標籤、Meta 像素和轉換 API。

準備工作

必備資料：

ads_read 權限。
一個應用程式。請參閱 Meta應用程式開發以瞭解更多資訊。

行銷活動統計資料

若要取得行銷活動過去 7 天的成效統計資料：

curl -G \
  -d "date_preset=last_7d" \
  -d "access_token=ACCESS_TOKEN" \
  "https://graph.facebook.com/API_VERSION/AD_CAMPAIGN_ID/insights"

如需瞭解詳情，請參閱廣告洞察報告：參考資料。

進行呼叫

所有廣告物件都會以關係連線的方式提供洞察報告 API。

API 方法
`act_<AD_ACCOUNT_ID>/insights`
`<CAMPAIGN_ID>/insights`
`<ADSET_ID>/insights`
`<AD_ID>/insights`

要求

您可在 fields 參數中使用逗號分隔清單來要求特定欄位。例如：

curl -G \
-d "fields=impressions" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v25.0/<AD_ID>/insights"

回應

{
  "data": [
    {
      "impressions": "2466376",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

層級

將結果彙總在已定義的物件層級，重複資料就會自動刪除。

要求

例如，取得行銷活動在廣告層級的洞察報告。

curl -G \
-d "level=ad" \
-d "fields=impressions,ad_id" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v25.0/CAMPAIGN_ID/insights"

回應

{
  "data": [
    {
      "impressions": "9708",
      "ad_id": "6142546123068",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "impressions": "18841",
      "ad_id": "6142546117828",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

若無權限存取所要求層級的所有廣告物件，洞察報告呼叫不會回傳任何資料。例如，要求 level 設為 ad 的洞察報告時，如果沒有權限可存取廣告帳號中的一個或多個廣告物件，此 API 呼叫會回傳權限錯誤訊息。

歸因期間

轉換歸因期間定義了將事件歸因於 Meta 廣告的起訖時間。如需相關背景資訊，請參閱 Meta 企業商家使用說明：關於歸因期間。我們會從發生轉換事件的時間點回顧 1 天和 7 天來衡量動作成效。若要檢視歸因至各個歸因期間的動作，請對 /{ad-account-id}/insights 發出要求。若未提供 action_attribution_windows，我們會使用 7d_click 並在 value 中提供其值。

例如，指定 action_attribution_windows，則「value」會固定為 7d_click 歸因期間。對 act_10151816772662695/insights?action_attribution_windows=['1d_click','1d_view'] 發出要求會得到以下結果：

"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608,
"1d_view": 86,
"1d_click": 6510
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344,
"1d_view": 27.354069767442,
"1d_click": 0.36135944700461
},

// if attribution window is _not_ specified in query. And note that the number under 'value' key is the same even if attribution window is specified.
// act_10151816772662695/insights
"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344
},

欄位擴充

要求節點層級的欄位和欄位擴展中指定的子欄位。

要求

curl -G \
-d "fields=insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v25.0/AD_ID"

回應

{
  "id": "6042542123268",
  "name": "My Website Clicks Ad",
  "insights": {
    "data": [
      {
        "impressions": "9708",
        "date_start": "2016-03-06",
        "date_stop": "2016-04-01"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

排序

以 sort 參數及 {fieldname}_descending 或 {fieldname}_ascending 排序結果：

要求

curl -G \
-d "sort=reach_descending" \
-d "level=ad" \
-d "fields=reach" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v25.0/AD_SET_ID/insights"

回應


{
  "data": [
    {
      "reach": 10742,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "reach": 5630,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-03"
    },
    {
      "reach": 3231,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-02"
    },
    {
      "reach": 936,
      "date_start": "2009-03-29",
      "date_stop": "2016-04-02"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

廣告標籤

將所有標籤名稱相同的統計數據，在廣告物件層級彙總為單一數值。請參閱廣告標籤：參考文件以瞭解更多資訊。

要求

curl -G \  
-d "fields=id,name,insights{unique_clicks,cpm,total_actions}" \
-d "level=ad" \
-d 'filtering=[{"field":"ad.adlabels","operator":"ANY", "value":["Label Name"]}]'  \
-d 'time_range={"since":"2015-03-01","until":"2015-03-31"}' \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v25.0/AD_OBJECT_ID/insights"

回應

{
  "data": [
    {
      "unique_clicks": 74,
      "cpm": 0.81081081081081,
      "total_actions": 49,
      "date_start": "2015-03-01",
      "date_stop": "2015-03-31",
    },
  ], 
  "paging": {
    "cursors": {
      "before": "MA==",
      "after": "MA==",
    }
  }
}

點擊次數的定義

如需深入瞭解 Meta 現在提供的點擊次數衡量指標，請參閱下方各衡量指標的定義和用途：

連結點擊次數：actions:link_click - 用戶點擊廣告連結前往特定目的地網頁或網路空間的次數（不限於 Meta 旗下應用程式與服務）。請參閱廣告使用說明：連結點擊次數
點擊次數（全部）：clicks - 此指標會計算用戶在廣告進行的各種點擊動作，包括與廣告容器進行特定類型的互動、點擊連結前往其他目的地，以及點擊連結進入廣告的延伸體驗。請參閱廣告使用說明：點擊次數（全部）

已刪除和已封存物件

廣告單位的狀態可能為 DELETED 或 ARCHIVED。已刪除或已封存物件的統計資料會在查詢其父節點時顯示。換言之，如果查詢廣告組合層級的 impressions，結果會包含廣告組合內所有廣告的 impressions，不論廣告是否為已刪除或已封存的狀態。另請參閱儲存與擷取廣告物件的最佳作法。

然而，如果您使用篩選條件進行查詢，系統預設會套用狀態篩選條件以僅傳回有效的物件。因此，父節點的統計資料可能大於其子節點的統計資料總和。

不過，您可從其父節點取得 ARCHIVED 物件的統計資料，方法是提供額外的 filtering 參數。

要求

若要取得廣告帳號中所有 ARCHIVED 廣告的統計資料，並逐一列出：

curl -G \
  -d "level=ad" \
  -d "filtering=[{'field':'ad.effective_status','operator':'IN','value':['ARCHIVED']}]" \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/insights/"

回應

請注意，這個回應僅傳回已封存物件。

{
  "data": [
    {
      "impressions": "1741",
      "date_start": "2016-03-11",
      "date_stop": "2016-03-12"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

已刪除物件的洞察報告

如果您有已刪除物件的編號，就可查詢其洞察報告，或者使用 ad.effective_status 篩選條件查詢。

要求

例如，如果您有廣告組合編號：

curl -G \
-d "fields=id,name,status,insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v25.0/AD_SET_ID"

在這個範例中，我們使用 ad.effective_status 查詢：

POST https://graph.facebook.com/<VERSION>/act_ID/insights?access_token=token&appsecret_proof=proof&fields=ad_id,impressions&date_preset=lifetime&level=ad&filtering=[{"field":"ad.effective_status","operator":"IN","value":["DELETED"]}]

回應

{
  "id": "6042147342661",
  "name": "My Like Campaign",
  "status": "DELETED",
  "insights": {
    "data": [
      {
        "impressions": "1741",
        "date_start": "2016-03-11",
        "date_stop": "2016-03-12"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

疑難排解

逾時

最常在這個端點造成錯誤的原因為要求的數量過多和逾時：

使用 /GET 或同步要求時，可能發生記憶體耗盡或逾時錯誤。
使用 /POST 或非同步要求時，可能發生逾時錯誤。使用非同步要求時，可能需要長達一小時才能完成要求（包括重新嘗試）。例如，如果您發出的查詢嘗試擷取許多廣告層級物件的大量資料。

建議

查詢失敗與否並無明確限制。如果發生逾時，請嘗試置入日期範圍等篩選條件，將查詢拆開為數個較小的查詢。
不重複指標的計算非常耗時。請嘗試在分開的呼叫中查詢不重複指標，以提升非不重複指標的效能。

限速

Meta 洞察報告 API 會利用限速來確保所有合作夥伴都能獲得最佳的分析報告體驗。如需詳細資訊和建議，請參閱洞察報告 API 的限制和最佳作法。

與廣告管理員的差異

自 2025 年 6 月 10 日起，為了減少與 Meta 廣告管理員的差異，系統將忽略 use_unified_attribution_setting 和 action_report_time parameters，API 回應將模仿廣告管理員設定：

歸因的 value 將根據廣告組合層級歸因設定（類似於 use_unified_attribution_setting=true），內嵌／廣告上動作將包含在 1d_click 或 1d_view 歸因期間資料中。此變更之後，系統將不再傳回獨立的 inline 歸因期間資料。
系統將使用 action_report_time=mixed 回報動作：Meta 上的動作（例如連結點擊次數）會使用以曝光為基礎的分析報告時間；而 Meta 站外動作（例如網站購物）則會使用以轉換為基礎的分析報告時間。

API 的預設行為與廣告管理員中的預設行為不同。如果您想觀察與在廣告管理員中之行為相同的行為，請將 use_account_attribution_setting 欄位設為 true。

瞭解詳情

上方未列出的端點即不在此 API 的範圍內。如果您預計在解決方案中加入 Meta 的報告，請參閱《Meta 開放平台使用條款》和行銷 API 的《開發商政策》。