curl \
-H "Authorization: Bearer API_KEY" \
-X GET "https://api.ayrshare.com/api/ads/facebook/insights?level=campaign&ids=120200000000000001&startDate=2026-09-01&endDate=2026-09-02"
const API_KEY = "API_KEY";
const params = new URLSearchParams({
level: "campaign",
ids: "120200000000000001",
startDate: "2026-09-01",
endDate: "2026-09-02",
});
fetch(`https://api.ayrshare.com/api/ads/facebook/insights?${params}`, {
method: "GET",
headers: { Authorization: `Bearer ${API_KEY}` },
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
import requests
headers = {'Authorization': 'Bearer API_KEY'}
params = {
'level': 'campaign',
'ids': '120200000000000001',
'startDate': '2026-09-01',
'endDate': '2026-09-02',
}
r = requests.get('https://api.ayrshare.com/api/ads/facebook/insights', headers=headers, params=params)
print(r.json())
{
"status": "success",
"platform": "facebook",
"level": "campaign",
"startDate": "2026-09-01",
"endDate": "2026-09-02",
"insights": [
{
"date": "2026-09-01",
"level": "campaign",
"id": "120200000000000001",
"currency": "USD",
"spend": 12.34,
"impressions": 4000,
"reach": 3100,
"clicks": 80,
"cpm": 3.085,
"cpc": 0.15425,
"ctr": 2,
"actions": [
{ "type": "link_click", "value": 75 },
{ "type": "omni_purchase", "value": 3 }
],
"conversionValue": 89.97
}
],
"count": 1,
"nextCursor": null
}
{
"status": "success",
"platform": "facebook",
"level": "ad",
"startDate": "2026-09-01",
"endDate": "2026-09-01",
"insights": [
{
"date": "2026-09-01",
"level": "ad",
"id": "120210000000000001",
"age": "25-34",
"gender": "female",
"currency": "EUR",
"spend": 1.5,
"impressions": 300
},
{
"date": "2026-09-01",
"level": "ad",
"id": "120210000000000001",
"age": "25-34",
"gender": "male",
"currency": "EUR",
"spend": 1,
"impressions": 200
}
],
"count": 2,
"nextCursor": null
}
{
"action": "ads",
"status": "error",
"code": 400,
"message": "The ad is not found or not authorized."
}
Facebook Ads
洞察報告
依廣告活動或廣告獲取即時的每日 Facebook 廣告洞察報告
GET
/
ads
/
facebook
/
insights
curl \
-H "Authorization: Bearer API_KEY" \
-X GET "https://api.ayrshare.com/api/ads/facebook/insights?level=campaign&ids=120200000000000001&startDate=2026-09-01&endDate=2026-09-02"
const API_KEY = "API_KEY";
const params = new URLSearchParams({
level: "campaign",
ids: "120200000000000001",
startDate: "2026-09-01",
endDate: "2026-09-02",
});
fetch(`https://api.ayrshare.com/api/ads/facebook/insights?${params}`, {
method: "GET",
headers: { Authorization: `Bearer ${API_KEY}` },
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
import requests
headers = {'Authorization': 'Bearer API_KEY'}
params = {
'level': 'campaign',
'ids': '120200000000000001',
'startDate': '2026-09-01',
'endDate': '2026-09-02',
}
r = requests.get('https://api.ayrshare.com/api/ads/facebook/insights', headers=headers, params=params)
print(r.json())
{
"status": "success",
"platform": "facebook",
"level": "campaign",
"startDate": "2026-09-01",
"endDate": "2026-09-02",
"insights": [
{
"date": "2026-09-01",
"level": "campaign",
"id": "120200000000000001",
"currency": "USD",
"spend": 12.34,
"impressions": 4000,
"reach": 3100,
"clicks": 80,
"cpm": 3.085,
"cpc": 0.15425,
"ctr": 2,
"actions": [
{ "type": "link_click", "value": 75 },
{ "type": "omni_purchase", "value": 3 }
],
"conversionValue": 89.97
}
],
"count": 1,
"nextCursor": null
}
{
"status": "success",
"platform": "facebook",
"level": "ad",
"startDate": "2026-09-01",
"endDate": "2026-09-01",
"insights": [
{
"date": "2026-09-01",
"level": "ad",
"id": "120210000000000001",
"age": "25-34",
"gender": "female",
"currency": "EUR",
"spend": 1.5,
"impressions": 300
},
{
"date": "2026-09-01",
"level": "ad",
"id": "120210000000000001",
"age": "25-34",
"gender": "male",
"currency": "EUR",
"spend": 1,
"impressions": 200
}
],
"count": 2,
"nextCursor": null
}
{
"action": "ads",
"status": "error",
"code": 400,
"message": "The ad is not found or not authorized."
}
獲取您的廣告活動或廣告的即時 Facebook 廣告表現，每天一列。
選擇您需要的指標，依年齡、性別、國家/地區或版位進行細分，並可分頁瀏覽較長的日期範圍。
Facebook 會報告此表中的所有指標。唯一的例外：對於帶有
- 數據會在您呼叫時即時從 Meta 讀取，而非來自每晚建立的副本。
- 請使用 歷史記錄 查看我們計費的支出。請使用洞察報告進行報表 與分析。
- 所有金額均以廣告帳戶的貨幣表示，並於每一列的
currency中返回。 - 廣告活動必須是透過 Ayrshare 為此個人檔案建立的。透過 Ayrshare 為其他個人檔案建立的廣告會被拒絕。 其他廣告 ID 會使用此個人檔案所連結的 Meta 帳戶讀取，因此 Meta 只會返回該帳戶可檢視的廣告。
- 每個請求僅涵蓋一個廣告帳戶。來自多個廣告帳戶的 ID 會返回代碼
101，多個 Ayrshare 沒有記錄的廣告 ID 也是如此。請逐一請求這些 ID。
請求頭參數
查詢參數
string
必填
每一列所報告的對象：
campaign 或 ad。目前尚不支援 adSet，傳送時會返回代碼 101。string
以逗號分隔的廣告活動或廣告 ID，最多 50 個。
level=campaign 時為必填。使用 level=ad 時，您可以省略 ids，改為傳送 accountId。這會報告您透過 Ayrshare 為此個人檔案在該廣告帳戶中
建立的廣告，而非該帳戶中的所有廣告。最多適用於 50 個此類廣告。若超過此數量，請傳送其 ID，或依廣告活動進行報告。
若找不到任何廣告，報告將為空。string
廣告帳戶 ID，可包含或不包含
act_ 前綴（1234567890 或 act_1234567890）。使用 level=ad 且省略 ids 時為必填。string
以逗號分隔的細分維度：
age、gender、country、placement。每天會依每個值各產生一列，使用 age,gender
時則依每種組合各產生一列。請一次傳送一個細分維度，或傳送 age,gender；Meta 會拒絕其他組合（例如
age,country），因此這些組合會返回代碼 101。string
預設值:"30 天前"
第一天，格式為
YYYY-MM-DD。最早可為 37 個月前。string
預設值:"今天"
最後一天，格式為
YYYY-MM-DD。string
上一個回應中的
nextCursor，用於獲取下一頁。指標
| 指標 | 類型 | 說明 |
|---|---|---|
spend | number | 支出金額 |
impressions | number | 廣告的顯示次數 |
reach | number | 至少看過一次廣告的人數 |
clicks | number | 點擊次數 |
cpm | number 或 null | 每 1,000 次曝光的費用 |
cpc | number 或 null | 每次點擊的費用。沒有點擊的日子為 null |
ctr | number 或 null | 點擊率，以百分比表示 |
actions | array | Meta 統計的每種動作類型及其次數 |
conversionValue | number | 購買總價值 |
breakdowns 且開始日期早於 13 個月前的報告，Meta 不會報告 reach，
因此這些列中會省略 reach。在不報告某項指標的社群網路上，該指標會從列中省略，而不是以 0 返回，
且請求該指標會返回代碼 101。
Meta 會將部分動作計入多種類型，因此請勿將
actions 的值相加。例如，omni_purchase 已包含 purchase。
conversionValue 中每筆購買只計算一次。分頁
每個回應最多返回 500 列。若還有更多資料，則會設定nextCursor。將 cursor 設為該值並再次傳送相同的請求，
即可獲取下一頁。在最後一頁，nextCursor 為 null。
錯誤
| 代碼 | 發生情況 |
|---|---|
101 | 缺少參數或參數錯誤、不支援某個細分維度或指標、傳送了 level=adSet、startDate 早於 37 個月前、傳送了超過 50 個 ID、ID 分屬多個廣告帳戶，或 Meta 拒絕該細分維度組合 |
400 | 廣告活動或廣告不屬於您，或 accountId 不是 Ayrshare 為您所傳送的 ID 所記錄的廣告帳戶。對於沒有 Ayrshare 記錄的廣告，不會檢查 accountId，並會單獨讀取該廣告 |
370 | Meta 無法返回洞察報告。請再試一次 |
curl \
-H "Authorization: Bearer API_KEY" \
-X GET "https://api.ayrshare.com/api/ads/facebook/insights?level=campaign&ids=120200000000000001&startDate=2026-09-01&endDate=2026-09-02"
const API_KEY = "API_KEY";
const params = new URLSearchParams({
level: "campaign",
ids: "120200000000000001",
startDate: "2026-09-01",
endDate: "2026-09-02",
});
fetch(`https://api.ayrshare.com/api/ads/facebook/insights?${params}`, {
method: "GET",
headers: { Authorization: `Bearer ${API_KEY}` },
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
import requests
headers = {'Authorization': 'Bearer API_KEY'}
params = {
'level': 'campaign',
'ids': '120200000000000001',
'startDate': '2026-09-01',
'endDate': '2026-09-02',
}
r = requests.get('https://api.ayrshare.com/api/ads/facebook/insights', headers=headers, params=params)
print(r.json())
{
"status": "success",
"platform": "facebook",
"level": "campaign",
"startDate": "2026-09-01",
"endDate": "2026-09-02",
"insights": [
{
"date": "2026-09-01",
"level": "campaign",
"id": "120200000000000001",
"currency": "USD",
"spend": 12.34,
"impressions": 4000,
"reach": 3100,
"clicks": 80,
"cpm": 3.085,
"cpc": 0.15425,
"ctr": 2,
"actions": [
{ "type": "link_click", "value": 75 },
{ "type": "omni_purchase", "value": 3 }
],
"conversionValue": 89.97
}
],
"count": 1,
"nextCursor": null
}
{
"status": "success",
"platform": "facebook",
"level": "ad",
"startDate": "2026-09-01",
"endDate": "2026-09-01",
"insights": [
{
"date": "2026-09-01",
"level": "ad",
"id": "120210000000000001",
"age": "25-34",
"gender": "female",
"currency": "EUR",
"spend": 1.5,
"impressions": 300
},
{
"date": "2026-09-01",
"level": "ad",
"id": "120210000000000001",
"age": "25-34",
"gender": "male",
"currency": "EUR",
"spend": 1,
"impressions": 200
}
],
"count": 2,
"nextCursor": null
}
{
"action": "ads",
"status": "error",
"code": 400,
"message": "The ad is not found or not authorized."
}