Ad Campaign Structure

Facebook's campaign structure has 3 levels: campaign, ad set and ad. In the API, there is a fourth level available for developers, called the creative.

  • Campaigns contains 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 audience will see your ads, and provides metrics for each audience.

  • Ads (contains ad creative). Create multiple ads in each ad set will to optimize ad delivery based different images, links, video, text or placements.

  • Ad creatives contain just the visual elements of the ad and once created, are immutable. 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

Campaigns

Reference Docs

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. All of the objectives can be found listed within the documentation. Setting objective of the campaign will enforce validation on any ads added to the 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 will 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/v5.0/act_<AD_ACCOUNT_ID>/campaigns
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const AdAccount = bizSdk.AdAccount; const Campaign = bizSdk.Campaign; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<AD_ACCOUNT_ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ 'name', 'objective', ]; params = { 'effective_status' : ['ACTIVE','PAUSED'], }; const campaignss = (new AdAccount(id)).getCampaigns( fields, params ); logApiCallResult('campaignss api call complete.', campaignss);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\Campaign; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<AD_ACCOUNT_ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( 'name', 'objective', ); $params = array( 'effective_status' => array('ACTIVE','PAUSED'), ); echo json_encode((new AdAccount($id))->getCampaigns( $fields, $params )->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.adaccount import AdAccount from facebook_business.adobjects.campaign import Campaign from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_ACCOUNT_ID>' FacebookAdsApi.init(access_token=access_token) fields = [ 'name', 'objective', ] params = { 'effective_status': ['ACTIVE','PAUSED'], } print AdAccount(id).get_campaigns( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<AD_ACCOUNT_ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(id, context).getCampaigns() .setEffectiveStatus(Arrays.asList(Campaign.EnumEffectiveStatus.VALUE_ACTIVE,Campaign.EnumEffectiveStatus.VALUE_PAUSED)) .requestNameField() .requestObjectiveField() .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_ACCOUNT_ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) campaignss = ad_account.campaigns({ fields: { 'name''objective' }, effective_status: ['ACTIVE','PAUSED'], })

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

Objectives are actions you want people to make when they see the ad and objects are what people act upon.

You need to specify your chosen objective during campaign creation. Explicitly setting the objective has the following benefits:

  • You get correct tracking, optimization, and bidding options for your ad.
  • You can view unique UI and analytics dashboards for each objective

The minimum API call needed to create a campaign is:

curl -X POST \ -F 'name="My First Campaign"' \ -F 'objective="PAGE_LIKES"' \ -F 'status="PAUSED"' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v5.0/act_<AD_ACCOUNT_ID>/campaigns
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const AdAccount = bizSdk.AdAccount; const Campaign = bizSdk.Campaign; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<AD_ACCOUNT_ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'name' : 'My First Campaign', 'objective' : 'PAGE_LIKES', 'status' : 'PAUSED', }; const campaigns = (new AdAccount(id)).createCampaign( fields, params ); logApiCallResult('campaigns api call complete.', campaigns);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\Campaign; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<AD_ACCOUNT_ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'My First Campaign', 'objective' => 'PAGE_LIKES', 'status' => 'PAUSED', ); echo json_encode((new AdAccount($id))->createCampaign( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.adaccount import AdAccount from facebook_business.adobjects.campaign import Campaign from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_ACCOUNT_ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'My First Campaign', 'objective': 'PAGE_LIKES', 'status': 'PAUSED', } print AdAccount(id).create_campaign( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<AD_ACCOUNT_ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(id, context).createCampaign() .setName(\"My First Campaign\") .setObjective(Campaign.EnumObjective.VALUE_PAGE_LIKES) .setStatus(Campaign.EnumStatus.VALUE_PAUSED) .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_ACCOUNT_ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) campaigns = ad_account.campaigns.create({ name: 'My First Campaign', objective: 'PAGE_LIKES', status: 'PAUSED', })

To set your objective to POST_ENGAGEMENT, the call looks like this:

curl -X POST \ -F 'name="My First Campaign"' \ -F 'objective="POST_ENGAGEMENT"' \ -F 'status="PAUSED"' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v5.0/act_<AD_ACCOUNT_ID>/campaigns
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const AdAccount = bizSdk.AdAccount; const Campaign = bizSdk.Campaign; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<AD_ACCOUNT_ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'name' : 'My First Campaign', 'objective' : 'POST_ENGAGEMENT', 'status' : 'PAUSED', }; const campaigns = (new AdAccount(id)).createCampaign( fields, params ); logApiCallResult('campaigns api call complete.', campaigns);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\Campaign; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<AD_ACCOUNT_ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'My First Campaign', 'objective' => 'POST_ENGAGEMENT', 'status' => 'PAUSED', ); echo json_encode((new AdAccount($id))->createCampaign( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.adaccount import AdAccount from facebook_business.adobjects.campaign import Campaign from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_ACCOUNT_ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'My First Campaign', 'objective': 'POST_ENGAGEMENT', 'status': 'PAUSED', } print AdAccount(id).create_campaign( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<AD_ACCOUNT_ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(id, context).createCampaign() .setName(\"My First Campaign\") .setObjective(Campaign.EnumObjective.VALUE_POST_ENGAGEMENT) .setStatus(Campaign.EnumStatus.VALUE_PAUSED) .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_ACCOUNT_ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) campaigns = ad_account.campaigns.create({ name: 'My First Campaign', objective: 'POST_ENGAGEMENT', status: 'PAUSED', })

See campaign for acceptable values for the objective parameter.

Ad Sets

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.

curl -X POST \ -F 'name="My First AdSet"' \ -F 'lifetime_budget=20000' \ -F 'start_time="2019-11-19T05:21:30-0800"' \ -F 'end_time="2019-11-26T05:21:30-0800"' \ -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)" } ], "publisher_platforms": [ "facebook", "audience_network" ] }' \ -F 'status="PAUSED"' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v5.0/act_<AD_ACCOUNT_ID>/adsets
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const AdAccount = bizSdk.AdAccount; const AdSet = bizSdk.AdSet; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<AD_ACCOUNT_ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'name' : 'My First AdSet', 'lifetime_budget' : '20000', 'start_time' : '2019-08-14T02:17:24-0700', 'end_time' : '2019-08-21T02:17:24-0700', 'campaign_id' : '<adCampaignLinkClicksID>', 'bid_amount' : '500', 'billing_event' : 'IMPRESSIONS', 'optimization_goal' : 'POST_ENGAGEMENT', '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':'<adsInterestID>','name':'<adsInterestName>'}],'life_events':[{'id':6002714398172,'name':'Newlywed (1 year)'}],'publisher_platforms':['facebook','audience_network']}, 'status' : 'PAUSED', }; const adsets = (new AdAccount(id)).createAdSet( fields, params ); logApiCallResult('adsets api call complete.', adsets);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\AdSet; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<AD_ACCOUNT_ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'My First AdSet', 'lifetime_budget' => '20000', 'start_time' => '2019-08-14T02:17:24-0700', 'end_time' => '2019-08-21T02:17:24-0700', 'campaign_id' => '<adCampaignLinkClicksID>', 'bid_amount' => '500', 'billing_event' => 'IMPRESSIONS', 'optimization_goal' => 'POST_ENGAGEMENT', 'targeting' => array('age_min' => 20,'age_max' => 24,'behaviors' => array(array('id' => 6002714895372,'name' => 'All travelers')),'genders' => array(1),'geo_locations' => array('countries' => array('US'),'regions' => array(array('key' => '4081')),'cities' => array(array('key' => '777934','radius' => 10,'distance_unit' => 'mile'))),'interests' => array(array('id' => '<adsInterestID>','name' => '<adsInterestName>')),'life_events' => array(array('id' => 6002714398172,'name' => 'Newlywed (1 year)')),'publisher_platforms' => array('facebook','audience_network')), 'status' => 'PAUSED', ); echo json_encode((new AdAccount($id))->createAdSet( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.adaccount import AdAccount from facebook_business.adobjects.adset import AdSet from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_ACCOUNT_ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'My First AdSet', 'lifetime_budget': '20000', 'start_time': '2019-08-14T02:17:24-0700', 'end_time': '2019-08-21T02:17:24-0700', 'campaign_id': '<adCampaignLinkClicksID>', 'bid_amount': '500', 'billing_event': 'IMPRESSIONS', 'optimization_goal': 'POST_ENGAGEMENT', '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':'<adsInterestID>','name':'<adsInterestName>'}],'life_events':[{'id':6002714398172,'name':'Newlywed (1 year)'}],'publisher_platforms':['facebook','audience_network']}, 'status': 'PAUSED', } print AdAccount(id).create_ad_set( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<AD_ACCOUNT_ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(id, context).createAdSet() .setName(\"My First AdSet\") .setLifetimeBudget(20000L) .setStartTime(\"2019-08-14T02:17:24-0700\") .setEndTime(\"2019-08-21T02:17:24-0700\") .setCampaignId(\"<adCampaignLinkClicksID>\") .setBidAmount(500L) .setBillingEvent(AdSet.EnumBillingEvent.VALUE_IMPRESSIONS) .setOptimizationGoal(AdSet.EnumOptimizationGoal.VALUE_POST_ENGAGEMENT) .setTargeting( new Targeting() .setFieldAgeMax(24L) .setFieldAgeMin(20L) .setFieldBehaviors(Arrays.asList( new IDName() .setFieldId(6002714895372L) .setFieldName(\"All travelers\") )) .setFieldGenders(Arrays.asList(1L)) .setFieldGeoLocations( new TargetingGeoLocation() .setFieldCities(Arrays.asList( new TargetingGeoLocationCity() .setFieldDistanceUnit(\"mile\") .setFieldKey(\"777934\") .setFieldRadius(10L) )) .setFieldCountries(Arrays.asList(\"US\")) .setFieldRegions(Arrays.asList( new TargetingGeoLocationRegion() .setFieldKey(\"4081\") )) ) .setFieldInterests(Arrays.asList( new IDName() .setFieldId(\"<adsInterestID>\") .setFieldName(\"<adsInterestName>\") )) .setFieldLifeEvents(Arrays.asList( new IDName() .setFieldId(6002714398172L) .setFieldName(\"Newlywed (1 year)\") )) .setFieldPublisherPlatforms(Arrays.asList(\"facebook\", \"audience_network\")) ) .setStatus(AdSet.EnumStatus.VALUE_PAUSED) .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_ACCOUNT_ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) adsets = ad_account.adsets.create({ name: 'My First AdSet', lifetime_budget: '20000', start_time: '2019-08-14T02:17:24-0700', end_time: '2019-08-21T02:17:24-0700', campaign_id: '<adCampaignLinkClicksID>', bid_amount: '500', billing_event: 'IMPRESSIONS', optimization_goal: 'POST_ENGAGEMENT', 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':'<adsInterestID>','name':'<adsInterestName>'}],'life_events':[{'id':6002714398172,'name':'Newlywed (1 year)'}],'publisher_platforms':['facebook','audience_network']}, status: 'PAUSED', })

Within your UI, you will likely want to list all ad sets within a campaign. You can achieve this 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/v5.0/<AD_CAMPAIGN_ID>/adsets
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const Campaign = bizSdk.Campaign; const AdSet = bizSdk.AdSet; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<AD_CAMPAIGN_ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ 'name', 'start_time', 'end_time', 'daily_budget', 'lifetime_budget', ]; params = { }; const adsetss = (new Campaign(id)).getAdSets( fields, params ); logApiCallResult('adsetss api call complete.', adsetss);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\Campaign; use FacebookAds\Object\AdSet; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<AD_CAMPAIGN_ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( 'name', 'start_time', 'end_time', 'daily_budget', 'lifetime_budget', ); $params = array( ); echo json_encode((new Campaign($id))->getAdSets( $fields, $params )->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.campaign import Campaign from facebook_business.adobjects.adset import AdSet from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_CAMPAIGN_ID>' FacebookAdsApi.init(access_token=access_token) fields = [ 'name', 'start_time', 'end_time', 'daily_budget', 'lifetime_budget', ] params = { } print Campaign(id).get_ad_sets( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<AD_CAMPAIGN_ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new Campaign(id, context).getAdSets() .requestNameField() .requestStartTimeField() .requestEndTimeField() .requestDailyBudgetField() .requestLifetimeBudgetField() .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_CAMPAIGN_ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end campaign = FacebookAds::Campaign.get(id) adsetss = campaign.adsets({ fields: { 'name''start_time''end_time''daily_budget''lifetime_budget' }, })

Ads

An ad object contains all of the information necessary to display an ad on Facebook, like 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/v5.0/act_<AD_ACCOUNT_ID>/ads
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const AdAccount = bizSdk.AdAccount; const Ad = bizSdk.Ad; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<AD_ACCOUNT_ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'name' : 'My Ad', 'adset_id' : '<adSetID>', 'creative' : {'creative_id':'<adCreativeID>'}, 'status' : 'PAUSED', }; const ads = (new AdAccount(id)).createAd( fields, params ); logApiCallResult('ads api call complete.', ads);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\Ad; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<AD_ACCOUNT_ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'My Ad', 'adset_id' => '<adSetID>', 'creative' => array('creative_id' => '<adCreativeID>'), 'status' => 'PAUSED', ); echo json_encode((new AdAccount($id))->createAd( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.adaccount import AdAccount from facebook_business.adobjects.ad import Ad from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_ACCOUNT_ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'My Ad', 'adset_id': '<adSetID>', 'creative': {'creative_id':'<adCreativeID>'}, 'status': 'PAUSED', } print AdAccount(id).create_ad( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<AD_ACCOUNT_ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(id, context).createAd() .setName(\"My Ad\") .setAdsetId(<adSetID>L) .setCreative( new AdCreative() .setFieldId(\"<adCreativeID>\") ) .setStatus(Ad.EnumStatus.VALUE_PAUSED) .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_ACCOUNT_ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) ads = ad_account.ads.create({ name: 'My Ad', adset_id: '<adSetID>', creative: {'creative_id':'<adCreativeID>'}, status: 'PAUSED', })

To see a preview of your ad, see our guide.

Finally, you will want to list all of the ads for an ad set within your UI. To do this, 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 in our developer documentation.

Learn more about Facebook's ad campaign structure here.