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広告のパフォーマンスを1日1行でリアルタイムに取得します。必要な指標を選択し、年齢、性別、国、または配置で分割し、長い期間はページングで取得できます。
Facebookはこの表のすべての指標をレポートします。例外が1つあります:
- 数値は夜間に作成されたコピーではなく、呼び出し時にMetaから読み取られます。
- 請求対象の出稿費用には履歴を使用してください。インサイトはレポーティングと分析に使用してください。
- すべての金額は広告アカウントの通貨で表され、各行の
currencyで返されます。 - キャンペーンは、このプロフィール用にAyrshare経由で作成されたものである必要があります。別のプロフィール用にAyrshare経由で作成された広告は拒否されます。それ以外の広告IDはこのプロフィールにリンクされたMeta アカウントで読み取られるため、Metaはそのアカウントが閲覧できる広告のみを返します。
- 1回のリクエストで対象となる広告アカウントは1つです。複数の広告アカウントのIDを指定するとコード
101が返され、Ayrshareに記録のない複数の広告IDを指定した場合も同様です。それらは1つずつリクエストしてください。
ヘッダーパラメータ
クエリパラメータ
string
必須
各行のレポート対象:
campaignまたはad。adSetはまだサポートされておらず、コード101が返されます。string
カンマ区切りのキャンペーンIDまたは広告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。各日について値ごとに1行、age,genderの場合は組み合わせごとに1行が返されます。内訳は1つずつ、またはage,genderで送信してください。Metaはそれ以外の組み合わせ(age,countryなど)を拒否するため、コード101が返されます。string
デフォルト:"30日前"
開始日(
YYYY-MM-DD形式)。最大37か月前まで指定できます。string
デフォルト:"今日"
終了日(
YYYY-MM-DD形式)。string
次のページを取得するための、前回のレスポンスの
nextCursor。指標
| 指標 | 型 | 意味 |
|---|---|---|
spend | number | 出稿費用 |
impressions | number | 広告が表示された回数 |
reach | number | 広告を1回以上見た人数 |
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は各購入を1回のみカウントします。ページング
各レスポンスは最大500行を返します。さらに行がある場合はnextCursorが設定されます。次のページを取得するには、cursorにその値を設定して同じリクエストを再度送信してください。最後のページではnextCursorはnullになります。
エラー
| コード | 発生条件 |
|---|---|
101 | パラメータが不足しているか誤っている、内訳または指標がサポートされていない、level=adSetが送信された、startDateが37か月より前である、50件を超えるIDが送信された、IDが複数の広告アカウントにまたがっている、またはMetaが内訳の組み合わせを拒否した |
400 | キャンペーンまたは広告がお客様のものではない、またはaccountIdが、送信したIDについてAyrshareが記録している広告アカウントと一致しない。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."
}