> ## 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.

# 洞察報告

> 依廣告活動或廣告獲取即時的每日 Instagram 廣告洞察報告

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} />

獲取您的廣告活動或廣告的即時 Instagram 廣告表現，每天一列。
選擇您需要的指標，依年齡、性別、國家/地區或版位進行細分，並可分頁瀏覽較長的日期範圍。

<ul className="custom-bullets">
  <li>數據會在您呼叫時即時從 Meta 讀取，而非來自每晚建立的副本。</li>

  <li>
    請使用 [歷史記錄](/docs/apis/ads/instagram/get-ad-history) 查看我們計費的支出。請使用洞察報告進行報表
    與分析。
  </li>

  <li>所有金額均以廣告帳戶的貨幣表示，並於每一列的 `currency` 中返回。</li>

  <li>
    廣告活動必須是透過 Ayrshare 為此個人檔案建立的。透過 Ayrshare 為其他個人檔案建立的廣告會被拒絕。
    其他廣告 ID 會使用此個人檔案所連結的 Meta 帳戶讀取，因此 Meta 只會返回該帳戶可檢視的廣告。
  </li>

  <li>
    每個請求僅涵蓋一個廣告帳戶。來自多個廣告帳戶的 ID 會返回代碼 `101`，多個 Ayrshare 沒有記錄的廣告 ID
    也是如此。請逐一請求這些 ID。
  </li>
</ul>

## 請求頭參數

<HeaderAPI />

## 查詢參數

<ParamField query="level" type="string" required>
  每一列所報告的對象：`campaign` 或 `ad`。

  目前尚不支援 `adSet`，傳送時會返回代碼 `101`。
</ParamField>

<ParamField query="ids" type="string">
  以逗號分隔的廣告活動或廣告 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`。每天會依每個值各產生一列，使用 `age,gender`
  時則依每種組合各產生一列。請一次傳送一個細分維度，或傳送 `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 | 至少看過一次廣告的人數 |
| `clicks` | number | 點擊次數 |
| `cpm` | number 或 `null` | 每 1,000 次曝光的費用 |
| `cpc` | number 或 `null` | 每次點擊的費用。沒有點擊的日子為 `null` |
| `ctr` | number 或 `null` | 點擊率，以百分比表示 |
| `actions` | array | Meta 統計的每種動作類型及其次數 |
| `conversionValue` | number | 購買總價值 |

Instagram 會報告此表中的所有指標。唯一的例外：對於帶有 `breakdowns` 且開始日期早於 13 個月前的報告，Meta 不會報告 `reach`，
因此這些列中會省略 `reach`。在不報告某項指標的社群網路上，該指標會從列中省略，而不是以 `0` 返回，
且請求該指標會返回代碼 `101`。

<Note>
  Meta 會將部分動作計入多種類型，因此請勿將 `actions` 的值相加。例如，`omni_purchase` 已包含 `purchase`。
  `conversionValue` 中每筆購買只計算一次。
</Note>

## 分頁

每個回應最多返回 500 列。若還有更多資料，則會設定 `nextCursor`。將 `cursor` 設為該值並再次傳送相同的請求，
即可獲取下一頁。在最後一頁，`nextCursor` 為 `null`。

## 錯誤

| 代碼 | 發生情況 |
| - | - |
| `101` | 缺少參數或參數錯誤、不支援某個細分維度或指標、傳送了 `level=adSet`、`startDate` 早於 37 個月前、傳送了超過 50 個 ID、ID 分屬多個廣告帳戶，或 Meta 拒絕該細分維度組合 |
| `400` | 廣告活動或廣告不屬於您，或 `accountId` 不是 Ayrshare 為您所傳送的 ID 所記錄的廣告帳戶。對於沒有 Ayrshare 記錄的廣告，不會檢查 `accountId`，並會單獨讀取該廣告 |
| `370` | Meta 無法返回洞察報告。請再試一次 |

<RequestExample>
  ```bash cURL theme={"system"}
  curl \
  -H "Authorization: Bearer API_KEY" \
  -X GET "https://api.ayrshare.com/api/ads/instagram/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/instagram/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/instagram/insights', headers=headers, params=params)

  print(r.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200: Success theme={"system"}
  {
    "status": "success",
    "platform": "instagram",
    "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": "instagram",
    "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.