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

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