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

# Annonces sponsorisées

> Obtenir les annonces sponsorisées de votre compte 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} />

Récupérez les annonces qui ont été sponsorisées pour une publication Facebook spécifique.

Cet endpoint des annonces sponsorisées fournit des informations détaillées sur les annonces sponsorisées, notamment le statut, les dépenses actuelles, les indicateurs de performance (statistiques) et les liens de prévisualisation.

<ul className="custom-bullets">
  <li>
    Les indicateurs sont des totaux en temps réel pour les annonces. Si vous avez besoin de données historiques, utilisez l'[endpoint
    get ad history](/apis/ads/facebook/get-ad-history).
  </li>

  <li>
    L'URL `previewLink` vous permet de partager l'aperçu de l'annonce avec vos collègues, afin qu'ils
    puissent voir l'annonce pendant 24 heures dans les différents formats Facebook. Les vues de l'annonce par vos collègues
    ne seront pas comptabilisées dans vos dépenses publicitaires.
  </li>
</ul>

## Paramètres d'en-tête

<HeaderAPI />

## Paramètres de requête

<ParamField query="accountId" type="number" required>
  Récupérer toutes les annonces sous l'ID du compte.

  Requis si `adId`, `fbPostId` ou `postId` n'est pas défini.
</ParamField>

<ParamField query="adId" type="string" required>
  Récupérer une annonce avec l'ID de l'annonce.

  Requis si `accountId`, `fbPostId` ou `postId` n'est pas défini.
</ParamField>

<ParamField query="fbPostId" type="string" required>
  Récupérer les annonces avec l'[ID de publication sociale Facebook](/apis/overview#social-post-id).

  Requis si `accountId`, `adId` ou `postId` n'est pas défini.
</ParamField>

<ParamField query="limit" type="number" default={25}>
  Récupérer un maximum de `limit` annonces. Le maximum est 500.
</ParamField>

<ParamField query="postId" type="string" required>
  Récupérer les annonces avec l'[ID de publication](/apis/overview#ayrshare-post-id) Ayrshare.

  Requis si `accountId`, `adId` ou `fbPostId` n'est pas défini.
</ParamField>

<ParamField query="status" type="string" default="all">
  Filtrer les annonces par statut. Les valeurs valides sont :

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