> ## 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 لملف شخصي آخر. أما معرّفات الإعلانات الأخرى فتُقرأ باستخدام حساب Meta المرتبط بهذا الملف الشخصي،
    لذا لا تُعيد Meta إلا الإعلانات التي يستطيع ذلك الحساب رؤيتها.
  </li>

  <li>
    يغطي الطلب الواحد حساب إعلانات واحدًا. تُعيد المعرّفات التابعة لعدة حسابات إعلانات الرمز `101`، وكذلك
    عدة معرّفات إعلانات لا يملك Ayrshare سجلًا لها. اطلب هذه المعرّفات واحدًا تلو الآخر.
  </li>
</ul>

## معاملات الترويسة

<HeaderAPI />

## معاملات الاستعلام

<ParamField query="level" type="string" required>
  ما يُبلغ عنه كل صف: `campaign` أو `ad`.

  القيمة `adSet` غير مدعومة بعد وتُعيد الرمز `101`.
</ParamField>

<ParamField query="ids" type="string">
  معرّفات الحملات أو الإعلانات مفصولة بفواصل، بحد أقصى 50. مطلوب مع `level=campaign`.

  مع `level=ad`، يمكنك حذف `ids` وإرسال `accountId` بدلًا منه. يُعدّ هذا تقريرًا عن الإعلانات
  التي أنشأتها عبر Ayrshare لهذا الملف الشخصي في حساب الإعلانات ذلك، وليس عن كل إعلان فيه. ويعمل
  ذلك مع ما يصل إلى 50 إعلانًا من هذا النوع. لأكثر من ذلك، أرسل معرّفاتها، أو أعدّ التقرير حسب الحملة. وإذا لم يُعثر على أي إعلان، يكون
  التقرير فارغًا.
</ParamField>

<ParamField query="accountId" type="string">
  معرّف حساب الإعلانات، مع البادئة `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 عن كل مقياس في هذا الجدول. باستثناء واحد: لا تُبلغ Meta عن `reach` في تقرير يتضمن
`breakdowns` ويبدأ قبل أكثر من 13 شهرًا، لذا يُحذف `reach` من تلك الصفوف. وعلى الشبكات التي لا تُبلغ عن مقياس ما، يُحذف ذلك المقياس
من الصفوف بدلًا من إرجاعه بالقيمة `0`، ويُعيد طلبه الرمز `101`.

<Note>
  تحتسب Meta بعض الإجراءات ضمن أكثر من نوع، لذا لا تجمع قيم `actions` معًا. على
  سبيل المثال، يتضمن `omni_purchase` بالفعل `purchase`. أما `conversionValue` فيحتسب كل عملية شراء مرة واحدة.
</Note>

## ترقيم الصفحات

تُعيد كل استجابة ما يصل إلى 500 صف. إذا كان هناك المزيد، تُعيَّن قيمة `nextCursor`. أرسل الطلب نفسه
مرة أخرى مع تعيين `cursor` إلى تلك القيمة للحصول على الصفحة التالية. في الصفحة الأخيرة، تكون قيمة `nextCursor` هي `null`.

## الأخطاء

| الرمز | متى |
| - | - |
| `101` | معامل مفقود أو غير صحيح، أو تقسيم أو مقياس غير مدعوم، أو إرسال `level=adSet`، أو كون `startDate` أقدم من 37 شهرًا، أو إرسال أكثر من 50 معرّفًا، أو انتماء المعرّفات إلى أكثر من حساب إعلانات واحد، أو رفض Meta لتركيبة التقسيمات |
| `400` | حملة أو إعلان لا يخصّك، أو `accountId` ليس حساب الإعلانات المسجّل لدى Ayrshare للمعرّفات التي أرسلتها. بالنسبة للإعلان الذي لا يملك 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.