Marketing API Version

Ad

Reading

An ad object contains the data necessary to visually display an ad and associate it with a corresponding ad set.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
No data
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

This endpoint doesn't have any parameters.

Fields

FieldDescription

id

numeric string

The ID of this ad.

account_id

numeric string

The ID of the ad account that this ad belongs to.

ad_review_feedback

The review feedback for this ad after it is reviewed.

adlabels

Ad labels associated with this ad

adset

Ad set that contains this ad

adset_id

numeric string

ID of the ad set that contains the ad

bid_amount

int32

Bid amount for this ad which will be used in auction instead of the ad set bid_amount, if specified. Any updates to the ad set bid_amount will overwrite this value with the new ad set value.

bid_info

map<string, unsigned int32>

A dictionary of {objective}:{value} that you place on your bid, based on the bid_type of ad set.
Values are defined in your currency's minimum denomination:
For bid_type=CPM, bid_info={'IMPRESSIONS':<value>}
For bid_type=CPC, bid_info={'CLICKS':<value>}
For bid_type=ABSOLUTE_OCPM, bid_info={'ACTIONS':<value>, 'REACH':<value>, 'CLICKS':<value>, 'SOCIAL':<value>}
For bid_type=CPA, bid_info={'ACTIONS':<value>}

bid_type

enum {CPC, CPM, MULTI_PREMIUM, ABSOLUTE_OCPM, CPA}

Bid type

campaign

Ad campaign that contains this ad

campaign_id

numeric string

ID of the ad campaign that contains this ad

configured_status

enum {ACTIVE, PAUSED, DELETED, ARCHIVED}

The configured status of the ad. Prefer using 'status' instead of this.

conversion_specs

Conversion specs

created_time

datetime

Created time

creative

This field is required for create. The ID of the ad creative to be used by this ad. You can read more about creatives here. You should supply the ID within an object as follows:

{"creative_id": <CREATIVE_ID>}

effective_status

enum {ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, ADSET_PAUSED}

The effective status of the ad. The status could be effective either because of its own status, or the status of its parent units.

last_updated_by_app_id

id

Last Updated By App ID

name

string

Name of the ad.

recommendations

If there are recommendations for this ad, this field includes them. Otherwise, will not be included in the response. (This field is not included in redownload mode.)

status

enum {ACTIVE, PAUSED, DELETED, ARCHIVED}

The configured status of the ad. The field returns the same value as 'configured_status', and is the suggested one to use.

tracking_specs

Tracking specs

updated_time

datetime

Updated time

Edges

EdgeDescription

adcreatives

Creative associated with this ad

insights

Insights on advertising performance of this ad

keywordstats

Stats of keywords of this ad

previews

Preview of the ad

targetingsentencelines

The targeting description sentence for this ad

Validation Rules

ErrorDescription
100Invalid parameter
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.
278Reading advertisements requires an access token with the extended permission ads_read
273This Ads API call requires the user to be admin of the ad account
274The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API
272This Ads API call requires the user to be admin of the application
200Permissions error

Creating

You can make a POST request to adgroups edge from the following paths:
When posting to this edge, an Ad will be created.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
  • manage_pages
  • pages_show_list
Page management Apps
No data
Other Apps
No data

Parameters

NameDescription
adlabels
list<Object>

Ad labels associated with this ad

adset_id
int64

The ID of the ad set, required on creation.

adset_spec
Ad set spec

The ad set spec for this ad. When the spec is provided, adset_id field is not required.

bid_amount
integer

Bid amount for this ad which will be used in auction instead of the ad set bid_amount, if specified. Any updates to the ad set bid_amount will overwrite this value with the new ad set value.

creative
AdCreative

This field is required for create. The ID of the ad creative to be used by this ad. You can read more about creatives here. You should supply the ID within an object as follows:

{"creative_id": <CREATIVE_ID>}

RequiredSupports Emoji
date_format
string

The format of the date.

display_sequence
int64

The sequence of the ad within the same campaign

execution_options
list<enum{validate_only, synchronous_ad_review, include_recommendations}>
Default value: 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.
synchronous_ad_review: this option should not be used by itself. It should always be specified with validate_only. When these options are specified, the API call will perform Ads Integrity validations, which include message language checking, image 20% text rule, and so on, as well as the validation logics.
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.

name
string

Name of the ad.

Required
redownload
boolean

Set this value to true and the API will respond with all fields instead of just id.

status
enum{ACTIVE, PAUSED, DELETED, ARCHIVED}

Only ACTIVE and PAUSED are valid during creation. Other statuses can be used for update. When an ad is created, it will first go through ad review, and will have the ad status PENDING_REVIEW before it finishes review and reverts back to your selected status of ACTIVE or PAUSED. During testing, it is recommended to set ads to a PAUSED status so as to not incur accidental spend.

tracking_specs
Object

