> ## 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>
  Отримайте всі оголошення за ID облікового запису.

  Обов'язковий, якщо `adId`, `fbPostId` або `postId` не задано.
</ParamField>

<ParamField query="adId" type="string" required>
  Отримайте оголошення за ID оголошення.

  Обов'язковий, якщо `accountId`, `fbPostId` або `postId` не задано.
</ParamField>

<ParamField query="fbPostId" type="string" required>
  Отримайте оголошення за [ID соціального допису 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>
  Отримайте оголошення за [post ID](/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: Success with Ad ID 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: Success with Account ID 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: Submitted ads retrieval error theme={"system"}
  {
    "action": "get ads",
    "status": "error",
    "code": 370,
    "message": "Error getting ads. Please try again or contact us if the issue persists."
  }
  ```
</ResponseExample>