> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# インサイト

> キャンペーンまたは広告ごとのFacebook広告の日次インサイトをリアルタイムで取得

export const PlansAvailable = ({plans = [], maxPackRequired}) => {
  let displayPlans = plans;
  if (plans && plans.length === 1) {
    const lowerCasePlan = plans[0].toLowerCase();
    if (lowerCasePlan === "business") {
      displayPlans = ["Launch", "Business", "Enterprise"];
    } else if (lowerCasePlan === "premium") {
      displayPlans = ["Premium", "Launch", "Business", "Enterprise"];
    }
  }
  return <Note>
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.

{maxPackRequired && <span onClick={() => window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
 <span className="px-1.5 py-0.5 rounded text-sm" style={{
    backgroundColor: '#C264B6',
    color: 'white',
    fontSize: '12px'
  }}>
   Max Pack required
 </span>
</span>}
</Note>;
};

export const HeaderAPI = ({noProfileKey, profileKeyRequired}) => <>
    <ParamField header="Authorization" type="string" required>
      <a href="/docs/apis/overview#authorization">API Key</a> of the Primary Profile.
      <br />
      <br />
      Format: <code>Authorization: Bearer API_KEY</code>
    </ParamField>
    {!noProfileKey && (profileKeyRequired ? <ParamField header="Profile-Key" type="string" required>
          <a href="/docs/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField> : <ParamField header="Profile-Key" type="string">
          <a href="/docs/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField>)}
  </>;

<PlansAvailable plans={["premium"]} maxPackRequired={false} />

キャンペーンまたは広告について、Facebook広告のパフォーマンスを1日1行でリアルタイムに取得します。必要な指標を選択し、年齢、性別、国、または配置で分割し、長い期間はページングで取得できます。

<ul className="custom-bullets">
  <li>数値は夜間に作成されたコピーではなく、呼び出し時にMetaから読み取られます。</li>

  <li>
    請求対象の出稿費用には[履歴](/docs/apis/ads/facebook/get-ad-history)を使用してください。インサイトはレポーティングと分析に使用してください。
  </li>

  <li>すべての金額は広告アカウントの通貨で表され、各行の`currency`で返されます。</li>

  <li>
    キャンペーンは、このプロフィール用にAyrshare経由で作成されたものである必要があります。別のプロフィール用にAyrshare経由で作成された広告は拒否されます。それ以外の広告IDはこのプロフィールにリンクされたMeta
    アカウントで読み取られるため、Metaはそのアカウントが閲覧できる広告のみを返します。
  </li>

  <li>
    1回のリクエストで対象となる広告アカウントは1つです。複数の広告アカウントのIDを指定するとコード`101`が返され、Ayrshareに記録のない複数の広告IDを指定した場合も同様です。それらは1つずつリクエストしてください。
  </li>
</ul>

## ヘッダーパラメータ

<HeaderAPI />

## クエリパラメータ

<ParamField query="level" type="string" required>
  各行のレポート対象: `campaign`または`ad`。

  `adSet`はまだサポートされておらず、コード`101`が返されます。
</ParamField>

<ParamField query="ids" type="string">
  カンマ区切りのキャンペーンIDまたは広告ID(最大50件)。`level=campaign`の場合は必須です。

  `level=ad`の場合は、`ids`を省略して代わりに`accountId`を送信できます。この場合、その広告アカウント内のすべての広告ではなく、このプロフィール用にAyrshare経由で作成した広告についてレポートします。対象となる広告は最大50件までです。それ以上の場合は、広告IDを送信するか、キャンペーン単位でレポートしてください。該当する広告が見つからない場合、レポートは空になります。
</ParamField>

<ParamField query="accountId" type="string">
  広告アカウントID。`act_`プレフィックスの有無は問いません(`1234567890`または`act_1234567890`)。

  `level=ad`で`ids`を省略する場合は必須です。
</ParamField>

<ParamField query="metrics" type="string">
  返す指標をカンマ区切りで指定します。省略するとすべての指標が返されます。[指標](#metrics)を参照してください。
</ParamField>

<ParamField query="breakdowns" type="string">
  カンマ区切りの内訳: `age`、`gender`、`country`、`placement`。各日について値ごとに1行、`age,gender`の場合は組み合わせごとに1行が返されます。内訳は1つずつ、または`age,gender`で送信してください。Metaはそれ以外の組み合わせ(`age,country`など)を拒否するため、コード`101`が返されます。
</ParamField>

<ParamField query="startDate" type="string" default="30日前">
  開始日(`YYYY-MM-DD`形式)。最大37か月前まで指定できます。
</ParamField>

<ParamField query="endDate" type="string" default="今日">
  終了日(`YYYY-MM-DD`形式)。
</ParamField>

<ParamField query="cursor" type="string">
  次のページを取得するための、前回のレスポンスの`nextCursor`。
</ParamField>

<h2 id="metrics">
  指標
</h2>

| 指標 | 型 | 意味 |
| - | - | - |
| `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 | 購入の合計金額 |

Facebookはこの表のすべての指標をレポートします。例外が1つあります: `breakdowns`を指定し、開始日が13か月より前のレポートでは、Metaが`reach`をレポートしないため、それらの行から`reach`は除外されます。指標をレポートしないネットワークでは、その指標は`0`として返されるのではなく行から除外され、その指標をリクエストするとコード`101`が返されます。

<Note>
  Metaは一部のアクションを複数のタイプでカウントするため、`actions`の値を合算しないでください。たとえば、`omni_purchase`にはすでに`purchase`が含まれています。`conversionValue`は各購入を1回のみカウントします。
</Note>

## ページング

各レスポンスは最大500行を返します。さらに行がある場合は`nextCursor`が設定されます。次のページを取得するには、`cursor`にその値を設定して同じリクエストを再度送信してください。最後のページでは`nextCursor`は`null`になります。

## エラー

| コード | 発生条件 |
| - | - |
| `101` | パラメータが不足しているか誤っている、内訳または指標がサポートされていない、`level=adSet`が送信された、`startDate`が37か月より前である、50件を超えるIDが送信された、IDが複数の広告アカウントにまたがっている、またはMetaが内訳の組み合わせを拒否した |
| `400` | キャンペーンまたは広告がお客様のものではない、または`accountId`が、送信したIDについてAyrshareが記録している広告アカウントと一致しない。Ayrshareに記録のない広告の場合、`accountId`はチェックされず、広告は単独で読み取られます |
| `370` | Metaがインサイトを返せませんでした。再度お試しください |

<RequestExample>
  ```bash cURL theme={"system"}
  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"
  ```

  ```javascript JavaScript theme={"system"}
  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);
  ```

  ```python Python theme={"system"}
  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())
  ```
</RequestExample>

<ResponseExample>
  ```json 200: Success theme={"system"}
  {
    "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
  }
  ```

  ```json 200: Breakdowns theme={"system"}
  {
    "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
  }
  ```

  ```json 400: Not Yours theme={"system"}
  {
    "action": "ads",
    "status": "error",
    "code": 400,
    "message": "The ad is not found or not authorized."
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.