Skip to main content
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"
    }
}

Documentation Index

Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

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