Reels Publishing API

Limitations

Publishing Reels on Groups or Users are not available.

Video Specifications for Reels

Sharing Disclosure

When uploading a Reel, the user should be presented with disclosure of and options for control over how their Reels are used on Facebook.

Privacy / Who can see this?

User selectable choice of audience. This selection corresponds to the privacy parameter in the publishing step. Posting to a Page has implicit public scope, and only the 'Public' option should be available. A mockup of how this disclosure could appear for posting to a Page is shown below. Sharing Disclosure Mockup

Permissions

All publishing actions require an appropriate Access Token and Permissions based on the node you are targeting. While you are testing you can easily generate Tokens and grant your app Permissions by using the Graph API Explorer. Refer to our Get Started guide to see how to do this. When your app is ready for production, you will likely have to implement Facebook Login to get Tokens and Permissions from your app users.

Publishing on Pages

The app user must be an Admin of the Page you are targeting. You will need the app user's Page Access Token and they must grant your app the pages_show_list, pages_read_engagement, and pages_manage_posts permissions.

API Endpoints

The process for publishing Reels involves Resumable (non-chunking) protocol including endpoints

• Initialize an upload session: /{page-id}/video_reels?upload_phase=start
• Upload the video itself (rupload.facebook.com): rupload.facebook.com/video-upload/{api-version}/{video-id}
• Status (Optional): /{video-id}?fields=status
• Publish the video, and set metadata: /{page-id}/video_reels?upload_phase=finish

Step 1: Initialize Upload Session

To initialize a video upload session, send a POST request to the /video_reels Graph API endpoint on the corresponding page edge.

Host: graph.facebook.com

Endpoint: /{page-id}/video_reels

Response

When successful, the API response will include a “video_id” value which will be used in subsequent calls and the URLs of the endpoints for the Upload, Status and Publish steps.

Sample Request

curl -X POST \
  "https://graph.facebook.com/v13.0/{page-id}/video_reels" \
      -F "upload_phase=start" \
  -F "access_token=EAADI..."

Sample Response

{
 "video_id": "{video-id}",
 "upload_url": "https://rupload.facebook.com/video-upload/v13.0/{video-id}",
}   

Step 2: Upload the Video

There are two supported sources for uploaded videos, "Local File" and "Hosted File".

Local File Upload

This method can be used when the video file is available locally to the uploader.

To initiate the upload of the video asset, send a POST request using application/octet-stream as content type to the video-upload endpoint, including the video file in the request body.

Host: rupload.facebook.com

Endpoint: /video-upload/{api-version}/{video-id}

Sample Request

curl -X POST \
  "https://rupload.facebook.com/video-upload/v13.0/{video-id}" \
  -H "Authorization: OAuth EAADI..." \
  -H "offset: 0" \
  -H "file_size: 73400320" \
  --data-binary "@my_video_file.mp4"

Sample Response

{"success": true}

Headers

Resuming a Local File Upload (if interrupted)

If the video upload is interrupted, it can be resumed. This can be done by first retrieving the upload byte offset from the status endpoint, and then uploading the remaining bytes using the /video-upload/ endpoint.

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)

Host: rupload.facebook.com

Endpoint: /video-upload/{api-version}/{session-id}

Hosted File Upload

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

Host: rupload.facebook.com

Endpoint: /video-upload/{api-version}/{video-id}

Sample Request

curl -X POST \
  "https://rupload.facebook.com/video-upload/v13.0/{video-id}" \
  -H "Authorization: OAuth EAADI..." \
  -H "file_url: https://some.cdn.url/video.mp4"

Sample Response

{"success": true}

Headers

Step 3: (Optional) Retrieve status of Upload session

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: /{video-id}?fields=status

Sample Request

curl -G "https://graph.facebook.com/v13.0/{video-id}" \
  -H "Authorization: OAuth EAADI..."
  -d "fields=status" 

Sample Response

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

File successfully uploaded

{
  "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": "scheduled", // published, draft, scheduled
      "publish_time": 234523452 // actual or scheduled publish time (unix)
    }
  }
}

Example response with error structure in processing phase

{
  "status": {
    "video_status": "processing",
    "uploading_phase": {
      "status": "complete",
    },
    "processing_phase": {
      "status": "not_started",
      "error": {
        "message": "Resolution too low. Video must have a minimum resolution of 540p."
      }
    }
    "publishing_phase": {
      "status": "not_started",
    }
  }
}

Step 4: Publish the Reel

When you end the upload session we will reassemble the complete video, encode it, then publish it on the selected page edge. To end the upload session and publish your video, send a POST request to the video_reels Graph API endpoint on the corresponding edge.

You can also include any of the additional parameters supported by Reels like description and title.

Host: graph.facebook.com

Endpoint: /{page-id}/video_reels

Sample Request

curl -X POST \
  "https://graph.facebook.com/v13.0/{page-id}/video_reels" \
  -F 'access_token=EAADI...' \
  -F 'video_id={video-id}' \
  -F 'upload_phase=finish' \
  -F 'video_state=PUBLISHED' \
  -F 'description=What a great day. Watch until the end!'

Sample Response

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

{"success": true}

Step 5: (Optional) Retrieve the published Reels

You can access all Reels published to your page by sending a GET request to /{page-id}/video_reels.

Host: graph.facebook.com

Endpoint: /{page-id}/video_reels

Sample Request

curl -X GET \ 
  "https://graph.facebook.com/v13.0/{page-id}/video_reels" \
  -F 'access_token=EAADI...'

Sample Response

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

{
  "data": [
      {
        "updated_time": "{date}",
        "id": "{video-id}"
      },
      {
        "description": "sample_description",
        "updated_time": "{date}",
        "id": "{video-id}"
      },
      ...
    ],
    "paging": {
    "cursors": {
      "before": "{token}",
      "after": "{token}"
    },
    "next": "https://graph.facebook.com/v13.0/{page-id}/video_reels?access_token={access-token}"
}