Boosted Ads

Get boosted ads from your Facebook account

GET /ads/facebook/ads

cURL

curl \
-H "Authorization: Bearer API_KEY" \
-X GET https://api.ayrshare.com/api/ads/facebook/ads?adId=1234567890

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

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

$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);

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}");
            }
        }
    }
}
}

200: Success with Ad ID

{
    "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
}

{
  "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
}

{
  "action": "get ads",
  "status": "error",
  "code": 370,
  "message": "Error getting ads. Please try again or contact us if the issue persists."
}

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.

• The metrics are real-time totals for the ads. If you need historical data, use the get ad history endpoint.

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

Header Parameters

Query Parameters

accountId · number · required

Retrieve all ads under the account ID.

Required if adId, fbPostId, or postId is not set.

adId · string · required

Retrieve an ad with the ad ID.

Required if accountId, fbPostId, or postId is not set.

fbPostId · string · required

Retrieve ads with the Facebook social post ID.

Required if accountId, adId, or postId is not set.

limit · number · default: 25

Retrieve a maximum of limit ads. Maximum is 500.

postId · string · required

Retrieve ads with the Ayrshare post ID.

Required if accountId, adId, or fbPostId is not set.

status · string · default: "all"

Filter ads by status of the ad. Valid values are:

• active
• paused
• deleted
• archived

cURL

curl \
-H "Authorization: Bearer API_KEY" \
-X GET https://api.ayrshare.com/api/ads/facebook/ads?adId=1234567890

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

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

$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);

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}");
            }
        }
    }
}
}

200: Success with Ad ID

{
    "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
}

{
  "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
}

{
  "action": "get ads",
  "status": "error",
  "code": 370,
  "message": "Error getting ads. Please try again or contact us if the issue persists."
}