FB Video Ads

Prerequisites

Publishing a video to an Ad Market account requires an appropriate access token and permissions. While testing you can easily generate tokens and grant your app permissions by using the Graph API Explorer. Refer to our Get Started guide for this.

When your app is ready for production, implement Facebook Login to get tokens and permissions from your app users. This guide assumes you have implemented the required components and successfully followed the Get Started guide.

For a user who can perform tasks on an ad account, you will need to implement Facebook Login to ask for the following permissions and receive a user access token:

• ads_read
• ads_management

If using a business system user in your API requests, note that uploading videos to business accounts is not yet supported.

Your app user must be able to perform the CREATE_CONTENT task on the ad account in the API requests.

Best Practices

Upload Video Ads

Publishing video ads involves the Resumable (non-chunking) protocol.

Video Specifications

Step 1: Initialize Upload Session

To initialize a video upload session, send a POST request to the /act_<PAYMENT_ACCOUNT_ID>/video_ads endpoint with the upload_phase parameter set to start.

Example Request

curl -X POST "https://graph.facebook.com/v25.0/act_<PAYMENT_ACCOUNT_ID>/video_ads" \
  -F "upload_phase=start" \
  -F "access_token=<ACCESS_TOKEN>"

On success, your app receives a JSON response with the ID for the video and the Facebook URL for uploading the video. This video ID will be used in subsequent steps.

Example Response

{
  "video_id": "<VIDEO_ID>",
  "upload_url": "https://rupload.facebook.com/video-ads-upload/v25.0/<VIDEO_ID>",
}      

Step 2: Upload Video

The video you want to upload can either be a local file on your device or a URL. If using a URL, it must be hosted on a public facing http/https server, such as a CDN.

Upload a local file

To upload a local file, send a POST request to the upload_url endpoint you received in step 1 with the following parameters:

• offset set to 0
• file_size set to the total size in bytes of the video being uploaded

Example Request

curl -X POST "https://rupload.facebook.com/video-ads-upload/v25.0/<VIDEO_ID>" \
  -H "Authorization: OAuth <ACCESS_TOKEN>" \
  -H "offset: 0" \
  -H "file_size: 73400320" \
  --data-binary "@/path/to/file/my_video_file.mp4"

On success, your app receives a JSON response with the ID for the video and the Facebook URL for uploading the video. This video ID will be used in subsequent steps.

Example Response

{
    "success": true
}

Headers

Resume Interrupted File Upload

If the video upload is interrupted, it can be resumed by repeating the POST request with offset set to the bytes_transfered value from a GET /status endpoint. You can also restart the upload by setting the offset to 0. This can be done by first retrieving the upload byte offset from the status endpoint, and then uploading the remaining bytes using the upload URL.

The offset header should be set to the offset/bytes_transferred value received from the status endpoint, or set to 0 to restart from the beginning of the upload. The file bytes sent in the subsequent request should start with the byte at “offset” (zero-based).

Upload Hosted Files

This method can be used when the video to upload is hosted on a public facing http/https server, such as a CDN.

Example Request

curl -X POST "https://rupload.facebook.com/video-ads-upload/v25.0/<VIDEO_ID>" \
  -H "Authorization: OAuth <ACCESS_TOKEN>" \
  -H "file_url: https://some.cdn.url/video.mp4"

Step 3: Retrieve Upload Session Status (Optional)

You can retrieve the status of a publishing operation by sending a GET request for the status field on the video.

• Host: graph.facebook.com
• Endpoint: /v25.0/<VIDEO_ID>?fields=status

Response

The response will be a JSON object that includes a status field. The status field will include the following nested fields:

Example Request

curl -X GET "https://graph.facebook.com/v25.0/<VIDEO_ID>" \
  -H "Authorization: OAuth <ACCESS_TOKEN" \
  -d "fields=status"

Example Response

{
  "status": {
    "video_status": "processing", // ready, processing, expired, error
    "uploading_phase": {
      "status": "in_progress", // not_started, in_progress, complete, error
      "bytes_transfered": 50002  // bytes received (also 'offset')
    },
    "processing_phase": {
      "status": "not_started"
    }
    "publishing_phase": {
      "status": "not_started",
      "publish_status": "publish",
      "publish_time": 234523452 // publish time (unix)
    }
  }
}

Step 4: Publish Video to Ad Account

When you end the upload session, we will encode the video and publish it to the ad account. To end the upload session and publish your video, send a POST request to video_ads endpoint on the corresponding ad account node.

• Host: graph.facebook.com
• Endpoint: /v25.0/act_<PAYMENT_ACCOUNT_ID>/video_ads

The response will be a JSON object that indicates whether the request was successful.

Example Request

curl -X POST "https://graph.facebook.com/video-ads-upload/v25.0/act_<PAYMENT_ACCOUNT_ID>/video_ads" \
  -F "upload_phase=finish" \
  -F 'video_id=<VIDEO_ID>' \
  -F "access_token=<ACCESS_TOKEN>"

Example Response

{
  "success": true,
}

Get Video Ads

To get a list of all videos for an ad account, send a GET request to the /act_<PAYMENT_ACCOUNT_ID>/video_ads endpoint where PAYMENT_ACCOUNT_ID is the ID for the payment account you want to view.

Example Request

curl -X GET "https://graph.facebook.com/v25.0/act_<PAYMENT_ACCOUNT_ID>/video_ads" \
  -F "access_token=<ACCESS_TOKEN>"

Example Response

{
  "data": [
    {
      "updated_time": "unix_timestamp",
      "id": "video_id",
    }
  ]
}

Filters (Optional)