Marketing API Version

Asynchronous and Batch Requests

You can use asynchronous requests to create ads, so your app can send numerous ads requests without having to block. Either specify a URL to be called after the request is complete or check the status of the request. See how to create async adgroup requests here.

The most efficient way to manage ads with Marketing API is via batched requests. Use batched request to perform some of the more common requests.

Asynchronous Requests

For example, to get the status of the asynchronous request set

curl –G \
-d "access_token=___" \
-d "fields=<comma separated list of fields>"\
"https://graph.facebook.com/<API_VERSION>/<REQUEST_SET_ID>"  

This returns the overall status for the async request set as a JSON object with following. Not all fields are returned by default. If you want your query to include any non-default fields, specify the field in the fields query parameters, such as fields=id,owner_id,name,total_count,success_count,error_count,is_completed.

Name Type Description Shown by default

id

int

The id of current async request set

yes

owner_id

int

Which object owns this async request set. For async ads, the owner_id will be the account id.

yes

name

string

Name of this async request set

yes

is_completed

bool

Are all async requests inside this set completed?

yes

total_count

int

The total requests count of this request set

no

initial_count

int

The number of requests that have not been served yet

no

in_progress_count

int

The number of requests that are in progress

no

success_count

int

The number of requests that are finished and succeed

no

error_count

int

The number of requests that are finished and failed

no

canceled_count

int

The number of requests that are canceled by user

no

notification_uri

string

The notification URI for this async request set.

no

notification_mode

string

Different way to receive notification. Following are valid values:


OFF – No need to send notification


ON_COMPLETE – Send notification when the whole set is done.

no

After you get the overall status of the async request set, get details of each request inside this async request set:

curl –G \   
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
-d "status=SUCCESS,ERROR" \
"https://graph.facebook.com/<API_VERSION>/<REQUEST_SET_ID>/requests" 

This returns details of each async request inside the async request set. For async ad creation, make one request to create one ad. To check status and detailed results, you can use this API. The status param is used to filter requests by its own status and can be any combination of following values:

  • initial – Not processed yet.
  • in_progress – The request is in processing
  • success – The request is finished and succeeds.
  • error – The request is finished and failed
  • canceled – The request is cancelled by user

The response is a JSON array, however not all the fields are shown by default. To include any non-default field, specify it in the query param, such as fields=id,scope_object_id,status,result,input,async_request_set.

Name Type Description Shown by default

id

int

The id of the individual async request

yes

scope_object_id

int

The parent id of the object this request would be creating. In async ad case, this will be ad set ID for the ad to create

yes

status

string

Status of this async request. Following are possible values:


Initial – Not processed yet


In_progress – The request is in processing


Success – The request is finished and succeeds


Error – The request is finished and failed


Canceled – The request is cancelled by user

yes

result

array

If the request is finished, this field will show the result of the request.
For success case, the result should be the same as non-async API. For example, for async ad creation, the result for each request will be id of the created ad. For error case, it will be array of following:


error_code – The error code returned


error_message – The error message

no

input

object

The original input for this async request. In async ad scenario, the input will be adgroup_spec.

no

async_request_set

object

The async request set that contains this individual request

no

Get details of an async request

To get details of a specific async request, you can call following API:

curl –G \
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
"https://graph.facebook.com/<API_VERSION>/<REQUEST_ID>"

This returns a JSON object with fields listed in the section above.

List async ad request sets for one adaccount

You can create multiple async ad request sets. To query all async ad request sets under an ad account, you can call following:

curl –G \ 
-d "access_token=___" \
-d "is_completed=1" \
–d "fields=<comma separated list of fields>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/asyncadgrouprequestsets"

Returns a JSON array of async request set objects. Each object is the same as specified in the async request set section. You can filter results with is_completed param. If is_completed=true, you see only completed async request set.

List async ad requests for one ad set

You can make an async call to create ads in different ad sets. To get the ad creation status for each ad set, call to get all async ad creation requests belonging to one ad set:

curl –G \
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
-d "statuses=SUCCESS,ERROR" \
"https://graph.facebook.com/<API_VERSION>/<AD_SET_ID>/asyncadgrouprequests" 

This returns a JSON array of async request objects. The status, fields filter and async request fields are the same as https://graph.facebook.com/&lt;API_VERSION>/&lt;REQUEST_SET_ID>/requests API


Update async request sets

Name, notification_uri and notification_mode can be changed for an async request set.

