History

Get Historical Daily Facebook Ad Spend & Analytics

Available on Premium, Business, Enterprise plans.

Retrieve detailed daily ad spend and performance metrics for your Facebook ads. This endpoint provides comprehensive analytics on your ads with daily breakdowns, goal-specific performance, and aggregated metrics.

The dailySpend array contains historical daily spend and performance metrics for each ad. The data is as of 8 AM EST. If real-time spend data is needed or spend has not yet occurred, please use the ads endpoint.

The ad will NOT be returned if no spend data is available or spend has not yet occurred.

• Metrics are calculated from Facebook’s reporting API and may have slight delays (up to 24 hours).

• The byGoalType and byGoalTitle sections group performance metrics by goal objectives.
• Use either adId or postId filters to narrow results to specific campaigns.
• All monetary values are in the ad account’s currency (typically USD).
• The goalPerformance section highlights your best-performing ad objectives.

This endpoint only returns Facebook ads created via the Boost Post endpoint. Ads created in Facebook Ads Manager or other third-party tools are not returned.

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

Filter results to a specific account ID.

adId · string

Filter results to a specific ad ID.

postId · string

Filter results to ads associated with a specific Ayrshare post ID.

fbPostId · string

Filter results to ads associated with a specific Facebook social post ID.

limit · number · default: 25

Retrieve a maximum of limit ads. Maximum is 500.

startDate · string · default: "30 days ago"

Start date for the reporting period in ISO 8601 format (default: 30 days ago)

endDate · string · default: "today"

End date for the reporting period in ISO 8601 format (default: today)

cURL

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

200: Success No Param

{
    "status": "success",
    "history": [
        {
            "adId": "6683876017501",
            "adName": "API Post 1 - DE6gpw8kxlonHy6eb7L1 - 2025-03-30T17:11:26",
            "budgetDaily": 4,
            "budgetType": "daily",
            "deliveryStatus": "ACTIVE",
            "goal": {
                "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.",
                "title": "Get More Engagement",
                "type": "engagement"
            },
            "isActive": true,
            "isComplete": false,
            "metrics": {
                "clicks": 3,
                "impressions": 1035,
                "reach": 1026,
                "frequency": 0,
                "ctr": 0,
                "cpm": 1.53,
                "cpp": 1.54,
                "cpc": 0
            },
            "network": "facebook",
            "postId": "DE6gpw8kxlonHy6eb7L1",
            "spend": 1.58,
            "spendDate": "2025-04-02T00:00:00.000Z",
            "status": "ACTIVE"
        },
        {
            "adId": "120218167147110411",
            "adName": "API Post 2 - DE6gpw8kxlonHy6eb7L1 - 2025-03-30T16:41:15",
            "budgetDaily": 4,
            "budgetType": "daily",
            "deliveryStatus": "ACTIVE",
            "goal": {
                "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.",
                "title": "Get More Engagement",
                "type": "engagement"
            },
            "isActive": true,
            "isComplete": false,
            "metrics": {
                "clicks": 4,
                "impressions": 1036,
                "reach": 1011,
                "frequency": 0,
                "ctr": 0,
                "cpm": 1.61,
                "cpp": 1.65,
                "cpc": 0
            },
            "network": "facebook",
            "postId": "DE6gpw8kxlonHy6eb7L1",
            "spend": 1.67,
            "spendDate": "2025-04-02T00:00:00.000Z",
            "status": "ACTIVE"
        }
    ],
    "dateRange": {
        "start": "2025-02-24T20:02:34.613Z",
        "end": "2025-03-26T20:02:34.613Z",
        "postId": "eSNkaAiFZVin6wm6f"
    },
    "metrics": {
        "totalSpend": 3.25,
        "totalClicks": 7,
        "totalImpressions": 2071,
        "totalReach": 2052,
        "averageCTR": 0.1,
        "averageFrequency": 0,
        "cpm": 0.79,
        "cpp": 0.85,
        "cpc": 0.2,
        "costPerResult": 1.2,
        "byGoalType": {
            "engagement": {
                "spend": 7.62,
                "impressions": 9332,
                "clicks": 0,
                "reach": 8502,
                "count": 8,
                "ctr": 0,
                "cpm": 0.8165452207458208,
                "cpp": 0.8962597035991532,
                "cpc": 0
            }
        },
        "byGoalTitle": {
            "Get More Engagement": {
                "spend": 3.25,
                "impressions": 2071,
                "clicks": 7,
                "reach": 2052,
                "count": 1,
                "type": "engagement",
                "ctr": 0.1,
                "cpm": 0.79,
                "cpp": 0.85,
                "cpc": 0.2
            }
        },
        "goalPerformance": {
            "bestPerformingGoalType": {
                "type": "engagement",
                "clicks": 7,
                "spend": 3.25,
                "ctr": 0.1
            },
            "mostEfficientGoalType": {
                "type": "engagement",
                "cpc": 0.2,
                "spend": 3.25
            }
        },
        "count": 2,
        "firstDay": "2025-03-17T00:00:00.000Z",
        "lastDay": "2025-03-23T00:00:00.000Z"
    }
}