Boosted Ads

Retrieve boosted Facebook ads by account, ad, or post ID, with status, Meta review results, current spend, real-time metrics, and shareable preview links.

GET /ads/facebook/ads

cURL

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

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",
                "review": {
                    "reasons": [],
                    "status": "approved"
                },
                "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
}

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.

• review is Meta’s review of the ad: status is pending while Meta reviews it, rejected when Meta disapproved it or left policy feedback on it, and approved when the ad is active or pre-approved. reasons holds Meta’s explanations, or the policy’s name when Meta gives no text, and is empty when there is no feedback. review is null when neither the ad’s status nor any feedback shows the review, for example an ad paused before review.

• 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 · string · required

Retrieve all ads under the account ID.

The ad account id, with or without the act_ prefix (1234567890 or act_1234567890).

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 300; higher values are capped at 300.

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

An ad boosted with a callToAction carries that object back on ad.callToAction, with type in Meta’s upper-case form. The key is omitted entirely for an ad that has no call-to-action button. A button that opens a chat also carries its destination. The examples below use the engagement goal with no button. A link button needs the traffic goal, and a chat button needs engagement or interactions. A chat button boosted with interactions is listed with the engagement goal when you filter by campaign.

cURL

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

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",
                "review": {
                    "reasons": [],
                    "status": "approved"
                },
                "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
}