History

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

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

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

accountIdnumber

Filter results to a specific account ID.

adIdstring

Filter results to a specific ad ID.

postIdstring

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

fbPostIdstring

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

limitnumberdefault: 25

Retrieve a maximum of limit ads. Maximum is 500.

startDatestringdefault: 30 days ago

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

endDatestringdefault: today

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

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

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