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

# Insights

> Lấy Insights Quảng cáo Instagram Hàng ngày Theo Thời gian Thực theo Chiến dịch, Nhóm quảng cáo hoặc Quảng cáo

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

Lấy hiệu suất quảng cáo Instagram theo thời gian thực, mỗi ngày một hàng, cho các chiến dịch, nhóm quảng cáo hoặc quảng cáo của bạn.
Chọn các chỉ số bạn muốn, phân tách chúng theo độ tuổi, giới tính, quốc gia hoặc vị trí hiển thị, và phân trang qua các khoảng thời gian dài.

<ul className="custom-bullets">
  <li>Số liệu được đọc từ Meta tại thời điểm bạn gọi, không phải từ bản sao được tạo mỗi đêm.</li>

  <li>
    Sử dụng [Lịch sử](/docs/apis/ads/instagram/get-ad-history) cho chi phí mà chúng tôi tính phí. Sử dụng Insights cho báo cáo
    và phân tích.
  </li>

  <li>Tất cả các giá trị tiền tệ đều tính theo đơn vị tiền tệ của tài khoản quảng cáo, được trả về trong `currency` trên mỗi hàng.</li>

  <li>
    Các chiến dịch phải được tạo thông qua Ayrshare cho profile này, và các nhóm quảng cáo phải nằm trong
    một chiến dịch như vậy. Một quảng cáo được tạo thông qua
    Ayrshare cho một profile khác sẽ bị từ chối. Các ad id khác được đọc bằng tài khoản Meta được liên kết
    với profile này, vì vậy Meta chỉ trả về những quảng cáo mà tài khoản đó có thể xem.
  </li>

  <li>
    Mỗi request chỉ bao gồm một tài khoản quảng cáo. Các id từ nhiều tài khoản quảng cáo sẽ trả về mã `101`, và điều tương tự
    cũng xảy ra với nhiều ad id mà Ayrshare không có bản ghi. Hãy yêu cầu từng id một.
  </li>
</ul>

## Tham số Header

<HeaderAPI />

## Tham số Query

<ParamField query="level" type="string" required>
  Đối tượng mà mỗi hàng báo cáo: `campaign`, `adSet` hoặc `ad`.
</ParamField>

<ParamField query="ids" type="string">
  Các campaign id, ad set id hoặc ad id phân tách bằng dấu phẩy, tối đa 50. Bắt buộc với `level=campaign` và
  `level=adSet`.

  Với `level=ad`, bạn có thể bỏ qua `ids` và gửi `accountId` thay thế. Khi đó báo cáo sẽ bao gồm các quảng cáo
  bạn đã tạo thông qua Ayrshare cho profile này trong tài khoản quảng cáo đó, chứ không phải mọi quảng cáo trong tài khoản. Cách này hoạt động
  với tối đa 50 quảng cáo như vậy. Nếu nhiều hơn, hãy gửi id của chúng hoặc báo cáo theo chiến dịch. Nếu không tìm thấy quảng cáo nào,
  báo cáo sẽ trống.
</ParamField>

<ParamField query="accountId" type="string">
  ID tài khoản quảng cáo, có hoặc không có tiền tố `act_` (`1234567890` hoặc `act_1234567890`).

  Bắt buộc với `level=ad` khi bỏ qua `ids`.
</ParamField>

<ParamField query="metrics" type="string">
  Các chỉ số cần trả về, phân tách bằng dấu phẩy. Bỏ qua tham số này để nhận tất cả. Xem [Chỉ số](#metrics).
</ParamField>

<ParamField query="breakdowns" type="string">
  Các breakdown phân tách bằng dấu phẩy: `age`, `gender`, `country`, `placement`. Khi đó mỗi ngày sẽ có một hàng cho mỗi
  giá trị, hoặc cho mỗi tổ hợp khi dùng `age,gender`. Hãy gửi từng breakdown một, hoặc `age,gender`; Meta
  từ chối các kết hợp khác (chẳng hạn `age,country`), vì vậy chúng sẽ trả về mã `101`.
</ParamField>

<ParamField query="startDate" type="string" default="30 ngày trước">
  Ngày đầu tiên, theo định dạng `YYYY-MM-DD`. Có thể lùi xa tối đa 37 tháng.
</ParamField>

<ParamField query="endDate" type="string" default="hôm nay">
  Ngày cuối cùng, theo định dạng `YYYY-MM-DD`.
</ParamField>

<ParamField query="cursor" type="string">
  Giá trị `nextCursor` từ phản hồi trước đó, để lấy trang tiếp theo.
</ParamField>

<h2 id="metrics">
  Chỉ số
</h2>

| Chỉ số | Kiểu | Ý nghĩa |
| - | - | - |
| `spend` | number | Số tiền đã chi |
| `impressions` | number | Số lần quảng cáo được hiển thị |
| `reach` | number | Số người đã xem quảng cáo ít nhất một lần |
| `clicks` | number | Số lượt nhấp |
| `cpm` | number hoặc `null` | Chi phí cho mỗi 1.000 lượt hiển thị |
| `cpc` | number hoặc `null` | Chi phí cho mỗi lượt nhấp. `null` vào ngày không có lượt nhấp |
| `ctr` | number hoặc `null` | Tỷ lệ nhấp, tính theo phần trăm |
| `actions` | array | Mỗi loại hành động mà Meta đã ghi nhận, kèm theo số lượng |
| `conversionValue` | number | Tổng giá trị các giao dịch mua |

Instagram báo cáo mọi chỉ số trong bảng này. Một ngoại lệ: Meta không báo cáo `reach` cho báo cáo có
`breakdowns` bắt đầu từ hơn 13 tháng trước, vì vậy `reach` bị bỏ khỏi các hàng đó. Trên các mạng không báo cáo một chỉ số, chỉ số đó sẽ bị bỏ
khỏi các hàng thay vì được trả về là `0`, và việc yêu cầu chỉ số đó sẽ trả về mã `101`.

<Note>
  Meta ghi nhận một số hành động dưới nhiều loại, vì vậy đừng cộng dồn các giá trị `actions`. Ví
  dụ, `omni_purchase` đã bao gồm `purchase`. `conversionValue` chỉ tính mỗi giao dịch mua một lần.
</Note>

<h2 id="paging">
  Phân trang
</h2>

Mỗi phản hồi trả về tối đa 500 hàng. Nếu còn nhiều hơn, `nextCursor` sẽ được đặt. Gửi lại cùng request đó
với `cursor` được đặt thành giá trị này để lấy trang tiếp theo. Ở trang cuối cùng, `nextCursor` là `null`.

<h2 id="errors">
  Lỗi
</h2>

| Mã | Khi nào |
| - | - |
| `101` | Thiếu tham số hoặc tham số sai, breakdown hoặc chỉ số không được hỗ trợ, `startDate` cách đây hơn 37 tháng, gửi hơn 50 id, các id thuộc nhiều tài khoản quảng cáo, hoặc Meta từ chối kết hợp breakdown |
| `400` | Chiến dịch, nhóm quảng cáo hoặc quảng cáo không thuộc về bạn, hoặc `accountId` không phải là tài khoản quảng cáo mà Ayrshare ghi nhận cho các id bạn đã gửi. Đối với nhóm quảng cáo, `accountId` cũng phải là tài khoản quảng cáo mà Meta báo cáo cho nhóm quảng cáo đó. Đối với quảng cáo không có bản ghi trong Ayrshare, `accountId` không được kiểm tra và quảng cáo được đọc riêng |
| `370` | Meta không thể trả về insights. Hãy thử lại |

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