> ## 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 विज्ञापन प्रदर्शन प्राप्त करें, प्रति दिन एक पंक्ति।
अपनी ज़रूरत के मेट्रिक्स चुनें, उन्हें आयु, लिंग, देश या प्लेसमेंट के अनुसार विभाजित करें, और लंबी तिथि सीमाओं में पेज-दर-पेज आगे बढ़ें।

<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>
    एक अनुरोध एक विज्ञापन खाते को कवर करता है। कई विज्ञापन खातों की ID कोड `101` लौटाती हैं, और वैसे ही
    ऐसी कई विज्ञापन ID भी जिनका Ayrshare के पास कोई रिकॉर्ड नहीं है। उन्हें एक-एक करके माँगें।
  </li>
</ul>

## हेडर पैरामीटर

<HeaderAPI />

## क्वेरी पैरामीटर

<ParamField query="level" type="string" required>
  प्रत्येक पंक्ति किस पर रिपोर्ट करती है: `campaign`, `adSet` या `ad`।
</ParamField>

<ParamField query="ids" type="string">
  अल्पविराम से अलग की गई अभियान, विज्ञापन सेट या विज्ञापन ID, अधिकतम 50। `level=campaign` और `level=adSet` के लिए आवश्यक।

  `level=ad` के साथ, आप `ids` छोड़कर उसके बजाय `accountId` भेज सकते हैं। यह उस विज्ञापन खाते में इस
  प्रोफ़ाइल के लिए Ayrshare के माध्यम से बनाए गए विज्ञापनों पर रिपोर्ट करता है, उसके हर विज्ञापन पर नहीं। यह
  ऐसे अधिकतम 50 विज्ञापनों के लिए काम करता है। इससे अधिक के लिए, उनकी ID भेजें, या अभियान के अनुसार रिपोर्ट करें। यदि
  कोई नहीं मिलता, तो रिपोर्ट खाली होती है।
</ParamField>

<ParamField query="accountId" type="string">
  विज्ञापन खाता ID, `act_` उपसर्ग के साथ या उसके बिना (`1234567890` या `act_1234567890`)।

  `ids` छोड़े जाने पर `level=ad` के साथ आवश्यक।
</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 द्वारा गिना गया प्रत्येक action प्रकार, उसकी गिनती के साथ |
| `conversionValue` | number | खरीदारियों का कुल मूल्य |

Facebook इस तालिका के हर मेट्रिक की रिपोर्ट करता है। एक अपवाद: Meta ऐसी रिपोर्ट के लिए `reach` की रिपोर्ट नहीं करता जिसमें
`breakdowns` हों और जो 13 महीने से अधिक पहले शुरू होती हो, इसलिए उन पंक्तियों से `reach` हटा दिया जाता है। जो नेटवर्क किसी मेट्रिक की रिपोर्ट नहीं करते, उन पर वह मेट्रिक
`0` के रूप में लौटाए जाने के बजाय पंक्तियों से हटा दिया जाता है, और उसे माँगने पर कोड `101` लौटता है।

<Note>
  Meta कुछ actions को एक से अधिक प्रकार के अंतर्गत गिनता है, इसलिए `actions` के मानों को आपस में न जोड़ें। उदाहरण
  के लिए, `omni_purchase` में पहले से ही `purchase` शामिल है। `conversionValue` प्रत्येक खरीदारी को एक बार गिनता है।
</Note>

<h2 id="paging">
  पेजिंग
</h2>

प्रत्येक रिस्पॉन्स अधिकतम 500 पंक्तियाँ लौटाता है। यदि और पंक्तियाँ हैं, तो `nextCursor` सेट होता है। अगला पेज पाने के लिए वही अनुरोध
दोबारा भेजें, जिसमें `cursor` को उस मान पर सेट किया गया हो। अंतिम पेज पर, `nextCursor` का मान `null` होता है।

<h2 id="errors">
  त्रुटियाँ
</h2>

| कोड | कब |
| - | - |
| `101` | कोई पैरामीटर अनुपस्थित या गलत है, कोई ब्रेकडाउन या मेट्रिक समर्थित नहीं है, `startDate` 37 महीने से अधिक पहले का है, 50 से अधिक ID भेजी गई हैं, ID एक से अधिक विज्ञापन खातों में हैं, या Meta ब्रेकडाउन संयोजन को अस्वीकार करता है |
| `400` | कोई अभियान, विज्ञापन सेट या विज्ञापन आपका नहीं है, या `accountId` वह विज्ञापन खाता नहीं है जो Ayrshare के रिकॉर्ड में आपके द्वारा भेजी गई ID के लिए दर्ज है। विज्ञापन सेट के लिए, `accountId` वह विज्ञापन खाता भी होना चाहिए जो Meta उसके लिए बताता है। जिस विज्ञापन का 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.