Facebook organizes ads in a structure with three levels: campaign, ad set and ad. In the API, developers have access to a fourth level called creative.
These objects contain your advertising objective and one or more ad sets. This helps you optimize and measure results for each advertising objective.
Ad sets have one or more ads. You define budget and schedule for each ad set. Create an ad set for each target audience with your bid; ads in the set target the same audience with the same bid. This helps control the amount you spend on each audience, determine when the audience will see your ads, and provides metrics for each audience.
Contains ad creative. Create multiple ads in each ad set to optimize ad delivery based different images, links, video, text, or placements.
Contain just the visual elements of the ad and you can't change them once they're created. Each ad account has a creative library to store creatives for reuse in ads.
Objective | Schedule | Budget | Bidding | Targeting | Creative | |
---|---|---|---|---|---|---|
Campaign | ✓ | |||||
Ad Set | ✓ | ✓ | ✓ | ✓ | ||
Ad | ✓ |
Mapping between the public facing naming of the object and API endpoints:
Public facing name | API endpoint |
---|---|
Campaign | /campaigns |
Ad Set | /adsets |
Ad | /ads |
Creative | /adcreatives |
A campaign is the highest level organizational structure within an ad account and should represent a single objective for an advertiser, for example, to drive page post engagement. Setting the objective of the campaign enforces validation on any ads added to that campaign to ensure they also have the correct objective.
In the ads manager, we show all of the active and paused campaigns within an ad account.
To read the campaigns associated with a specific account, you make a request to the connection of the ad account you are using. By default we only return campaigns whose status is ACTIVE
or PAUSED
, so you need to specify additional statuses if required:
curl -X GET \
-d 'effective_status=[
"ACTIVE",
"PAUSED"
]' \
-d 'fields="name,objective"' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/campaigns
We also show some high level insights, including impressions, clicks and the amount spent. You can retrieve these by calling the following endpoint, optionally specifying the start and/or end time:
use FacebookAds\Object\Campaign;
$campaign = new Campaign(<CAMPAIGN_ID>);
$insights = $campaign->getInsights(array(
AdsInsightsFields::IMPRESSIONS,
AdsInsightsFields::INLINE_LINK_CLICKS,
AdsInsightsFields::SPEND,
), array(
'end_time' => (new \DateTime('now'))->getTimestamp(),
));
from facebookads.adobjects.campaign import Campaign
from facebookads.adobjects.adsinsights import AdsInsights
import time
fields = [
AdsInsights.Field.impressions,
AdsInsights.Field.inline_link_clicks,
AdsInsights.Field.spend,
]
params = {
'end_time': int(time.time()),
}
campaign = Campaign(<CAMPAIGN_ID>)
insights = campaign.get_insights(fields=fields, params=params)
APINodeList<AdsInsights> adsInsightss = new Campaign(<CAMPAIGN_ID>, context).getInsights()
.setParam("end_time", end_time)
.requestField("impressions")
.requestField("inline_link_clicks")
.requestField("spend")
.execute();
curl -G \
-d 'end_time=1517287567' \
-d 'fields=impressions,inline_link_clicks,spend' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v2.11/<CAMPAIGN_ID>/insights
Objectives are actions you want people to make when they see your ad. You need to specify your chosen objective during campaign creation.
Explicitly setting the objective has the following benefits:
The minimum API call needed to create a campaign is:
curl -X POST \
-F 'name="My First Campaign"' \
-F 'objective="OUTCOME_ENGAGEMENT"' \
-F 'status="PAUSED"' \
-F 'special_ad_categories=[]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/campaigns
Ad sets are groups of ads, and are used to configure the budget and period the ads should run for. All ads contained within an ad set should have the same targeting, budget, billing, optimization goal, and duration.
curl -X POST \
-F 'name="My First AdSet"' \
-F 'lifetime_budget=20000' \
-F 'start_time="2024-10-14T04:13:38-0700"' \
-F 'end_time="2024-10-21T04:13:38-0700"' \
-F 'campaign_id="<AD_CAMPAIGN_ID>"' \
-F 'bid_amount=500' \
-F 'billing_event="IMPRESSIONS"' \
-F 'optimization_goal="POST_ENGAGEMENT"' \
-F 'targeting={
"age_min": 20,
"age_max": 24,
"behaviors": [
{
"id": 6002714895372,
"name": "All travelers"
}
],
"genders": [
1
],
"geo_locations": {
"countries": [
"US"
],
"regions": [
{
"key": "4081"
}
],
"cities": [
{
"key": "777934",
"radius": 10,
"distance_unit": "mile"
}
]
},
"interests": [
{
"id": "<INTEREST_ID>",
"name": "<INTEREST_NAME>"
}
],
"life_events": [
{
"id": 6002714398172,
"name": "Newlywed (1 year)"
}
],
"facebook_positions": [
"feed"
],
"publisher_platforms": [
"facebook",
"audience_network"
]
}' \
-F 'status="PAUSED"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/adsets
You can list all ad sets within a campaign by making a request to the following path, specifying the fields and statuses you want:
curl -X GET \
-d 'fields="name,start_time,end_time,daily_budget,lifetime_budget"' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/<AD_CAMPAIGN_ID>/adsets
An ad object contains all of the information necessary to display an ad on Facebook, including the creative.
curl -X POST \
-F 'name="My Ad"' \
-F 'adset_id="<AD_SET_ID>"' \
-F 'creative={
"creative_id": "<CREATIVE_ID>"
}' \
-F 'status="PAUSED"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/ads
To see a preview of your ad, see our guide.
Finally, if you want to list all of the ads for an ad set, you can make a request to the following path, specifying the fields you want to retrieve:
use FacebookAds\Object\AdSet;
use FacebookAds\Object\Values\ArchivableCrudObjectEffectiveStatuses;
use FacebookAds\Object\Fields\AdFields;
$adset = new AdSet(<AD_SET_ID>);
$ads = $adset->getAds(array(
AdFields::NAME,
AdFields::CONFIGURED_STATUS,
AdFields::EFFECTIVE_STATUS,
AdFields::CREATIVE,
), array(
AdFields::EFFECTIVE_STATUS => array(
ArchivableCrudObjectEffectiveStatuses::ACTIVE,
ArchivableCrudObjectEffectiveStatuses::PAUSED,
ArchivableCrudObjectEffectiveStatuses::PENDING_REVIEW,
ArchivableCrudObjectEffectiveStatuses::PREAPPROVED,
),
));
from facebookads.adobjects.adset import AdSet
from facebookads.adobjects.ad import Ad
fields = [
Ad.Field.name,
Ad.Field.configured_status,
Ad.Field.effective_status,
Ad.Field.creative,
]
params = {
Ad.Field.effective_status: [
'ACTIVE',
'PAUSED',
'PENDING_REVIEW',
'PREAPPROVED',
],
}
ad_set = AdSet(<AD_SET_ID>)
ads = ad_set.get_ads(fields=fields, params=params)
APINodeList<Ad> ads = new AdSet(<AD_SET_ID>, context).getAds()
.setEffectiveStatus("[\"ACTIVE\",\"PAUSED\",\"PENDING_REVIEW\",\"PREAPPROVED\"]")
.requestNameField()
.requestConfiguredStatusField()
.requestEffectiveStatusField()
.requestCreativeField()
.execute();
curl -G \
--data-urlencode 'effective_status=[
"ACTIVE",
"PAUSED",
"PENDING_REVIEW",
"PREAPPROVED"
]' \
-d 'fields=name,configured_status,effective_status,creative' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v2.11/<AD_SET_ID>/ads
You may find the total number of ads is greater than the number you want to show on a single page. In this case you should specify the limit
field as the number of items you want to retrieve, and then paginate through the remaining items.
Pagination is performed using the cursors returned as part of the response:
"paging": { "previous" : "https://graph.facebook.com/...", "next": "https://graph.facebook.com/...", "cursors": { "before": "NjAxNjc3NTU1ODMyNw==", "after": "NjAxMTc0NTU2MjcyNw==" }
If there are additional pages to retrieve, the response includes the previous
and next
fields, and these URLs can be called to retrieve these pages of data. Read more about cursor-based pagination.