Marketing API Version
Batch Requests

In this document:

Note: The batch requests for ads, adcreatives and ad sets are very similar so will not be dealt with separately here.


Overview

The most efficient way to manage ads on the Marketing API is via batched requests. This document outlines how the batched request functionality can be used to perform some of the more common requests in the Marketing API.

Batched requests allow you to combine together a number of Graph API calls into the one HTTP request. This request is received by the Marketing API and split up into its constituent requests. This makes batched requests the most efficient way of interacting with the Marketing API.

For even greater efficiency batch requests may be made in parallel using separate processing threads.

Note: Each batched request can contain a maximum of 50 requests. For ad creation we advise creating 10 or fewer ads per batch.


Batch requests for ads

Creating an adcreative and many similar ads via a batched request

The following example shows how to create 3 ads using 1 adcreative and 3 different targeting specs.

In this example the Ad Creative is defined first and then referenced in the creation of 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&body=Test body&link_url=http://www.test12345.com&image_file=test1.jpg"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&optimization_goal=REACH&billing_event=IMPRESSIONS&bid_amount=150&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test1"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&optimization_goal=REACH&billing_event=IMPRESSIONS&bid_amount=150&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"GB\"]}&name=test2"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&optimization_goal=REACH&billing_event=IMPRESSIONS&bid_amount=150&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"IE\"]}&name=test3"
             }
            ]' https://graph.facebook.com/

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

The response for this request includes individual response codes for each request as well as the standard Graph API response. Please see the Making Multiple API Requests for a detailed explanation of the batch response.

Creating different ads via a batched request

The following example shows how to create 3 ads using 2 different images called test1.jpg and test2.jpg

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

The response for this request includes individual response codes for each request as well as the standard Graph API response. Please see the batched request documentation for a detailed explanation of the batch response.

Updating ads via a batch request.

Ads can also be updated via a batch request. The following example updates the bids for 3 ads in the one call.

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

The response for this request includes individual response codes for each request as well as the standard Graph API response. Please see the batched request documentation for a detailed explanation of the batch response.

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

Note: To update the creative of an ad the entire creative must be specified or a new creative id must be supplied. 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 to read the best option is to split the request over multiple requests within a batched request. The following example shows a number of ways of requesting ad in an efficient manner.

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

The response for this request includes individual response codes for each request as well as the standard Graph API response. Please see the batched request documentation for a detailed explanation of the batch response.

Note: In the above example 6003356308839 and 6004164369439 are ad ids and 6003356307839 and 6004164259439 are ad set ids.


Batch requests for Ad Insights

Note: The batch requests for stats for ads and ad sets are very similar so will not be dealt with separately here.

Reading ad insights

If you have a large number of Ad Insights to read the best option is to split the request over multiple requests within a batched request. The following example shows a number of ways of requesting Ad Insights in an efficient manner.

  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

The response for this request includes individual response codes for each request as well as the standard Graph API response. Please see the batched request documentation for a detailed explanation of the batch response.

Note: In the above example 6003356308839 and 6004164369439 are ad ids and 6003356307839 and 6004164259439 are ad set ids.

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


Batch requests for Reach Estimate

Querying reach estimate for an ad

If you want to get the latest reach estimate for a large number of ads the best approach is to request multiple reach estimates at once using a batched request. Up to 50 reach estimates may be requested in a single batched request.

The following example shows the reach estimate being requested for 3 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 response for this request includes individual response codes for each request as well as the standard Graph API response. Please see the batched request documentation for a detailed explanation of the batch response.

Querying reach estimates for a targeting spec

If you want to get the latest reach estimate for a large number of targeting specs the best approach is to request multiple reach estimates at once using a batched requests. Up to 50 reach estimates may be requested in a single batched requests.

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

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

The response for this request includes individual response codes for each request as well as the standard Graph API response. Please see the batched request documentation for a detailed explanation of the batch response.


ETags

ETags can be used with batch queries to check if anything has changed since the last time you made the batch request. For more on ETags please review the Using ETags documentation.