curl \
-H "Authorization: Bearer API_KEY" \
-X GET "https://api.ayrshare.com/api/ads/facebook/insights?level=campaign&ids=120200000000000001&startDate=2026-09-01&endDate=2026-09-02"
const API_KEY = "API_KEY";
const params = new URLSearchParams({
level: "campaign",
ids: "120200000000000001",
startDate: "2026-09-01",
endDate: "2026-09-02",
});
fetch(`https://api.ayrshare.com/api/ads/facebook/insights?${params}`, {
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'}
params = {
'level': 'campaign',
'ids': '120200000000000001',
'startDate': '2026-09-01',
'endDate': '2026-09-02',
}
r = requests.get('https://api.ayrshare.com/api/ads/facebook/insights', headers=headers, params=params)
print(r.json())
{
"status": "success",
"platform": "facebook",
"level": "campaign",
"startDate": "2026-09-01",
"endDate": "2026-09-02",
"insights": [
{
"date": "2026-09-01",
"level": "campaign",
"id": "120200000000000001",
"currency": "USD",
"spend": 12.34,
"impressions": 4000,
"reach": 3100,
"clicks": 80,
"cpm": 3.085,
"cpc": 0.15425,
"ctr": 2,
"actions": [
{ "type": "link_click", "value": 75 },
{ "type": "omni_purchase", "value": 3 }
],
"conversionValue": 89.97
}
],
"count": 1,
"nextCursor": null
}
{
"status": "success",
"platform": "facebook",
"level": "ad",
"startDate": "2026-09-01",
"endDate": "2026-09-01",
"insights": [
{
"date": "2026-09-01",
"level": "ad",
"id": "120210000000000001",
"age": "25-34",
"gender": "female",
"currency": "EUR",
"spend": 1.5,
"impressions": 300
},
{
"date": "2026-09-01",
"level": "ad",
"id": "120210000000000001",
"age": "25-34",
"gender": "male",
"currency": "EUR",
"spend": 1,
"impressions": 200
}
],
"count": 2,
"nextCursor": null
}
{
"action": "ads",
"status": "error",
"code": 400,
"message": "The ad is not found or not authorized."
}
Facebook Ads
Insights
Get Live Daily Facebook Ad Insights by Campaign or Ad
GET
/
ads
/
facebook
/
insights
curl \
-H "Authorization: Bearer API_KEY" \
-X GET "https://api.ayrshare.com/api/ads/facebook/insights?level=campaign&ids=120200000000000001&startDate=2026-09-01&endDate=2026-09-02"
const API_KEY = "API_KEY";
const params = new URLSearchParams({
level: "campaign",
ids: "120200000000000001",
startDate: "2026-09-01",
endDate: "2026-09-02",
});
fetch(`https://api.ayrshare.com/api/ads/facebook/insights?${params}`, {
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'}
params = {
'level': 'campaign',
'ids': '120200000000000001',
'startDate': '2026-09-01',
'endDate': '2026-09-02',
}
r = requests.get('https://api.ayrshare.com/api/ads/facebook/insights', headers=headers, params=params)
print(r.json())
{
"status": "success",
"platform": "facebook",
"level": "campaign",
"startDate": "2026-09-01",
"endDate": "2026-09-02",
"insights": [
{
"date": "2026-09-01",
"level": "campaign",
"id": "120200000000000001",
"currency": "USD",
"spend": 12.34,
"impressions": 4000,
"reach": 3100,
"clicks": 80,
"cpm": 3.085,
"cpc": 0.15425,
"ctr": 2,
"actions": [
{ "type": "link_click", "value": 75 },
{ "type": "omni_purchase", "value": 3 }
],
"conversionValue": 89.97
}
],
"count": 1,
"nextCursor": null
}
{
"status": "success",
"platform": "facebook",
"level": "ad",
"startDate": "2026-09-01",
"endDate": "2026-09-01",
"insights": [
{
"date": "2026-09-01",
"level": "ad",
"id": "120210000000000001",
"age": "25-34",
"gender": "female",
"currency": "EUR",
"spend": 1.5,
"impressions": 300
},
{
"date": "2026-09-01",
"level": "ad",
"id": "120210000000000001",
"age": "25-34",
"gender": "male",
"currency": "EUR",
"spend": 1,
"impressions": 200
}
],
"count": 2,
"nextCursor": null
}
{
"action": "ads",
"status": "error",
"code": 400,
"message": "The ad is not found or not authorized."
}
Get live Facebook ad performance, one row per day, for your campaigns or ads.
Pick the metrics you want, split them by age, gender, country or placement, and page through long date ranges.
Facebook reports every metric in this table. One exception: Meta does not report
- Numbers are read from Meta when you call, not from a nightly copy.
- Use History for the spend we bill. Use Insights for reporting and analysis.
- All money values are in the ad account’s currency, returned in
currencyon each row. - Campaigns must have been created through Ayrshare for this profile. An ad created through Ayrshare for another profile is refused. Other ad ids are read with this profile’s linked Meta account, so Meta only returns ads that account can see.
- One request covers one ad account. Ids from several ad accounts return code
101, and so do several ad ids that Ayrshare has no record of. Ask for those one at a time.
Header Parameters
Query Parameters
string
required
What each row reports on:
campaign or ad.adSet is not supported yet and returns code 101.string
Comma-separated campaign or ad ids, up to 50. Required for
level=campaign.With level=ad, you can leave ids out and send accountId instead. This reports on the ads
you created through Ayrshare for this profile in that ad account, not on every ad in it. It works
for up to 50 such ads. For more, send their ids, or report by campaign. If none are found, the
report is empty.string
The ad account id, with or without the
act_ prefix (1234567890 or act_1234567890).Required with level=ad when ids is left out.string
Comma-separated breakdowns:
age, gender, country, placement. Each day then has one row per
value, or per combination with age,gender. Send one breakdown at a time, or age,gender; Meta
refuses other mixes (such as age,country), so they return code 101.string
default:"30 days ago"
First day, as
YYYY-MM-DD. It can be up to 37 months ago.string
default:"today"
Last day, as
YYYY-MM-DD.string
The
nextCursor from the previous response, to get the next page.Metrics
| Metric | Type | Meaning |
|---|---|---|
spend | number | Amount spent |
impressions | number | Times the ad was shown |
reach | number | People who saw the ad at least once |
clicks | number | Clicks |
cpm | number or null | Cost per 1,000 impressions |
cpc | number or null | Cost per click. null on a day with no clicks |
ctr | number or null | Click-through rate, in percent |
actions | array | Each action type Meta counted, with its count |
conversionValue | number | Total value of purchases |
reach for a report with
breakdowns that starts more than 13 months ago, so reach is left out of those rows. On networks that don’t report a metric, it is left out
of the rows rather than returned as 0, and asking for it returns code 101.
Meta counts some actions under more than one type, so don’t add
actions values together. For
example, omni_purchase already includes purchase. conversionValue counts each purchase once.Paging
Each response returns up to 500 rows. If there are more,nextCursor is set. Send the same request
again with cursor set to that value to get the next page. On the last page, nextCursor is null.
Errors
| Code | When |
|---|---|
101 | A parameter is missing or wrong, a breakdown or metric isn’t supported, level=adSet is sent, startDate is more than 37 months ago, more than 50 ids are sent, the ids are in more than one ad account, or Meta refuses the breakdown combination |
400 | A campaign or ad isn’t yours, or accountId isn’t the ad account Ayrshare has on record for the ids you sent. For an ad with no Ayrshare record, accountId is not checked and the ad is read on its own |
370 | Meta could not return the insights. Try again |
curl \
-H "Authorization: Bearer API_KEY" \
-X GET "https://api.ayrshare.com/api/ads/facebook/insights?level=campaign&ids=120200000000000001&startDate=2026-09-01&endDate=2026-09-02"
const API_KEY = "API_KEY";
const params = new URLSearchParams({
level: "campaign",
ids: "120200000000000001",
startDate: "2026-09-01",
endDate: "2026-09-02",
});
fetch(`https://api.ayrshare.com/api/ads/facebook/insights?${params}`, {
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'}
params = {
'level': 'campaign',
'ids': '120200000000000001',
'startDate': '2026-09-01',
'endDate': '2026-09-02',
}
r = requests.get('https://api.ayrshare.com/api/ads/facebook/insights', headers=headers, params=params)
print(r.json())
{
"status": "success",
"platform": "facebook",
"level": "campaign",
"startDate": "2026-09-01",
"endDate": "2026-09-02",
"insights": [
{
"date": "2026-09-01",
"level": "campaign",
"id": "120200000000000001",
"currency": "USD",
"spend": 12.34,
"impressions": 4000,
"reach": 3100,
"clicks": 80,
"cpm": 3.085,
"cpc": 0.15425,
"ctr": 2,
"actions": [
{ "type": "link_click", "value": 75 },
{ "type": "omni_purchase", "value": 3 }
],
"conversionValue": 89.97
}
],
"count": 1,
"nextCursor": null
}
{
"status": "success",
"platform": "facebook",
"level": "ad",
"startDate": "2026-09-01",
"endDate": "2026-09-01",
"insights": [
{
"date": "2026-09-01",
"level": "ad",
"id": "120210000000000001",
"age": "25-34",
"gender": "female",
"currency": "EUR",
"spend": 1.5,
"impressions": 300
},
{
"date": "2026-09-01",
"level": "ad",
"id": "120210000000000001",
"age": "25-34",
"gender": "male",
"currency": "EUR",
"spend": 1,
"impressions": 200
}
],
"count": 2,
"nextCursor": null
}
{
"action": "ads",
"status": "error",
"code": 400,
"message": "The ad is not found or not authorized."
}