> ## 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.

# Boosted Ads

> Get boosted ads from your Facebook account

export const PlansAvailable = ({plans = [], maxPackRequired}) => {
  let displayPlans = plans;
  if (plans && plans.length === 1) {
    const lowerCasePlan = plans[0].toLowerCase();
    if (lowerCasePlan === "basic") {
      displayPlans = ["Basic", "Premium", "Business", "Enterprise"];
    } else if (lowerCasePlan === "business") {
      displayPlans = ["Business", "Enterprise"];
    } else if (lowerCasePlan === "premium") {
      displayPlans = ["Premium", "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} />

Retrieve ads that have been boosted for a specific Facebook post.

This boosted ads endpoint provides detailed information about the boosted ads, including status, current spend, performance metrics (analytics), and preview links.

<ul className="custom-bullets">
  <li>
    The metrics are real-time totals for the ads. If you need historical data, use the [get ad
    history endpoint](/apis/ads/facebook/get-ad-history).
  </li>

  <li>
    The `previewLink` URL allows you share the preview ad with your colleagues, so that they will
    see the ad for 24-hours across the various Facebook formats. Your colleagues' views of the ad
    will not be counted towards your ad spend.
  </li>
</ul>

## Header Parameters

<HeaderAPI />

## Query Parameters

<ParamField query="accountId" type="number" required>
  Retrieve all ads under the account ID.

  Required if `adId`, `fbPostId`, or `postId` is not set.
</ParamField>

<ParamField query="adId" type="string" required>
  Retrieve an ad with the ad ID.

  Required if `accountId`, `fbPostId`, or `postId` is not set.
</ParamField>

<ParamField query="fbPostId" type="string" required>
  Retrieve ads with the [Facebook social post ID](/apis/overview#social-post-id).

  Required if `accountId`, `adId`, or `postId` is not set.
</ParamField>

<ParamField query="limit" type="number" default={25}>
  Retrieve a maximum of `limit` ads. Maximum is 500.
</ParamField>

<ParamField query="postId" type="string" required>
  Retrieve ads with the Ayrshare [post ID](/apis/overview#ayrshare-post-id).

  Required if `accountId`, `adId`, or `fbPostId` is not set.
</ParamField>

<ParamField query="status" type="string" default="all">
  Filter ads by status of the ad. Valid values are:

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