curl \
-F "access_token=___" \
-F "name=set_name" \
-F "notification_uri=https://some.com/new_callback" \
-F "notification_mode=OFF" \
"https://graph.facebook.com/<API_VERSION>/<REQUEST_SET_ID>" 

You can only change notification_uri and notification_mode before the notification is sent. It will return true if it successfully updates the async request set.


Cancelling

You can cancel an async request; the request can only be cancelled if it is not processed yet.

curl –XDELETE "https://graph.facebook.com/<API_VERSION>/<REQUEST_ID>" \
-F "access_token=___"  

Returns true if it successfully cancel the request.

You can also cancel the whole async request set. This cancels any unprocessed requests inside the request set:

curl –XDELETE "https://graph.facebook.com/<API_VERSION>/<REQUEST_SET_ID>" \
-F "access_token=___"

Returns true if it successfully cancels the async request set.


Async Examples

Getting status of a specific async request:

//pretty=true for command line readable output
curl -G \
-d "id=6012384857989" \
-d "pretty=true" \
-d "access_token=_____" \
"https://graph.facebook.com/<API_VERSION>/"

Return values:

{
   "id": "6012384857989",
   "owner_id": 12345,
   "name": "testasyncset",
   "is_completed": true
}

Getting results of requests:

curl -G \
-d "id=6012384857989" \
-d "pretty=true" \
-d "fields=result" \
-d "access_token=_____" \
"https://graph.facebook.com/<API_VERSION>/requests"

Return values:

