Boosted Ads

GEThttps://api.acme.com/api/ads/facebook/ads

Available on Premium, Business, Enterprise plans.

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

Authorizationstringrequired

API Key of the Primary Profile.

Format: Authorization: Bearer API_KEY

Profile-Keystring

Profile Key of a User Profile.

Format: Profile-Key: PROFILE_KEY

Query Parameters

accountIdnumberrequired

Retrieve all ads under the account ID.

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

adIdstringrequired

Retrieve an ad with the ad ID.

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

fbPostIdstringrequired

Retrieve ads with the Facebook social post ID.

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

limitnumberdefault: 25

Retrieve a maximum of limit ads. Maximum is 500.

postIdstringrequired

Retrieve ads with the ACME post ID.

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

statusstringdefault: all

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

active
paused
deleted
archived

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

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