الرؤى

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"

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);

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())

{
  "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
}

{
  "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
}

{
  "action": "ads",
  "status": "error",
  "code": 400,
  "message": "The ad is not found or not authorized."
}

GET

ads

instagram

insights

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"

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);

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())

{
  "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
}

{
  "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
}

{
  "action": "ads",
  "status": "error",
  "code": 400,
  "message": "The ad is not found or not authorized."
}

احصل على أداء إعلاناتك على Instagram مباشرةً، بصف واحد لكل يوم، لحملاتك أو إعلاناتك. اختر المقاييس التي تريدها، وقسّمها حسب العمر أو الجنس أو الدولة أو موضع الظهور، وتصفّح النطاقات الزمنية الطويلة صفحةً تلو الأخرى.

تُقرأ الأرقام من Meta لحظة استدعائك، وليس من نسخة تُحدَّث كل ليلة.
استخدم السجل لمعرفة الإنفاق الذي نحتسبه في الفوترة. واستخدم الرؤى لإعداد التقارير والتحليل.
جميع القيم النقدية بعملة حساب الإعلانات، وتُعاد في الحقل currency في كل صف.
يجب أن تكون الحملات قد أُنشئت عبر Ayrshare لهذا الملف الشخصي. يُرفض الإعلان الذي أُنشئ عبر Ayrshare لملف شخصي آخر. أما معرّفات الإعلانات الأخرى فتُقرأ باستخدام حساب Meta المرتبط بهذا الملف الشخصي، لذا لا تُعيد Meta إلا الإعلانات التي يستطيع ذلك الحساب رؤيتها.
يغطي الطلب الواحد حساب إعلانات واحدًا. تُعيد المعرّفات التابعة لعدة حسابات إعلانات الرمز 101، وكذلك عدة معرّفات إعلانات لا يملك Ayrshare سجلًا لها. اطلب هذه المعرّفات واحدًا تلو الآخر.

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

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

string

مطلوب

ما يُبلغ عنه كل صف: campaign أو ad.القيمة adSet غير مدعومة بعد وتُعيد الرمز 101.

string

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

string

معرّف حساب الإعلانات، مع البادئة act_ أو بدونها (1234567890 أو act_1234567890).مطلوب مع level=ad عند حذف ids.

string

المقاييس المطلوب إرجاعها مفصولة بفواصل. احذفه للحصول عليها جميعًا. راجع المقاييس.

string

التقسيمات مفصولة بفواصل: age وgender وcountry وplacement. يصبح لكل يوم عندئذٍ صف واحد لكل قيمة، أو لكل تركيبة مع age,gender. أرسل تقسيمًا واحدًا في كل مرة، أو age,gender؛ إذ ترفض Meta التركيبات الأخرى (مثل age,country)، لذا تُعيد الرمز 101.

string

افتراضي:"قبل 30 يومًا"

اليوم الأول، بصيغة YYYY-MM-DD. يمكن أن يعود إلى ما يصل إلى 37 شهرًا مضت.

string

افتراضي:"اليوم"

اليوم الأخير، بصيغة YYYY-MM-DD.

string

قيمة nextCursor من الاستجابة السابقة، للحصول على الصفحة التالية.

المقاييس

المقياس	النوع	المعنى
`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.

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

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

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

الأخطاء

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

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"

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);

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())

{
  "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
}

{
  "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
}

{
  "action": "ads",
  "status": "error",
  "code": 400,
  "message": "The ad is not found or not authorized."
}

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

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

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

المقاييس

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

الأخطاء

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

​معاملات الاستعلام

​المقاييس

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

​الأخطاء

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

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

المقاييس

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

الأخطاء