Version API du graphe

Ad Account, Ad Campaigns

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.

Ads About Social Issues, Elections, and Politics

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.

Lecture

Returns the campaigns under this ad account. A request with no filters returns only campaigns that were not archived or deleted.

Exemple

Graph API Explorer

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

Pour apprendre à utiliser l’API Graph, consultez notre guide Utiliser l’API Graph.

Paramètres

Paramètre	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}>	Par défaut : `Vec` effective status for the campaigns
`is_completed` boolean	If `true`, we return completed campaigns.
`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.

Champs

La lecture à partir de cette arête renverra un résultat au format JSON :

{
    "data": [],
    "paging": {},
    "summary": {}
}

`data`

Une liste de nœuds Campaign.

`paging`

Pour plus de détails à propos de la pagination, voir Guide de l’API Graph.

`summary`

Informations agrégées relatives à l’arête, par exemple le nombre. Indiquez les champs à récupérer dans le paramètre récapitulatif (par exemple récapitulatif=insights).

Champ Description

Champ	Description
`insights` Edge<AdsInsights>	Analytics summary for all objects
`total_count` unsigned int32	Total number of objects Par défaut

insights

Edge<AdsInsights>

Analytics summary for all objects

total_count

unsigned int32

Total number of objects

Par défaut

Error Codes

Erreur	Description
100	Invalid parameter
190	Invalid OAuth 2.0 Access Token
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.
2635	You are calling a deprecated version of the Ads API. Please update to the latest version.
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.
2642	Invalid cursors values
2500	Error parsing graph query
3018	The start date of the time range cannot be beyond 37 months from the current date

Création

You can make a POST request to campaigns edge from the following paths:

/act_{ad_account_id}/campaigns

When posting to this edge, a Campaign will be created.

Exemple

Graph API Explorer

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

Pour apprendre à utiliser l’API Graph, consultez notre guide Utiliser l’API Graph.

Paramètres

Paramètre	Description
`adlabels` list<Object>	Ad Labels associated with this campaign
`bid_strategy` 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 `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: If you do not enable campaign budget optimization, you should set `bid_strategy` at ad set level. `TARGET_COST` bidding strategy has been deprecated with Marketing API v9.
`budget_schedule_specs` list<JSON or object-like arrays>	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` int64
`time_start` datetime
`time_end` datetime
`budget_value` int64
`budget_value_type` enum{ABSOLUTE, MULTIPLIER}
`recurrence_type` enum{ONE_TIME, WEEKLY}
`weekly_schedule` list<JSON or object-like arrays>
`days` list<int64>
`minute_start` int64
`minute_end` int64
`timezone_type` string
`buying_type` string	Par défaut : `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` 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}>	Par défaut : `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` 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. 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` 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` int	The ID of a Facebook Application. Usually related to mobile or canvas games being promoted on Facebook for installs or engagement
`pixel_id` numeric string or integer	The ID of a Facebook conversion pixel. Used with offsite conversion campaigns.
`custom_event_type` enum{AD_IMPRESSION, RATE, TUTORIAL_COMPLETION, CONTACT, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, SCHEDULE, START_TRIAL, SUBMIT_APPLICATION, SUBSCRIBE, ADD_TO_CART, ADD_TO_WISHLIST, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE, LEAD, COMPLETE_REGISTRATION, CONTENT_VIEW, SEARCH, SERVICE_BOOKING_REQUEST, MESSAGING_CONVERSATION_STARTED_7D, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, SPENT_CREDITS, LISTING_INTERACTION, D2_RETENTION, D7_RETENTION, OTHER}	The event from an App Event of a mobile app, not in the standard event list.
`object_store_url` 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` numeric string or integer	The ID of an Offer from a Facebook Page.
`page_id` Page ID	The ID of a Facebook Page
`product_catalog_id` numeric string or integer	The ID of a Product Catalog. Used with Dynamic Product Ads.
`product_item_id` numeric string or integer	The ID of the product item.
`instagram_profile_id` numeric string or integer	The ID of the instagram profile id.
`product_set_id` numeric string or integer	The ID of a Product Set within an Ad Set level Product Catalog. Used with Dynamic Product Ads.
`event_id` numeric string or integer	The ID of a Facebook Event
`offline_conversion_data_set_id` numeric string or integer	The ID of the offline dataset.
`fundraiser_campaign_id` numeric string or integer	The ID of the fundraiser campaign.
`custom_event_str` string	The event from an App Event of a mobile app, not in the standard event list.
`mcme_conversion_id` numeric string or integer	The ID of a MCME conversion.
`conversion_goal_id` numeric string or integer	The ID of a Conversion Goal.
`offsite_conversion_event_id` numeric string or integer	The ID of a Offsite Conversion Event
`boosted_product_set_id` numeric string or integer	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` enum{inferred, offsite_crm, offsite_web, onsite_crm, onsite_web}	The event source of lead ads form.
`value_semantic_type` enum {VALUE, MARGIN, LIFETIME_VALUE}	The semantic of the event value to be using for optimization
`variation` enum {OMNI_CHANNEL_SHOP_AUTOMATIC_DATA_COLLECTION, PRODUCT_SET_AND_APP, PRODUCT_SET_AND_IN_STORE, PRODUCT_SET_AND_OMNICHANNEL, PRODUCT_SET_AND_WEBSITE}	Variation of the promoted object for a PCA ad
`omnichannel_object` Object
`app` array<JSON object>
`pixel` array<JSON object>	Obligatoire
`onsite` array<JSON object>
`whatsapp_phone_number` string
`source_campaign_id` numeric string or integer	Used if a campaign has been copied. The ID from the original campaign that was copied.
`special_ad_categories` array<enum {NONE, EMPLOYMENT, HOUSING, CREDIT, ISSUES_ELECTIONS_POLITICS, ONLINE_GAMBLING_AND_GAMING, FINANCIAL_PRODUCTS_SERVICES}>	special_ad_categories Obligatoire
`special_ad_category_country` 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 `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` datetime	stop_time
`topline_id` numeric string or integer	Topline ID

Type de retour

This endpoint supports read-after-write and will read the node represented by id in the return type.

Struct {

id: numeric string,

success: bool,

}

Error Codes

Erreur	Description
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.
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.
300	Edit failure
900	No such application exists.

Mise à jour

Vous ne pouvez pas effectuer cette opération sur ce point de terminaison.

Suppression

You can dissociate a Campaign from an AdAccount by making a DELETE request to /act_{ad_account_id}/campaigns.

Paramètres

Paramètre Description

Paramètre	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 Obligatoire
`object_count` integer	Object count

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

Obligatoire

object_count

integer

Object count

Type de retour

Struct {

objects_left_to_delete_count: unsigned int32,

deleted_object_ids: List [

numeric string

}

Error Codes

Erreur	Description
100	Invalid parameter