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 /v21.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/v21.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 |
Reading from this edge will return a JSON formatted result:
{ "
data
": [], "paging
": {}, "summary
": {} }
data
paging
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. |
200 | Permissions error |
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. |
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. |
2500 | Error parsing graph query |
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. |
3018 | The start date of the time range cannot be beyond 37 months from the current date |
2642 | Invalid cursors values |
campaigns
edge from the following paths: POST /v21.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/v21.0/act_<AD_ACCOUNT_ID>/campaigns
Parameter | Description |
---|---|
adlabels list<Object> | Ad Labels associated with this campaign |
enum{LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS} | Choose bid strategy for this campaign to suit your specific business goals.
Each strategy has tradeoffs and may be available for certain Notes:
|
budget_schedule_specs list<JSON or object-like arrays> | Initial high demand periods to be created with the campaign. |
buying_type string | Default value: 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: |
campaign_optimization_type enum{NONE, ICO_ONLY} | campaign_optimization_type |
daily_budget int64 | 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 list<enum{validate_only, include_recommendations}> | Default value: Set An execution setting |
is_skadnetwork_attribution boolean | To create an iOS 14 campaign, enable SKAdNetwork attribution for this campaign. |
is_using_l3_schedule boolean | is_using_l3_schedule |
iterative_split_test_configs list<Object> | Array of Iterative Split Test Configs created under this campaign . |
lifetime_budget int64 | 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 string | Name for this campaign Supports Emoji |
objective enum{APP_INSTALLS, BRAND_AWARENESS, CONVERSIONS, EVENT_RESPONSES, LEAD_GENERATION, LINK_CLICKS, LOCAL_AWARENESS, MESSAGES, OFFER_CLAIMS, OUTCOME_APP_PROMOTION, OUTCOME_AWARENESS, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_TRAFFIC, PAGE_LIKES, POST_ENGAGEMENT, PRODUCT_CATALOG_SALES, REACH, STORE_VISITS, VIDEO_VIEWS} | Campaign's objective. If it is specified the API will validate that any ads created under the campaign match that objective. |
promoted_object 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 |
source_campaign_id numeric string or integer | Used if a campaign has been copied. The ID from the original campaign that was copied. |
array<enum {NONE, EMPLOYMENT, HOUSING, CREDIT, ISSUES_ELECTIONS_POLITICS, ONLINE_GAMBLING_AND_GAMING, FINANCIAL_PRODUCTS_SERVICES}> | special_ad_categories Required |
array<enum {AD, AE, AF, AG, AI, AL, AM, AN, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW}> | special_ad_category_country |
spend_cap int64 | 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 datetime | start_time |
status enum{ACTIVE, PAUSED, DELETED, ARCHIVED} | Only |
stop_time datetime | stop_time |
topline_id numeric string or integer | Topline ID |
id
in the return type.id
: numeric string, success
: bool, Error | Description |
---|---|
100 | Invalid parameter |
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 |
190 | Invalid OAuth 2.0 Access Token |
2635 | You are calling a deprecated version of the Ads API. Please update to the latest version. |
/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 |
---|---|
100 | Invalid parameter |