> ## 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="/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="/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="/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>
    المقاييس هي إجماليات في الوقت الفعلي للإعلانات. إذا كنت بحاجة إلى بيانات تاريخية، فاستخدم [نقطة نهاية الحصول على
    سجل الإعلان](/apis/ads/facebook/get-ad-history).
  </li>

  <li>
    يتيح لك عنوان URL `previewLink` مشاركة الإعلان التجريبي مع زملائك، بحيث سيرون
    الإعلان لمدة 24 ساعة عبر تنسيقات Facebook المختلفة. لن تُحتسب مشاهدات زملائك للإعلان
    ضمن إنفاق إعلانك.
  </li>
</ul>

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

<HeaderAPI />

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

<ParamField query="accountId" type="number" required>
  استرجع جميع الإعلانات ضمن معرّف الحساب.

  مطلوب إذا لم يتم تعيين `adId` أو `fbPostId` أو `postId`.
</ParamField>

<ParamField query="adId" type="string" required>
  استرجع إعلانًا باستخدام معرّف الإعلان.

  مطلوب إذا لم يتم تعيين `accountId` أو `fbPostId` أو `postId`.
</ParamField>

<ParamField query="fbPostId" type="string" required>
  استرجع الإعلانات باستخدام [معرّف المنشور الاجتماعي على Facebook](/apis/overview#social-post-id).

  مطلوب إذا لم يتم تعيين `accountId` أو `adId` أو `postId`.
</ParamField>

<ParamField query="limit" type="number" default={25}>
  استرجع بحد أقصى `limit` إعلانًا. الحد الأقصى هو 500.
</ParamField>

<ParamField query="postId" type="string" required>
  استرجع الإعلانات باستخدام [معرّف منشور](/apis/overview#ayrshare-post-id) Ayrshare.

  مطلوب إذا لم يتم تعيين `accountId` أو `adId` أو `fbPostId`.
</ParamField>

<ParamField query="status" type="string" default="all">
  فلتر الإعلانات حسب حالة الإعلان. القيم الصالحة هي:

  <ul className="custom-bullets">
    <li>`active`</li>
    <li>`paused`</li>
    <li>`deleted`</li>
    <li>`archived`</li>
  </ul>
</ParamField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl \
  -H "Authorization: Bearer API_KEY" \
  -X GET https://api.ayrshare.com/api/ads/facebook/ads?adId=1234567890
  ```

  ```javascript JavaScript theme={"system"}
  const API_KEY = "API_KEY";

  fetch("https://api.ayrshare.com/api/ads/facebook/ads?adId=1234567890", {
        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'}

  r = requests.get('https://api.ayrshare.com/api/ads/facebook/ads?adId=1234567890', headers=headers)

  print(r.json())
  ```

  ```php PHP theme={"system"}
  <?php

  $apiUrl = 'https://api.ayrshare.com/api/ads/facebook/ads?adId=1234567890';
  $apiKey = 'API_KEY';  // Replace 'API_KEY' with your actual API key

  $headers = [
      'Content-Type: application/json',
      'Authorization: Bearer ' . $apiKey,
  ];

  $curl = curl_init($apiUrl);
  curl_setopt_array($curl, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => $headers
  ]);

  $response = curl_exec($curl);

  if ($response === false) {
      echo 'Curl error: ' . curl_error($curl);
  } else {
      echo json_encode(json_decode($response), JSON_PRETTY_PRINT);
  }

  curl_close($curl);

  ```

  ```csharp C# theme={"system"}
  using System;
  using System.Net.Http;
  using System.Threading.Tasks;

  namespace HistoryGETRequest_csharp
  {
  class History
  {
      static async Task Main(string[] args)
      {
          string API_KEY = "API_KEY";
          string url = "https://api.ayrshare.com/api/ads/facebook/ads?adId=1234567890";

          using (var client = new HttpClient())
          {
              client.DefaultRequestHeaders.Add("Authorization", "Bearer " + API_KEY);

              try
              {
                  var response = await client.GetStringAsync(url);
                  Console.WriteLine(response);
              }
              catch (HttpRequestException ex)
              {
                  Console.WriteLine($"Error: {ex.Message}");
              }
          }
      }
  }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200: نجاح باستخدام معرّف الإعلان theme={"system"}
  {
      "status": "success",
      "ads": [
          {
              "postId": "DE6gpw8kxlonHy6eb721",
              "ad": {
                  "accountId": "274948331",
                  "adId": "6683876017501",
                  "budgetRemaining": 0,
                  "created": "2025-03-30T10:11:34-0700",
                  "creativeId": "1033490148629541",
                  "dailyBudget": 0,
                  "deliveryStatus": "ACTIVE",
                  "endDate": "2025-04-03T22:30:00.000Z",
                  "fbPostId": "106638148652329_672633202087922",
                  "goal": {
                      "title": "Get More Engagement",
                      "description": "This goal seeks to increase engagement while ensuring that the ad reaches the maximum number of unique users. It balances visibility with engagement, showing the ad to as many different people as possible who may interact with it.",
                      "type": "engagement"
                  },
                  "isComplete": false,
                  "lifetimeBudget": 0,
                  "metrics": {
                      "spend": 9.21,
                      "impressions": 6495,
                      "reach": 6272,
                      "clicks": 3,
                      "ctr": 0.046189,
                      "cpm": 1.418014,
                      "cpp": 1.468431,
                      "frequency": 1.035555,
                      "uniqueClicks": 3,
                      "uniqueCtr": 0.047832,
                      "costPerUniqueClick": 3.07,
                      "inlineLinkClicks": 0,
                      "costPerInlineLinkClick": 0,
                      "outboundClicks": 0,
                      "costPerOutboundClick": 0,
                      "websiteCtr": [],
                      "accountCurrency": "USD",
                      "accountName": "John Doe",
                      "accountId": "274948331"
                  },
                  "name": "API Post - DE6gpw8kxlonHy6eb7L1 - 2025-03-30T17:11:26",
                  "previewLink": "https://fb.me/22Cn31wXlzhxOC1",
                  "spend": 9.21,
                  "startDate": "2025-03-30T17:11:32.000Z",
                  "status": "ACTIVE",
                  "targeting": {
                      "ageMax": 65,
                      "ageMin": 18,
                      "geoLocations": {
                          "countries": [
                              "US"
                          ],
                          "locationTypes": [
                              "home",
                              "recent"
                          ]
                      },
                      "interests": [
                          {
                              "id": "6003195554098",
                              "name": "Rhythm and blues music"
                          }
                      ]
                  }
              }
          }
      ],
      "count": 1
  }
  ```

  ```json 200: نجاح باستخدام معرّف الحساب theme={"system"}
  {
    "status": "success",
    "ads": [
      {
        "postId": "DE6gpw8kxlonHy6eb7Lo",
        "ad": {
          "accountId": "274948331",
          "adId": "6683876017501",
          "budgetRemaining": 0,
          "created": "2025-03-30T10:11:34-0700",
          "creativeId": "1033490148629541",
          "dailyBudget": 0,
          "deliveryStatus": "ACTIVE",
          "endDate": "2025-04-03T22:30:00.000Z",
          "fbPostId": "106638148652329_672633202087921",
          "goal": {
            "title": "Get More Engagement",
            "description": "This goal seeks to increase engagement while ensuring that the ad reaches the maximum number of unique users. It balances visibility with engagement, showing the ad to as many different people as possible who may interact with it.",
            "type": "engagement"
          },
          "isComplete": false,
          "lifetimeBudget": 0,
          "metrics": {
            "spend": 9.21,
            "impressions": 6495,
            "reach": 6272,
            "clicks": 3,
            "ctr": 0.046189,
            "cpm": 1.418014,
            "cpp": 1.468431,
            "frequency": 1.035555,
            "uniqueClicks": 3,
            "uniqueCtr": 0.047832,
            "costPerUniqueClick": 3.07,
            "inlineLinkClicks": 0,
            "costPerInlineLinkClick": 0,
            "outboundClicks": 0,
            "costPerOutboundClick": 0,
            "websiteCtr": [],
            "accountCurrency": "USD",
            "accountName": "John Doe",
            "accountId": "274948331"
          },
          "name": "API Post - DE6gpw8kxlonHy6eb7Lo - 2025-03-30T17:11:26",
          "previewLink": "https://fb.me/22Cn31wXlzhxOC1",
          "spend": 9.21,
          "startDate": "2025-03-30T17:11:32.000Z",
          "status": "ACTIVE",
          "targeting": {
            "ageMax": 65,
            "ageMin": 18,
            "geoLocations": {
              "countries": ["US"],
              "locationTypes": ["home", "recent"]
            },
            "interests": [
              {
                "id": "6003195554098",
                "name": "Rhythm and blues music"
              }
            ]
          }
        }
      },
      {
        "ad": {
          "accountId": "274948331",
          "adId": "6685225314301",
          "budgetRemaining": 0,
          "created": "2025-03-30T18:36:39-0700",
          "creativeId": "628434386637341",
          "dailyBudget": 0,
          "deliveryStatus": "PAUSED",
          "endDate": "2025-04-03T22:30:00.000Z",
          "fbPostId": "106638148652329_672633202087921",
          "goal": {
            "title": "Get More Engagement",
            "description": "This goal seeks to increase engagement while ensuring that the ad reaches the maximum number of unique users. It balances visibility with engagement, showing the ad to as many different people as possible who may interact with it.",
            "type": "engagement"
          },
          "isComplete": false,
          "lifetimeBudget": 0,
          "metrics": {},
          "name": "API Post 14 - 106638148652329_672633202087926 - 2025-03-31T01:36:32",
          "previewLink": "https://fb.me/2nPlTIZEpzrCnY1",
          "spend": 0,
          "startDate": "2025-03-31T01:36:37.000Z",
          "status": "PAUSED",
          "targeting": {
            "ageMax": 65,
            "ageMin": 18,
            "geoLocations": {
              "countries": ["US"],
              "locationTypes": ["home", "recent"]
            },
            "interests": [
              {
                "id": "6003195554098",
                "name": "Rhythm and blues music"
              }
            ]
          }
        }
      }
    ],
    "count": 2
  }
  ```

  ```json 400: خطأ استرجاع الإعلانات المُرسَلة theme={"system"}
  {
    "action": "get ads",
    "status": "error",
    "code": 370,
    "message": "Error getting ads. Please try again or contact us if the issue persists."
  }
  ```
</ResponseExample>