The ad campaigns associated with a given ad account.
On May 1, 2018 with the release of Marketing API 3.0 we removed kpi_custom_conversion_id
, kpi_type
, and kpi_results
.
Beginning September 15, 2022, with the release of Marketing API v15.0, advertisers will no longer be allowed to create incremental conversion optimization campaigns. Existing conversion optimization campaigns will behave normally.
Beginning with the release of Marketing API v15.0, advertisers will no longer be able to create Special Ad Audiences. See Special Ad Audiences details here for more information.
Returns the campaigns under this ad account. A request with no filters returns only campaigns that were not archived or deleted.
GET /v20.0/act_<AD_ACCOUNT_ID>/campaigns?effective_status=%5B%22ACTIVE%22%2C%22PAUSED%22%5D&fields=name%2Cobjective HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
// Returns a `Facebook\FacebookResponse` object
$response = $fb->get(
'/act_<AD_ACCOUNT_ID>/campaigns?effective_status=%5B%22ACTIVE%22%2C%22PAUSED%22%5D&fields=name%2Cobjective',
'{access-token}'
);
} catch(Facebook\Exceptions\FacebookResponseException $e) {
echo 'Graph returned an error: ' . $e->getMessage();
exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
echo 'Facebook SDK returned an error: ' . $e->getMessage();
exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
"/act_<AD_ACCOUNT_ID>/campaigns",
{
"effective_status": "[\"ACTIVE\",\"PAUSED\"]",
"fields": "name,objective"
},
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Bundle params = new Bundle();
params.putString("effective_status", "[\"ACTIVE\",\"PAUSED\"]");
params.putString("fields", "name,objective");
/* make the API call */
new GraphRequest(
AccessToken.getCurrentAccessToken(),
"/act_<AD_ACCOUNT_ID>/campaigns",
params,
HttpMethod.GET,
new GraphRequest.Callback() {
public void onCompleted(GraphResponse response) {
/* handle the result */
}
}
).executeAsync();
NSDictionary *params = @{
@"effective_status": @"[\"ACTIVE\",\"PAUSED\"]",
@"fields": @"name,objective",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
initWithGraphPath:@"/act_<AD_ACCOUNT_ID>/campaigns"
parameters:params
HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
id result,
NSError *error) {
// Handle the result
}];
curl -X GET -G \
-d 'effective_status=[
"ACTIVE",
"PAUSED"
]' \
-d 'fields="name,objective"' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v20.0/act_<AD_ACCOUNT_ID>/campaigns
Parameter | Description |
---|---|
date_preset
enum{today, yesterday, this_month, last_month, this_quarter, maximum, data_maximum, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, last_week_mon_sun, last_week_sun_sat, last_quarter, last_year, this_week_mon_today, this_week_sun_today, this_year}
|
Predefine date range used to aggregate insights metrics. |
effective_status
list<enum{ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, ADSET_PAUSED, IN_PROCESS, WITH_ISSUES}>
|
Default value:
Vec
effective status for the campaigns |
is_completed
boolean
|
If |
time_range
{'since':YYYY-MM-DD,'until':YYYY-MM-DD}
|
Date range used to aggregate insights metrics |
since
datetime
|
A date in the format of "YYYY-MM-DD", which means from the beginning midnight of that day. |
until
datetime
|
A date in the format of "YYYY-MM-DD", which means to the beginning midnight of the following day. |
Reading from this edge will return a JSON formatted result:
{ "
data
": [], "paging
": {}, "summary
": {} }
summary
Aggregated information about the edge, such as counts. Specify the fields to fetch in the summary param (like summary=insights
).
Field | Description |
---|---|
insights
Edge<AdsInsights>
|
Analytics summary for all objects |
total_count
unsigned int32
|
Total number of objects |
Error | Description |
---|---|
100 | Invalid parameter |
190 | Invalid OAuth 2.0 Access Token |
2635 | You are calling a deprecated version of the Ads API. Please update to the latest version. |
80004 | There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting#ads-management. |
200 | Permissions error |
415 | Two factor authentication required. User have to enter a code from SMS or TOTP code generator to pass 2fac. This could happen when accessing a 2fac-protected asset like a page that is owned by a 2fac-protected business manager. |
80000 | There have been too many calls from this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting#ads-insights. |
2500 | Error parsing graph query |
3018 | The start date of the time range cannot be beyond 37 months from the current date |
campaigns
edge from the following paths:
POST /v20.0/act_<AD_ACCOUNT_ID>/campaigns HTTP/1.1
Host: graph.facebook.com
name=My+campaign&objective=OUTCOME_TRAFFIC&status=PAUSED&special_ad_categories=%5B%5D
/* PHP SDK v5.0.0 */
/* make the API call */
try {
// Returns a `Facebook\FacebookResponse` object
$response = $fb->post(
'/act_<AD_ACCOUNT_ID>/campaigns',
array (
'name' => 'My campaign',
'objective' => 'OUTCOME_TRAFFIC',
'status' => 'PAUSED',
'special_ad_categories' => '[]',
),
'{access-token}'
);
} catch(Facebook\Exceptions\FacebookResponseException $e) {
echo 'Graph returned an error: ' . $e->getMessage();
exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
echo 'Facebook SDK returned an error: ' . $e->getMessage();
exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
"/act_<AD_ACCOUNT_ID>/campaigns",
"POST",
{
"name": "My campaign",
"objective": "OUTCOME_TRAFFIC",
"status": "PAUSED",
"special_ad_categories": "[]"
},
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Bundle params = new Bundle();
params.putString("name", "My campaign");
params.putString("objective", "OUTCOME_TRAFFIC");
params.putString("status", "PAUSED");
params.putString("special_ad_categories", "[]");
/* make the API call */
new GraphRequest(
AccessToken.getCurrentAccessToken(),
"/act_<AD_ACCOUNT_ID>/campaigns",
params,
HttpMethod.POST,
new GraphRequest.Callback() {
public void onCompleted(GraphResponse response) {
/* handle the result */
}
}
).executeAsync();
NSDictionary *params = @{
@"name": @"My campaign",
@"objective": @"OUTCOME_TRAFFIC",
@"status": @"PAUSED",
@"special_ad_categories": @"[]",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
initWithGraphPath:@"/act_<AD_ACCOUNT_ID>/campaigns"
parameters:params
HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
id result,
NSError *error) {
// Handle the result
}];
curl -X POST \
-F 'name="My campaign"' \
-F 'objective="OUTCOME_TRAFFIC"' \
-F 'status="PAUSED"' \
-F 'special_ad_categories=[]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v20.0/act_<AD_ACCOUNT_ID>/campaigns
adlabels
Ad Labels associated with this campaign
Choose bid strategy for this campaign to suit your specific business goals.
Each strategy has tradeoffs and may be available for certain optimization_goal
s:
LOWEST_COST_WITHOUT_CAP
: Designed to get the most results for your budget based on
your ad set optimization_goal
without limiting your bid amount. This is the best strategy
if you care most about cost efficiency. However with this strategy it may be harder to get
stable average costs as you spend. This strategy is also known as automatic bidding
.
Learn more in Ads Help Center, About bid strategies: Lowest cost
.
LOWEST_COST_WITH_BID_CAP
: Designed to get the most results for your budget based on
your ad set optimization_goal
while limiting actual bid to your specified
amount. With a bid cap you have more control over your
cost per actual optimization event. However if you set a limit which is too low you may
get less ads delivery. If you select this, you must provide
a bid cap in the bid_amount
field for each ad set in this ad campaign.
Note: during creation this is the default bid strategy if you don't specify.
This strategy is also known as manual maximum-cost bidding
.
Learn more in Ads Help Center, About bid strategies: Lowest cost
.
Notes:
bid_strategy
at ad set level.TARGET_COST
bidding strategy has been deprecated with Marketing API v9
.budget_schedule_specs
Initial high demand periods to be created with the campaign.
Provide list of time_start
, time_end
, budget_value
, and budget_value_type
.
For example,
-F 'budget_schedule_specs=[{
"time_start":1699081200,
"time_end":1699167600,
"budget_value":100,
"budget_value_type":"ABSOLUTE"
}]'
See High Demand Period
for more details on each field.
id
time_start
time_end
budget_value
budget_value_type
recurrence_type
weekly_schedule
days
minute_start
minute_end
timezone_type
buying_type
AUCTION
This field will help Facebook make optimizations to delivery, pricing, and limits. All ad sets in this campaign must match the buying type. Possible values are:
AUCTION
(default)
RESERVED
(for reach and frequency ads
).
campaign_optimization_type
campaign_optimization_type
daily_budget
Daily budget of this campaign. All adsets under this campaign will share this budget. You can either set budget at the campaign level or at the adset level, not both.
execution_options
Set
An execution setting
validate_only
: when this option is specified, the API call will not perform the mutation but will run through the validation rules against values of each field.
include_recommendations
: this option cannot be used by itself. When this option is used, recommendations for ad object's configuration will be included. A separate section recommendations
will be included in the response, but only if recommendations for this specification exist.
If the call passes validation or review, response will be {"success": true}
. If the call does not pass, an error will be returned with more details. These options can be used to improve any UI to display errors to the user much sooner, e.g. as soon as a new value is typed into any field corresponding to this ad object, rather than at the upload/save stage, or after review.
is_skadnetwork_attribution
To create an iOS 14 campaign, enable SKAdNetwork attribution for this campaign.
is_using_l3_schedule
is_using_l3_schedule
iterative_split_test_configs
Array of Iterative Split Test Configs created under this campaign .
lifetime_budget
Lifetime budget of this campaign. All adsets under this campaign will share this budget. You can either set budget at the campaign level or at the adset level, not both.
name
Name for this campaign
objective
Campaign's objective. If it is specified the API will validate that any ads created under the campaign match that objective.
Currently, with BRAND_AWARENESS
objective, all creatives should be either only images or only videos, not mixed.
See Outcome Ad-Driven Experience Objective Validation
for more information.
promoted_object
The object this campaign is promoting across all its ads. It’s required for Meta iOS 14+ app promotion (SKAdNetwork or Aggregated Event Measurement) campaign creation. Only product_catalog_id
is used at the ad set level.
application_id
The ID of a Facebook Application. Usually related to mobile or canvas games being promoted on Facebook for installs or engagement
pixel_id
The ID of a Facebook conversion pixel. Used with offsite conversion campaigns.
custom_event_type
The event from an App Event of a mobile app, not in the standard event list.
object_store_url
The uri of the mobile / digital store where an application can be bought / downloaded. This is platform specific. When combined with the "application_id" this uniquely specifies an object which can be the subject of a Facebook advertising campaign.
offer_id
The ID of an Offer from a Facebook Page.
page_id
The ID of a Facebook Page
product_catalog_id
The ID of a Product Catalog. Used with Dynamic Product Ads .
product_item_id
The ID of the product item.
instagram_profile_id
The ID of the instagram profile id.
product_set_id
The ID of a Product Set within an Ad Set level Product Catalog. Used with Dynamic Product Ads .
event_id
The ID of a Facebook Event
offline_conversion_data_set_id
The ID of the offline dataset.
fundraiser_campaign_id
The ID of the fundraiser campaign.
custom_event_str
The event from an App Event of a mobile app, not in the standard event list.
mcme_conversion_id
The ID of a MCME conversion.
conversion_goal_id
The ID of a Conversion Goal.
offsite_conversion_event_id
The ID of a Offsite Conversion Event
boosted_product_set_id
The ID of the Boosted Product Set within an Ad Set level Product Catalog. Should only be present when the advertiser has opted into Product Set Boosting.
lead_ads_form_event_source_type
The event source of lead ads form.
value_semantic_type
The semantic of the event value to be using for optimization
omnichannel_object
app
pixel
onsite
whatsapp_phone_number
source_campaign_id
Used if a campaign has been copied. The ID from the original campaign that was copied.
special_ad_categories
special_ad_category_country
spend_cap
A spend cap for the campaign, such that it will not spend more than this cap. Defined as integer value of subunit in your currency with a minimum value of $100 USD (or approximate local equivalent). Set the value to 922337203685478 to remove the spend cap. Not available for Reach and Frequency or Premium Self Serve campaigns
start_time
start_time
status
Only ACTIVE
and PAUSED
are valid during
creation. Other statuses can be used for update. If it is set to PAUSED
, its active child objects will be paused and have an effective
status CAMPAIGN_PAUSED
.
stop_time
stop_time
topline_id
Topline ID
id
in the return type.id
: numeric string,success
: bool,Error | Description |
---|---|
100 | Invalid parameter |
200 | Permissions error |
190 | Invalid OAuth 2.0 Access Token |
2635 | You are calling a deprecated version of the Ads API. Please update to the latest version. |
80004 | There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting#ads-management. |
368 | The action attempted has been deemed abusive or is otherwise disallowed |
300 | Edit failure |
2615 | Invalid call to update this adaccount |
2625 | The request for a reach frequency campaign is invalid. |
/act_{ad_account_id}/campaigns
. Parameter | Description |
---|---|
before_date
datetime
|
Set a before date to delete campaigns before this date |
delete_strategy
enum{DELETE_ANY, DELETE_OLDEST, DELETE_ARCHIVED_BEFORE}
|
Delete strategy Required
|
object_count
integer
|
Object count |
objects_left_to_delete_count
: unsigned int32,deleted_object_ids
: List [ Error | Description |
---|---|
368 | The action attempted has been deemed abusive or is otherwise disallowed |