GET
/
ads
/
facebook
/
ads
curl \
-H "Authorization: Bearer API_KEY" \
-X GET https://api.ayrshare.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
}
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

​
Authorization
string
required
API Key of the Primary Profile.

Format: Authorization: Bearer API_KEY
​
Profile-Key
string
Profile Key of a User Profile.

Format: Profile-Key: PROFILE_KEY

​
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 \
-H "Authorization: Bearer API_KEY" \
-X GET https://api.ayrshare.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
}