Asynchronous Batch Requests

Asynchronous batch requests allow you to make multiple Graph API calls in a single HTTP request. Facebook will schedule and process each call asynchronously and return a consolidated response to you before closing the connection.

Async batch requests share the same syntax as current batch requests, but require a name for each sub-request, do not support dependencies, and can only call the following endpoints:

Asynchronous batch requests return an async_sessions array of session IDs which can then be used to fetch each sub-request's session result.

Async batch request example

Here is an example of an async batch request containing two sub-requests; one which will succeed and one which will fail:

curl -F 'access_token=...'\
     -F 'asyncbatch=[{"method":"POST","relative_url":"{ad_id}/copies","name":"copy_ad_1","body":"adset_id=<adset_id>&status=PAUSED&rename_options={"rename_strategy":\"ONLY_TOP_LEVEL_RENAME\", "rename_suffix":\"code sample\"}"}, {"method":"POST","relative_url":"{ad_id}/copies","name":"copy_ad_2","body":"adset_id=<adset_id>&status=PAUSED&rename_options={"rename_strategy":\"ONLY_TOP_LEVEL_RENAME\", "rename_suffix":\"code sample\"}"}]' 
     https://graph.facebook.com/v2.10

Here's the example response:

{ 
  "async_sessions":[  
    {  
       "id":"{session_id}",
       "name":"add_campaign_1"
    },
    {  
      "id":"{session_id}",
      "name":"add_campaign_2"
    }
 ]
}

Once you have the async_sessions array, you can use each sub-request's id to fetch the session result.

Failed session return result :

{
  "error_code": 273,
  "exception": "(#273) This Ads API call requires the user to be admin of the ad account. User is not admin on ad account {ad_account_id}.",
  "result": "{\"error\":{\"message\":\"(#273) This Ads API call requires the user to be admin of the ad account. User is not admin on ad account {ad_account_id}.\",\"type\":\"OAuthException\",\"code\":273,\"fbtrace_id\":\"HYKr+qPYIFA\"}}",
  "complete_time": "2017-02-14T23:29:17+0000",
  "method": "POST",
  "percent_completed": 100,
  "platform_version": "V2_10",
  "start_time": "2017-02-14T23:29:16+0000",
  "status": "FAILED",
  "uri": "https://graph.facebook.com/{ad_account_id}/campaigns",
  "name": "add_campaign_1",
  "id": "{async_session_id}"
}

Succeeded session return result:

{
  "error_code": 0,
  "result": "{\"id\":\"6063797281542\"}",
  "complete_time": "2017-02-15T03:27:42+0000",
  "method": "POST",
  "percent_completed": 100,
  "platform_version": "V2_10",
  "start_time": "2017-02-15T03:27:39+0000",
  "status": "COMPLETED",
  "uri": "https://graph.facebook.com/{ad_account_id}/campaigns",
  "name": "add_campaign_2",
  "id": "{async_session_id}"
}

Invalidated Async Batch Requests

When a sub-request is not supported, the Graph API will throw a GraphAsyncBatchException exception:

{  
   "error":{  
      "message":"user_feed cannot be called asynchronously",
      "type":"GraphAsyncBatchException",
      "fbtrace_id":"EeTe1WpUods"
   }
}

Specifying Dependencies

By default, the operations specified in async batch API request are independent. They can be executed in arbitrary order on the server and an error in one operation does not affect execution of other operations. We also support dependency and the syntax is the same with Batch API, except each request can only specific one dependency. There are two ways to define dependencies in async batch: Using depends_on on sub-requests to specify the request name depend on and by using a JSONPath expression.

curl -F 'access_token=...'
     -F 'asyncbatch=[{"method":"POST","relative_url":"{ad_id}/copies","name":"copy_ad_1","body":"..."}, {"method":"POST", "relative_url":"{ad_id}/copies", "name":"copy_ad_2", "depends_on":"copy_ad_1","body":"..."}]'
     https://graph.facebook.com/v2.10

Webhooks Update for Async Session

We support sending Webhooks to clients once the async session has finished. Learn more about subscribing to webhooks and the received update format.