curl \
-H "Authorization: Bearer API_KEY" \
-X GET https://api.ayrshare.com/api/ads/facebook/history?accountId=1234567890
const API_KEY = "API_KEY";
fetch("https://api.ayrshare.com/api/ads/facebook/history?accountId=1234567890", {
method: "GET",
headers: {
"Authorization": `Bearer ${API_KEY}`
}
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
import requests
headers = {'Authorization': 'Bearer API_KEY'}
r = requests.get('https://api.ayrshare.com/api/ads/facebook/history', headers=headers)
print(r.json())
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.ayrshare.com/api/ads/facebook/history",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer API_KEY"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error: " . $err;
} else {
echo $response;
}
?>
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
static async Task Main(string[] args)
{
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer API_KEY");
var response = await client.GetAsync("https://api.ayrshare.com/api/ads/facebook/history");
var content = await response.Content.ReadAsStringAsync();
Console.WriteLine(content);
}
}
package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
client := &http.Client{}
req, _ := http.NewRequest("GET", "https://api.ayrshare.com/api/ads/facebook/history", nil)
req.Header.Add("Authorization", "Bearer API_KEY")
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error:", err)
return
}
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
fmt.Println(string(body))
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class GetAdSpend {
public static void main(String[] args) {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.ayrshare.com/api/ads/facebook/history"))
.header("Authorization", "Bearer API_KEY")
.GET()
.build();
try {
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
} catch (Exception e) {
e.printStackTrace();
}
}
}
require 'net/http'
require 'json'
require 'uri'
uri = URI.parse('https://api.ayrshare.com/api/ads/facebook/history')
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer API_KEY'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(request)
end
puts response.body
{
"status": "success",
"history": [
{
"adId": "6683876017501",
"adName": "API Post 1 - DE6gpw8kxlonHy6eb7L1 - 2025-03-30T17:11:26",
"budgetDaily": 4,
"budgetType": "daily",
"currency": "USD",
"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": 1.01,
"ctr": 0,
"cpm": 1.53,
"cpp": 1.54,
"cpc": 0
},
"network": "facebook",
"postId": "DE6gpw8kxlonHy6eb7L1",
"spend": 1.58,
"spendDate": "2025-04-02T00:00:00.000Z",
"spendUsd": 1.58,
"status": "ACTIVE"
},
{
"adId": "120218167147110411",
"adName": "API Post 2 - DE6gpw8kxlonHy6eb7L1 - 2025-03-30T16:41:15",
"budgetDaily": 4,
"budgetType": "daily",
"currency": "USD",
"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": 1.02,
"ctr": 0,
"cpm": 1.61,
"cpp": 1.65,
"cpc": 0
},
"network": "facebook",
"postId": "DE6gpw8kxlonHy6eb7L1",
"spend": 1.67,
"spendDate": "2025-04-02T00:00:00.000Z",
"spendUsd": 1.67,
"status": "ACTIVE"
}
],
"dateRange": {
"start": "2025-02-24T20:02:34.613Z",
"end": "2025-03-26T20:02:34.613Z",
"postId": "eSNkaAiFZVin6wm6f"
},
"metrics": {
"totalSpend": 3.25,
"totalSpendByCurrency": { "USD": 3.25 },
"unconvertedRows": 0,
"totalClicks": 7,
"totalImpressions": 2071,
"totalReach": 2052,
"averageCTR": 0.1,
"averageFrequency": 1.02,
"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"
}
}
{
"status": "success",
"history": [
{
"accountId": "274948332",
"adId": "6683876017505",
"adName": "API Post 13 - DE6gpw8kxlonHy6eb7Lo - 2025-03-30T17:11:26",
"budgetDaily": 4,
"budgetType": "",
"currency": "USD",
"deliveryStatus": "ACTIVE",
"fbPostId": "106638148652329_672633202087926",
"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": 2,
"cpc": 0,
"cpp": 1.6,
"cpm": 1.55,
"ctr": 0,
"frequency": 1.03,
"impressions": 452,
"reach": 438
},
"network": "facebook",
"postId": "DE6gpw8kxlonHy6eb7Lo",
"spend": 0.7,
"spendDate": "2025-04-03T00:00:00.000Z",
"spendUsd": 0.7,
"status": "ACTIVE"
},
{
"accountId": "274948332",
"adId": "6683876017505",
"adName": "API Post 13 - DE6gpw8kxlonHy6eb7Lo - 2025-03-30T17:11:26",
"budgetDaily": 4,
"budgetType": "daily",
"currency": "USD",
"deliveryStatus": "ACTIVE",
"fbPostId": "106638148652329_672633202087926",
"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": 1,
"cpc": 0,
"cpp": 1.5,
"cpm": 1.5,
"ctr": 0,
"frequency": 1,
"impressions": 2793,
"reach": 2793
},
"network": "facebook",
"postId": "DE6gpw8kxlonHy6eb7Lo",
"spend": 4.19,
"spendDate": "2025-04-02T00:00:00.000Z",
"spendUsd": 4.19,
"status": "ACTIVE"
}
],
"dateRange": {
"start": "2025-03-04T18:49:18.159Z",
"end": "2025-04-03T18:49:18.159Z",
"adId": "6683876017505"
},
"metrics": {
"totalSpend": 4.89,
"totalSpendByCurrency": { "USD": 4.89 },
"unconvertedRows": 0,
"totalClicks": 3,
"totalImpressions": 10553,
"totalReach": 10339,
"averageCTR": 0.03,
"averageFrequency": 1.02,
"cpm": 1.460248270633943,
"cpp": 1.49047296643776,
"cpc": 5.136666666666667,
"costPerResult": 5.14,
"byGoalType": {
"engagement": {
"spend": 4.89,
"impressions": 10553,
"clicks": 3,
"reach": 10339,
"count": 2,
"ctr": 0.03,
"cpm": 1.46,
"cpp": 1.49,
"cpc": 5.14
}
},
"byGoalTitle": {
"Get More Engagement": {
"spend": 4.89,
"impressions": 10553,
"clicks": 3,
"reach": 10339,
"count": 2,
"type": "engagement",
"ctr": 0.03,
"cpm": 1.5,
"cpp": 1.49,
"cpc": 5.14
}
},
"goalPerformance": {
"bestPerformingGoalType": {
"type": "engagement",
"clicks": 3,
"spend": 4.89,
"ctr": 0.03
},
"mostEfficientGoalType": {
"type": "engagement",
"cpc": 5.14,
"spend": 4.89
}
},
"count": 2,
"firstDay": "2025-03-30T00:00:00.000Z",
"lastDay": "2025-04-03T00:00:00.000Z"
}
}
{
"status": "success",
"history": [],
"dateRange": {
"start": "2025-03-04T18:49:18.159Z",
"end": "2025-04-03T18:49:18.159Z",
"adId": "6683876017505"
},
"metrics": {
"totalSpend": 0,
"totalSpendByCurrency": {},
"unconvertedRows": 0,
"totalClicks": 0,
"totalImpressions": 0,
"totalReach": 0,
"averageCTR": 0,
"averageFrequency": 0,
"cpm": 0,
"cpp": 0,
"cpc": 0,
"costPerResult": 0,
"byGoalType": {},
"byGoalTitle": {},
"goalPerformance": {
"bestPerformingGoalType": null,
"mostEfficientGoalType": null
},
"daysCount": 0,
"firstDay": null,
"lastDay": null
},
"warnings": [
{
"action": "ads",
"status": "error",
"code": 401,
"message": "No spend data found for the ad."
}
]
}
{
"action": "get ad spend",
"status": "error",
"code": 367,
"message": "Error getting ad spend. Please verify you have an active ad account."
}
Facebook Ads
History
Retrieve daily Facebook ad spend and performance metrics for ads created with Boost Post, with goal-specific results, aggregated totals, and date filters.
GET
/
ads
/
facebook
/
history
curl \
-H "Authorization: Bearer API_KEY" \
-X GET https://api.ayrshare.com/api/ads/facebook/history?accountId=1234567890
const API_KEY = "API_KEY";
fetch("https://api.ayrshare.com/api/ads/facebook/history?accountId=1234567890", {
method: "GET",
headers: {
"Authorization": `Bearer ${API_KEY}`
}
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
import requests
headers = {'Authorization': 'Bearer API_KEY'}
r = requests.get('https://api.ayrshare.com/api/ads/facebook/history', headers=headers)
print(r.json())
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.ayrshare.com/api/ads/facebook/history",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer API_KEY"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error: " . $err;
} else {
echo $response;
}
?>
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
static async Task Main(string[] args)
{
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer API_KEY");
var response = await client.GetAsync("https://api.ayrshare.com/api/ads/facebook/history");
var content = await response.Content.ReadAsStringAsync();
Console.WriteLine(content);
}
}
package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
client := &http.Client{}
req, _ := http.NewRequest("GET", "https://api.ayrshare.com/api/ads/facebook/history", nil)
req.Header.Add("Authorization", "Bearer API_KEY")
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error:", err)
return
}
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
fmt.Println(string(body))
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class GetAdSpend {
public static void main(String[] args) {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.ayrshare.com/api/ads/facebook/history"))
.header("Authorization", "Bearer API_KEY")
.GET()
.build();
try {
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
} catch (Exception e) {
e.printStackTrace();
}
}
}
require 'net/http'
require 'json'
require 'uri'
uri = URI.parse('https://api.ayrshare.com/api/ads/facebook/history')
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer API_KEY'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(request)
end
puts response.body
{
"status": "success",
"history": [
{
"adId": "6683876017501",
"adName": "API Post 1 - DE6gpw8kxlonHy6eb7L1 - 2025-03-30T17:11:26",
"budgetDaily": 4,
"budgetType": "daily",
"currency": "USD",
"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": 1.01,
"ctr": 0,
"cpm": 1.53,
"cpp": 1.54,
"cpc": 0
},
"network": "facebook",
"postId": "DE6gpw8kxlonHy6eb7L1",
"spend": 1.58,
"spendDate": "2025-04-02T00:00:00.000Z",
"spendUsd": 1.58,
"status": "ACTIVE"
},
{
"adId": "120218167147110411",
"adName": "API Post 2 - DE6gpw8kxlonHy6eb7L1 - 2025-03-30T16:41:15",
"budgetDaily": 4,
"budgetType": "daily",
"currency": "USD",
"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": 1.02,
"ctr": 0,
"cpm": 1.61,
"cpp": 1.65,
"cpc": 0
},
"network": "facebook",
"postId": "DE6gpw8kxlonHy6eb7L1",
"spend": 1.67,
"spendDate": "2025-04-02T00:00:00.000Z",
"spendUsd": 1.67,
"status": "ACTIVE"
}
],
"dateRange": {
"start": "2025-02-24T20:02:34.613Z",
"end": "2025-03-26T20:02:34.613Z",
"postId": "eSNkaAiFZVin6wm6f"
},
"metrics": {
"totalSpend": 3.25,
"totalSpendByCurrency": { "USD": 3.25 },
"unconvertedRows": 0,
"totalClicks": 7,
"totalImpressions": 2071,
"totalReach": 2052,
"averageCTR": 0.1,
"averageFrequency": 1.02,
"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"
}
}
{
"status": "success",
"history": [
{
"accountId": "274948332",
"adId": "6683876017505",
"adName": "API Post 13 - DE6gpw8kxlonHy6eb7Lo - 2025-03-30T17:11:26",
"budgetDaily": 4,
"budgetType": "",
"currency": "USD",
"deliveryStatus": "ACTIVE",
"fbPostId": "106638148652329_672633202087926",
"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": 2,
"cpc": 0,
"cpp": 1.6,
"cpm": 1.55,
"ctr": 0,
"frequency": 1.03,
"impressions": 452,
"reach": 438
},
"network": "facebook",
"postId": "DE6gpw8kxlonHy6eb7Lo",
"spend": 0.7,
"spendDate": "2025-04-03T00:00:00.000Z",
"spendUsd": 0.7,
"status": "ACTIVE"
},
{
"accountId": "274948332",
"adId": "6683876017505",
"adName": "API Post 13 - DE6gpw8kxlonHy6eb7Lo - 2025-03-30T17:11:26",
"budgetDaily": 4,
"budgetType": "daily",
"currency": "USD",
"deliveryStatus": "ACTIVE",
"fbPostId": "106638148652329_672633202087926",
"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": 1,
"cpc": 0,
"cpp": 1.5,
"cpm": 1.5,
"ctr": 0,
"frequency": 1,
"impressions": 2793,
"reach": 2793
},
"network": "facebook",
"postId": "DE6gpw8kxlonHy6eb7Lo",
"spend": 4.19,
"spendDate": "2025-04-02T00:00:00.000Z",
"spendUsd": 4.19,
"status": "ACTIVE"
}
],
"dateRange": {
"start": "2025-03-04T18:49:18.159Z",
"end": "2025-04-03T18:49:18.159Z",
"adId": "6683876017505"
},
"metrics": {
"totalSpend": 4.89,
"totalSpendByCurrency": { "USD": 4.89 },
"unconvertedRows": 0,
"totalClicks": 3,
"totalImpressions": 10553,
"totalReach": 10339,
"averageCTR": 0.03,
"averageFrequency": 1.02,
"cpm": 1.460248270633943,
"cpp": 1.49047296643776,
"cpc": 5.136666666666667,
"costPerResult": 5.14,
"byGoalType": {
"engagement": {
"spend": 4.89,
"impressions": 10553,
"clicks": 3,
"reach": 10339,
"count": 2,
"ctr": 0.03,
"cpm": 1.46,
"cpp": 1.49,
"cpc": 5.14
}
},
"byGoalTitle": {
"Get More Engagement": {
"spend": 4.89,
"impressions": 10553,
"clicks": 3,
"reach": 10339,
"count": 2,
"type": "engagement",
"ctr": 0.03,
"cpm": 1.5,
"cpp": 1.49,
"cpc": 5.14
}
},
"goalPerformance": {
"bestPerformingGoalType": {
"type": "engagement",
"clicks": 3,
"spend": 4.89,
"ctr": 0.03
},
"mostEfficientGoalType": {
"type": "engagement",
"cpc": 5.14,
"spend": 4.89
}
},
"count": 2,
"firstDay": "2025-03-30T00:00:00.000Z",
"lastDay": "2025-04-03T00:00:00.000Z"
}
}
{
"status": "success",
"history": [],
"dateRange": {
"start": "2025-03-04T18:49:18.159Z",
"end": "2025-04-03T18:49:18.159Z",
"adId": "6683876017505"
},
"metrics": {
"totalSpend": 0,
"totalSpendByCurrency": {},
"unconvertedRows": 0,
"totalClicks": 0,
"totalImpressions": 0,
"totalReach": 0,
"averageCTR": 0,
"averageFrequency": 0,
"cpm": 0,
"cpp": 0,
"cpc": 0,
"costPerResult": 0,
"byGoalType": {},
"byGoalTitle": {},
"goalPerformance": {
"bestPerformingGoalType": null,
"mostEfficientGoalType": null
},
"daysCount": 0,
"firstDay": null,
"lastDay": null
},
"warnings": [
{
"action": "ads",
"status": "error",
"code": 401,
"message": "No spend data found for the ad."
}
]
}
{
"action": "get ad spend",
"status": "error",
"code": 367,
"message": "Error getting ad spend. Please verify you have an active ad account."
}
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
history 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.When no ad has spend in the date range, the response is still a success: history is
empty and warnings holds one entry with code 401.- Metrics are calculated from Facebook’s reporting API and may have slight delays (up to 24 hours).
- The
byGoalTypeandbyGoalTitlesections group performance metrics by goal objectives. - Use either
adIdorpostIdfilters to narrow results to specific campaigns. - Each day’s
spendis in the ad account’s currency, shown incurrency.spendUsdis the same spend in US dollars. - Non-USD spend is converted to USD at that day’s exchange rate from Open Exchange Rates.
totalSpend,cpm,cpp,cpc,costPerResultand the goalspendtotals are in US dollars. totalSpendByCurrencygives the total spend in each currency before conversion.unconvertedRowscounts the days not converted yet: they count at face value intotalSpend, and theirspendUsdisnull.- Spend from before October 2026 may show
currency: "USD"even when the ad account uses another currency, and is counted intotalSpendas recorded. - The
goalPerformancesection 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
string
Filter results to a specific account ID.
string
Filter results to a specific ad ID.
string
Filter results to ads associated with a specific Ayrshare post
ID.
string
Filter results to ads associated with a specific Facebook social post
ID.
number
default:25
Retrieve a maximum of
limit ads. Maximum is 500.string
default:"30 days ago"
Start date for the reporting period in ISO 8601 format (default: 30 days ago)
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/history?accountId=1234567890
const API_KEY = "API_KEY";
fetch("https://api.ayrshare.com/api/ads/facebook/history?accountId=1234567890", {
method: "GET",
headers: {
"Authorization": `Bearer ${API_KEY}`
}
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
import requests
headers = {'Authorization': 'Bearer API_KEY'}
r = requests.get('https://api.ayrshare.com/api/ads/facebook/history', headers=headers)
print(r.json())
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.ayrshare.com/api/ads/facebook/history",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer API_KEY"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error: " . $err;
} else {
echo $response;
}
?>
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
static async Task Main(string[] args)
{
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer API_KEY");
var response = await client.GetAsync("https://api.ayrshare.com/api/ads/facebook/history");
var content = await response.Content.ReadAsStringAsync();
Console.WriteLine(content);
}
}
package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
client := &http.Client{}
req, _ := http.NewRequest("GET", "https://api.ayrshare.com/api/ads/facebook/history", nil)
req.Header.Add("Authorization", "Bearer API_KEY")
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error:", err)
return
}
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
fmt.Println(string(body))
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class GetAdSpend {
public static void main(String[] args) {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.ayrshare.com/api/ads/facebook/history"))
.header("Authorization", "Bearer API_KEY")
.GET()
.build();
try {
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
} catch (Exception e) {
e.printStackTrace();
}
}
}
require 'net/http'
require 'json'
require 'uri'
uri = URI.parse('https://api.ayrshare.com/api/ads/facebook/history')
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer API_KEY'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(request)
end
puts response.body
{
"status": "success",
"history": [
{
"adId": "6683876017501",
"adName": "API Post 1 - DE6gpw8kxlonHy6eb7L1 - 2025-03-30T17:11:26",
"budgetDaily": 4,
"budgetType": "daily",
"currency": "USD",
"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": 1.01,
"ctr": 0,
"cpm": 1.53,
"cpp": 1.54,
"cpc": 0
},
"network": "facebook",
"postId": "DE6gpw8kxlonHy6eb7L1",
"spend": 1.58,
"spendDate": "2025-04-02T00:00:00.000Z",
"spendUsd": 1.58,
"status": "ACTIVE"
},
{
"adId": "120218167147110411",
"adName": "API Post 2 - DE6gpw8kxlonHy6eb7L1 - 2025-03-30T16:41:15",
"budgetDaily": 4,
"budgetType": "daily",
"currency": "USD",
"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": 1.02,
"ctr": 0,
"cpm": 1.61,
"cpp": 1.65,
"cpc": 0
},
"network": "facebook",
"postId": "DE6gpw8kxlonHy6eb7L1",
"spend": 1.67,
"spendDate": "2025-04-02T00:00:00.000Z",
"spendUsd": 1.67,
"status": "ACTIVE"
}
],
"dateRange": {
"start": "2025-02-24T20:02:34.613Z",
"end": "2025-03-26T20:02:34.613Z",
"postId": "eSNkaAiFZVin6wm6f"
},
"metrics": {
"totalSpend": 3.25,
"totalSpendByCurrency": { "USD": 3.25 },
"unconvertedRows": 0,
"totalClicks": 7,
"totalImpressions": 2071,
"totalReach": 2052,
"averageCTR": 0.1,
"averageFrequency": 1.02,
"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"
}
}
{
"status": "success",
"history": [
{
"accountId": "274948332",
"adId": "6683876017505",
"adName": "API Post 13 - DE6gpw8kxlonHy6eb7Lo - 2025-03-30T17:11:26",
"budgetDaily": 4,
"budgetType": "",
"currency": "USD",
"deliveryStatus": "ACTIVE",
"fbPostId": "106638148652329_672633202087926",
"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": 2,
"cpc": 0,
"cpp": 1.6,
"cpm": 1.55,
"ctr": 0,
"frequency": 1.03,
"impressions": 452,
"reach": 438
},
"network": "facebook",
"postId": "DE6gpw8kxlonHy6eb7Lo",
"spend": 0.7,
"spendDate": "2025-04-03T00:00:00.000Z",
"spendUsd": 0.7,
"status": "ACTIVE"
},
{
"accountId": "274948332",
"adId": "6683876017505",
"adName": "API Post 13 - DE6gpw8kxlonHy6eb7Lo - 2025-03-30T17:11:26",
"budgetDaily": 4,
"budgetType": "daily",
"currency": "USD",
"deliveryStatus": "ACTIVE",
"fbPostId": "106638148652329_672633202087926",
"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": 1,
"cpc": 0,
"cpp": 1.5,
"cpm": 1.5,
"ctr": 0,
"frequency": 1,
"impressions": 2793,
"reach": 2793
},
"network": "facebook",
"postId": "DE6gpw8kxlonHy6eb7Lo",
"spend": 4.19,
"spendDate": "2025-04-02T00:00:00.000Z",
"spendUsd": 4.19,
"status": "ACTIVE"
}
],
"dateRange": {
"start": "2025-03-04T18:49:18.159Z",
"end": "2025-04-03T18:49:18.159Z",
"adId": "6683876017505"
},
"metrics": {
"totalSpend": 4.89,
"totalSpendByCurrency": { "USD": 4.89 },
"unconvertedRows": 0,
"totalClicks": 3,
"totalImpressions": 10553,
"totalReach": 10339,
"averageCTR": 0.03,
"averageFrequency": 1.02,
"cpm": 1.460248270633943,
"cpp": 1.49047296643776,
"cpc": 5.136666666666667,
"costPerResult": 5.14,
"byGoalType": {
"engagement": {
"spend": 4.89,
"impressions": 10553,
"clicks": 3,
"reach": 10339,
"count": 2,
"ctr": 0.03,
"cpm": 1.46,
"cpp": 1.49,
"cpc": 5.14
}
},
"byGoalTitle": {
"Get More Engagement": {
"spend": 4.89,
"impressions": 10553,
"clicks": 3,
"reach": 10339,
"count": 2,
"type": "engagement",
"ctr": 0.03,
"cpm": 1.5,
"cpp": 1.49,
"cpc": 5.14
}
},
"goalPerformance": {
"bestPerformingGoalType": {
"type": "engagement",
"clicks": 3,
"spend": 4.89,
"ctr": 0.03
},
"mostEfficientGoalType": {
"type": "engagement",
"cpc": 5.14,
"spend": 4.89
}
},
"count": 2,
"firstDay": "2025-03-30T00:00:00.000Z",
"lastDay": "2025-04-03T00:00:00.000Z"
}
}
{
"status": "success",
"history": [],
"dateRange": {
"start": "2025-03-04T18:49:18.159Z",
"end": "2025-04-03T18:49:18.159Z",
"adId": "6683876017505"
},
"metrics": {
"totalSpend": 0,
"totalSpendByCurrency": {},
"unconvertedRows": 0,
"totalClicks": 0,
"totalImpressions": 0,
"totalReach": 0,
"averageCTR": 0,
"averageFrequency": 0,
"cpm": 0,
"cpp": 0,
"cpc": 0,
"costPerResult": 0,
"byGoalType": {},
"byGoalTitle": {},
"goalPerformance": {
"bestPerformingGoalType": null,
"mostEfficientGoalType": null
},
"daysCount": 0,
"firstDay": null,
"lastDay": null
},
"warnings": [
{
"action": "ads",
"status": "error",
"code": 401,
"message": "No spend data found for the ad."
}
]
}
{
"action": "get ad spend",
"status": "error",
"code": 367,
"message": "Error getting ad spend. Please verify you have an active ad account."
}