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. Sessions have a one week TTL (time to live).

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:

Sample Request

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

Sample 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}"
}

Async Ad Creative Creation

Here is an example of an async request for Ad Creative creation with object_story_spec:

curl -F 'access_token={access_token}'\
     -F 'asyncbatch=[{
          "method":"POST",
          "relative_url":"act_{ad_account_id}/adcreatives",
          "name":"My Async Ad Creative",
          "body":"object_story_spec={\"link_data\": {\"link\": \"www.link.com\",\"message\": \"test Message\",\"name\": \"test Name \",\"image_hash\":\"{image_hash}\"},\"page_id\": \"{page_id}\"}"}]' \
     https://graph.facebook.com/v2.12

Here is an example of an async request for Ad Creative creation with an existing Post:

curl -F 'access_token={access_token}'\
     -F 'asyncbatch=[{
          "method":"POST",
          "relative_url":"act_{ad_account_id}/adcreatives",
          "name":"My Async Ad Creative",
          "body":"body=test & object_story_id={page_id}_{post_id}"
      }]'\
     https://graph.facebook.com/v2.12

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"
   }
}

Getting Async Session IDs

You can get a list of async session IDs by querying the async_sessions edge on the Ad Account:

curl -G -d "access_token={access_token}" \
     https://graph.facebook.com/v2.12/act_{ad_account_id}/async_sessions

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.