{
   "data": [
      {
         "result": {
            "id": "6012384860989"
         },
         "id": "6012384858389"
      },
      {
         "result": {
            "id": "6012384858789"
         },
         "id": "6012384858189"
      }
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

Getting a list of request sets for an ad account:

curl -G \
-d "is_completed=1" \
-d "pretty=true" \
-d "access_token=___" \
"https://graph.facebook.com/<API_VERSION>/act_71597454/asyncadgrouprequestsets"

Return values:

{
   "data": [
      {
         "id": "6012384253789",
         "owner_id": 71597454,
         "name": "testasyncset",
         "is_completed": true
      },
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

Getting a list of requests for a campaign:

curl -G \
-d "status=SUCCESS,ERROR" \
-d "pretty=true" \
-d "access_token=___" \
"https://graph.facebook.com/<API_VERSION>/6008248529789/asyncadgrouprequests"

Return values:

{
   "data": [
      {
         "id": "6012384951789",
         "scope_object_id": 6008248529789,
         "status": "SUCCESS"
      },
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

Batch Requests

With batched requests, combine a number of Graph API calls into the one HTTP request. Marketing API split this request into its constituent requests. This makes batched requests the most efficient way of interacting with the Marketing API. For even greater efficiency you can make parallel batch requests using separate processing threads.

Note: Each batched request can contain a maximum of 50 requests. For ad creation you should only have 10 or less ads per batch.

Batch requests for ads, adcreatives and ad sets are very similar so we don't discuss them separately here. For more information, see Graph API batch requests and ETags.

Creating Ads

You can provide adcreative and other ad objects in a batched request. For example, you can create three ads using one adcreative and three different targeting specs. Define your Ad Creative first then reference it when you create each ad:

curl -F 'access_token=______' 
  -F 'test1=@./test1.jpg'  
  -F 'batch=[
             {
              "method": "POST",
              "name": "create_creative",
              "relative_url": "<API_VERSION>/act_187687683/adcreatives",
              "attached_files": "test1",
              "body": "title=Test title&amp;body=Test body&amp;link_url=http://www.test12345.com&amp;image_file=test1.jpg"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&amp;redownload=1&amp;optimization_goal=REACH&amp;billing_event=IMPRESSIONS&amp;bid_amount=150&amp;creative={\"creative_id\":\"{result=create_creative:$.id}\"}&amp;targeting={\"countries\":[\"US\"]}&amp;name=test1"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&amp;redownload=1&amp;optimization_goal=REACH&amp;billing_event=IMPRESSIONS&amp;bid_amount=150&amp;creative={\"creative_id\":\"{result=create_creative:$.id}\"}&amp;targeting={\"countries\":[\"GB\"]}&amp;name=test2"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&amp;redownload=1&amp;optimization_goal=REACH&amp;billing_event=IMPRESSIONS&amp;bid_amount=150&amp;creative={\"creative_id\":\"{result=create_creative:$.id}\"}&amp;targeting={\"countries\":[\"IE\"]}&amp;name=test3"
             }
            ]' https://graph.facebook.com/

The response individual response codes for each request as well as the standard Graph API response. For details, see Making Multiple API Requests.

The batched request process uses the JSONPath expression format to reference the previous requests.

The next example creates three ads using two different images:

curl -F 'access_token=____' 
  -F 'test1=@./test1.jpg' 
  -F 'test2=@./test2.jpg' 
  -F 'batch=[
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "attached_files": "test1",
              "body": "adset_id=6004163746239&amp;optimization_goal=REACH&amp;billing_event=IMPRESSIONS&amp;bid_amount=150&amp;creative={\"title\":\"Test title 1\",\"body\":\"Test body 1\",\"object_url\":\"https://apps.facebook.com/testapp/\", \"image_file\":\"test1.jpg\"}&amp;targeting={\"countries\":[\"US\"]}&amp;name=test1"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "attached_files": "test2",
              "body": "adset_id=6004163746239&amp;optimization_goal=REACH&amp;billing_event=IMPRESSIONS&amp;bid_amount=150&amp;creative={\"title\":\"Test title 2\",\"body\":\"Test body 2\",\"object_url\":\"https://apps.facebook.com/testapp/\", \"image_file\":\"test2.jpg\"}&amp;targeting={\"countries\":[\"US\"]}&amp;name=test2"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "attached_files": "test1",
              "body": "adset_id=6004163746239&amp;optimization_goal=REACH&amp;billing_event=IMPRESSIONS&amp;bid_amount=150&amp;creative={\"title\":\"Test title 3\",\"body\":\"Test body 3\",\"object_url\":\"https://apps.facebook.com/testapp/\", \"image_file\":\"test1.jpg\"}&amp;targeting={\"countries\":[\"US\"]}&amp;name=test3"
             }
           ]' https://graph.facebook.com

Updating Ads

Ads can also be updated via a batch request. To updates bids for three ads:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/6004251715639",
              "body": "redownload=1&amp;bid_amount=100"
             },
             {
              "method": "POST",
              "relative_url": <API_VERSION>/v6004251716039",
              "body": "redownload=1&amp;bid_amount=100"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/6004251715839",
              "body": "redownload=1&amp;bid_amount=100"
             }
            ]' https://graph.facebook.com

By including redownload=1 in the relative URL you the full ad specification including the ad id to help identify which ads were updated.

To update ad creative, specify the entire creative, or provide a new creative id. This is because Ad Creatives cannot be edited after they have been created except for name and run status.

Read ads

If you have a large number of ads, split the request over multiple requests within a batched request:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/?ids=6003356308839,6004164369439&amp;fields=<comma separated list of fields>"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6003356307839/ads&amp;fields=<comma separated list of fields>"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_187687683/ads?adset_ids=[6003356307839, 6004164259439]&amp;fields=<comma separated list of fields>"
             }
            ]' https://graph.facebook.com

6003356308839 and 6004164369439 are ad ids and 6003356307839 and 6004164259439 are ad set ids.


Ad Insights

If you have a large number of Ad Insights split the request over multiple requests within a batched request:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_19643108/insights?filtering=[{field:'ad.id',operator:'IN',value:[6003356308839,6004164369439]}]"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6003356308839/insights"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_187687683/insights?filtering=[{field:'adset.id',operator:'IN',value:[6003356307839, 6004164259439]}]"
             }
            ]' https://graph.facebook.com

In this example 6003356308839 and 6004164369439 are ad ids and 6003356307839 and 6004164259439 are ad set ids.

For Ad accounts with a large number of ads using act_&lt;account_ID>/adgroupstats is not recommended as it may cause the request to timeout.

Batch requests for Reach Estimate

You can request up to 50 reach estimates in a single batched request. For example, to get the reach estimate for three different ads at the one time:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6003356308839/reachestimate"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6004164369439/reachestimate"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6004017499039/reachestimate"
             }
            ]' https://graph.facebook.com

The following example shows the reach estimate being requested for 3 different targeting specs:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_600335/reachestimate?currency=USD&amp;targeting_spec={'countries':['US']}"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_600335/reachestimate?currency=USD&amp;targeting_spec={'countries':['FR']}"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_600335/reachestimate?currency=USD&amp;targeting_spec={'countries':['US'],'zips':['94402']}"
             }
            ]' https://graph.facebook.com

