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

# Anúncios impulsionados

> Obter anúncios impulsionados da sua conta do 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} />

Recupere anúncios que foram impulsionados para uma publicação específica do Facebook.

Este endpoint de anúncios impulsionados fornece informações detalhadas sobre os anúncios impulsionados, incluindo status, gasto atual, métricas de desempenho (analytics) e links de visualização.

<ul className="custom-bullets">
  <li>
    As métricas são totais em tempo real dos anúncios. Se precisar de dados históricos, use o [endpoint
    de histórico de anúncios](/apis/ads/facebook/get-ad-history).
  </li>

  <li>
    A URL `previewLink` permite compartilhar o anúncio de visualização com seus colegas, para que possam
    ver o anúncio por 24 horas nos vários formatos do Facebook. As visualizações do anúncio pelos seus colegas
    não serão contabilizadas no gasto do seu anúncio.
  </li>
</ul>

## Parâmetros de cabeçalho

<HeaderAPI />

## Parâmetros de consulta

<ParamField query="accountId" type="number" required>
  Recupera todos os anúncios sob o ID da conta.

  Obrigatório se `adId`, `fbPostId` ou `postId` não estiverem definidos.
</ParamField>

<ParamField query="adId" type="string" required>
  Recupera um anúncio pelo ID do anúncio.

  Obrigatório se `accountId`, `fbPostId` ou `postId` não estiverem definidos.
</ParamField>

<ParamField query="fbPostId" type="string" required>
  Recupera anúncios pelo [ID da publicação social do Facebook](/apis/overview#social-post-id).

  Obrigatório se `accountId`, `adId` ou `postId` não estiverem definidos.
</ParamField>

<ParamField query="limit" type="number" default={25}>
  Recupera no máximo `limit` anúncios. O máximo é 500.
</ParamField>

<ParamField query="postId" type="string" required>
  Recupera anúncios pelo [ID da publicação](/apis/overview#ayrshare-post-id) da Ayrshare.

  Obrigatório se `accountId`, `adId` ou `fbPostId` não estiverem definidos.
</ParamField>

<ParamField query="status" type="string" default="all">
  Filtra anúncios por status do anúncio. Valores válidos são:

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