Tracking specs

Return Type

Struct {
id: numeric string,
success: bool,
}
You can make a POST request to ads edge from the following paths:
When posting to this edge, an Ad will be created.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
No data

Parameters

NameDescription
adlabels
list<Object>

Ad labels associated with this ad

adset_id
int64

The ID of the ad set, required on creation.

adset_spec
Ad set spec

The ad set spec for this ad. When the spec is provided, adset_id field is not required.

bid_amount
integer

Bid amount for this ad which will be used in auction instead of the ad set bid_amount, if specified. Any updates to the ad set bid_amount will overwrite this value with the new ad set value.

creative
AdCreative

This field is required for create. The ID of the ad creative to be used by this ad. You can read more about creatives here. You should supply the ID within an object as follows:

{"creative_id": <CREATIVE_ID>}

RequiredSupports Emoji
date_format
string

The format of the date.

display_sequence
int64

The sequence of the ad within the same campaign

execution_options
list<enum{validate_only, synchronous_ad_review, include_recommendations}>
Default value: 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.
synchronous_ad_review: this option should not be used by itself. It should always be specified with validate_only. When these options are specified, the API call will perform Ads Integrity validations, which include message language checking, image 20% text rule, and so on, as well as the validation logics.
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.

name
string

Name of the ad.

Required
redownload
boolean

Set this value to true and the API will respond with all fields instead of just id.

status
enum{ACTIVE, PAUSED, DELETED, ARCHIVED}

Only ACTIVE and PAUSED are valid during creation. Other statuses can be used for update. When an ad is created, it will first go through ad review, and will have the ad status PENDING_REVIEW before it finishes review and reverts back to your selected status of ACTIVE or PAUSED. During testing, it is recommended to set ads to a PAUSED status so as to not incur accidental spend.

tracking_specs
Object

Tracking specs

Return Type

Struct {
id: numeric string,
success: bool,
}
You can make a POST request to leads edge from the following paths:
When posting to this edge, an Ad will be created.

Parameters

NameDescription
end_time
datetime

Leads created before end_time will be exported

start_time
datetime

Leads created after start_time will be exported

Return Type

This endpoint supports read-after-write and will read the node represented by report_run_id in the return type.
Struct {
report_run_id: numeric string,
}
You may perform a POST request to the following edge from this node:

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
500Message contains banned content
273This Ads API call requires the user to be admin of the ad account
380There was a problem uploading your thumbnail file. Please try again.
2626The request for a reach frequency campaign has failed.
300Edit failure
294Managing advertisements requires an access token with the extended permission for ads_management
384The video you tried to upload is too long. Please try again with a shorter video.
192Invalid phone number

Updating

You can update an Ad by making a POST request to /{ad_id}.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
No data

Parameters

NameDescription
adlabels
list<Object>

Ad labels associated with this ad

adset_id
int64

The ID of the ad set, required on creation.

bid_amount
integer

Bid amount for this ad which will be used in auction instead of the ad set bid_amount, if specified. Any updates to the ad set bid_amount will overwrite this value with the new ad set value.

creative
AdCreative

This field is required for create. The ID of the ad creative to be used by this ad. You can read more about creatives here. You should supply the ID within an object as follows:

{"creative_id": <CREATIVE_ID>}

Supports Emoji
display_sequence
int64

The sequence of the ad within the same campaign

execution_options
list<enum{validate_only, synchronous_ad_review, include_recommendations}>
Default value: 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.
synchronous_ad_review: this option should not be used by itself. It should always be specified with validate_only. When these options are specified, the API call will perform Ads Integrity validations, which include message language checking, image 20% text rule, and so on, as well as the validation logics.
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.

name
string

Name of the ad.

redownload
boolean

Set this value to true and the API will respond with all fields instead of just id.

status
enum{ACTIVE, PAUSED, DELETED, ARCHIVED}

Only ACTIVE and PAUSED are valid during creation. Other statuses can be used for update. When an ad is created, it will first go through ad review, and will have the ad status PENDING_REVIEW before it finishes review and reverts back to your selected status of ACTIVE or PAUSED. During testing, it is recommended to set ads to a PAUSED status so as to not incur accidental spend.

tracking_specs
Object

Tracking specs

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
}
You may perform a POST request to the following edge from this node:

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
500Message contains banned content
273This Ads API call requires the user to be admin of the ad account
380There was a problem uploading your thumbnail file. Please try again.
2626The request for a reach frequency campaign has failed.
300Edit failure
294Managing advertisements requires an access token with the extended permission for ads_management
384The video you tried to upload is too long. Please try again with a shorter video.
192Invalid phone number

Deleting

You can delete an Ad by making a DELETE request to /{ad_id}.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
No data

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
success: bool,
}
You may perform a DELETE request to the following edge from this node:

Validation Rules

ErrorDescription
100Invalid parameter