ETags

Use ETags with batch queries to check if anything has changed since the last time you made the batch request, see Using ETags.

Batch API

Currently in closed beta and only available to whitelisted developers.

Batch API enables you batch requests and send them asynchronously. Group several Graph API calls into one HTTP request, and execute them asynchronously without having to block. You can also specify dependencies between related operations. Facebook processes each independent operation in parallel processes and your dependent operations sequentially. Each API call can have a maximum of 1000 requests.

Making a Batch API call

To make a Batch API call:

curl \
-F "access_token=___" \
-F "name=asyncbatchreqs" \
-F "adbatch=<an array of requests>"\
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/async_batch_requests"  

Provide an array of HTTP requests as JSON arrays. Each request has:

  • name,
  • relative_url - portion of URL after graph.facebook.com,
  • optional headers array - corresponds to HTTP headers and
  • optional body - for POST and PUT.

The API returns an id you use to query the progress of requests.

For example, create a campaign with an ad set with JSONPath Format to reference the previous requests:

curl \
-F "access_token=___" \
-F "name=batchapiexample" \
-F "adbatch=[
  {
    'name': 'create-campaign',
    'relative_url': 'act_123456/campaigns',
    'body': 'name%3DTest+Campaign%26objective%3DLINK_CLICKS%26status%3DPAUSED%26buying_type%3DAUCTION',
  },
  {
    'name': 'create-adset',
    'relative_url': 'act_123456/adsets',
    'body': 'targeting%3D%7B%22geo_locations%22%3A%7B%22countries%22%3A%5B%22US%22%5D%7D%7D%26daily_budget%3D5000%26campaign_id%3D%7Bresult%3Dcreate-campaign%3A%24.id%7D%26bid_amount%3D2%26name%3DFirst%2BAd%2BSet%20Test%26billing_event%3DLINK_CLICKS',
  },
]" \
https://graph.facebook.com/<API_VERSION>/act_123456/async_batch_requests

To get a request set status:

curl –G \
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
"https://graph.facebook.com/<API_VERSION>/<REQUEST_SET_ID>"  

This returns overall status for async request sets as JSON objects. Not all fields are returned by default; to include them, specify the field in query parameters, such as fields=id,owner_id,name,total_count,success_count,error_count,is_completed

Name Type Description Shown by default

id

int

The id of current async request set

yes

owner_id

int

Which object owns this async request set. For async ads, the owner_id will be the account id.

yes

name

string

Name of this async request set

yes

is_completed

bool

All async requests inside this set complete

yes

total_count

int

Total requests count for this request set

no

initial_count

int

Number of requests not served yet

no

in_progress_count

int

Number of requests that are in progress

no

success_count

int

Number of requests that are finished and succeed

no

error_count

int

Number of requests that are finished and failed

no

canceled_count

int

Number of requests that are canceled by user

no

notification_uri

string

Notification URI for this async request set.

no

notification_mode

string

Ways to receive notification. Following are valid values:


OFF – No need to send notification


ON_COMPLETE – Send notification when the whole set is done.

no

notification_result

string

Result of the notification sending.

no

notification_status

string

Status of the notification. Valid values are one of the followings: {not_sent, sending, sent}

no

After you get overall status, you can get details for each request in the set:

curl –G \   
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
"https://graph.facebook.com/<API_VERSION>/<REQUEST_SET_ID>/requests" 

This returns details of each async request as a JSON array. To include non-default fields, specify it in your query, such as fields=id,scope_object_id,status,result,input,async_request_set.

Name Type Description Shown by default

id

int

ID of the individual async request

yes

scope_object_id

int

Parent id of the object this request would be creating. In async ad case, this will be ad set ID for the ad to create

yes

status

string

Status of this async request. Following are possible values:


Initial – Not processed yet


In_progress – Request is in processing


Success – Request is finished and succeeds


Error – Request is finished and failed


Canceled – Request is cancelled by user

yes

result

array

If request finishes, show result of request. For success, the result is same as non-async API. For example, for async ad creation, result is new ad id. For errors, the array can have:


error_code – Error code returned


error_message – Error message

no

input

object

Original input for this async request. In async ad scenario, the input will be adgroup_spec.

no

async_request_set

object

Async request set containing this request

no

List Batch API request sets for an ad account

You can create multiple Batch API request sets. To query all request sets under an ad account, you can call following:

curl –G \ 
-d "access_token=___" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/async_requests"