Graph API Version

Page Videos

Videos for a Facebook Page.

A Page Access Token is required for all methods.

You can't delete or update videos using this edge, however you can do this using the /video-id node.

Please visit the Page Feed Reference doc for information on uploading a video without publishing it.

Reading

Feature Permissions

NameDescription
Page Public Content AccessThis feature permission may be required.

Gets a list of Videos on a Page.

Permissions

The source field will no longer be returned for Page-owned videos unless the User making the request is an admin of the owning Page.

Example

Graph API Explorer
GET /v4.0/{page-id}/videos HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{page-id}/videos',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/{page-id}/videos",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{page-id}/videos",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{page-id}/videos"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

ParameterDescription
type
enum{tagged, uploaded}
Default value: uploaded

Allows you to query which type of videos to return

Fields

Reading from this edge will return a JSON formatted result:

{ "data": [], "paging": {} }

data

A list of Video nodes.

paging

For more details about pagination, see the Graph API guide.

Validation Rules

ErrorDescription
100Invalid parameter
80001There have been too many calls to this Page account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
200Permissions error

Creating

Resumable Upload

In Graph API 2.3+ you can perform resumable upload of video chunks at the (user-id||event-id||page-id)/videos/ edges. For information see the tutorial at Video Upload with Graph API.

Supported Formats

Videos must be encoded as multipart/form-data and published to graph-video.facebook.com instead of the regular Graph API URL.

POST /v4.0/{page-id}/videos HTTP/1.1
Host: graph-video.facebook.com

source=%7Bvideo-data%7D
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/{page-id}/videos',
    array (
      'source' => '{video-data}',
    ),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/{page-id}/videos",
    "POST",
    {
        "source": "{video-data}"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("source", "{video-data}");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{page-id}/videos",
    params,
    HttpMethod.POST,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"source": @"{video-data}",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{page-id}/videos"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

We support the following formats for uploaded videos:

3g2, 3gp, 3gpp, asf, avi, dat, divx, dv, f4v, flv, m2ts, m4v, mkv, mod, mov, mp4, mpe, mpeg, mpeg4, mpg, mts, nsv, ogm, ogv, qt, tod, ts, vob, wmv.

The aspect ratio of the video must be between 9x16 and 16x9.

Permissions

A page access token with publish_pages permission can be used to publish new videos. You can get permissions from Graph API Explorer.

The publish_actions permission has been deprecated. If your app has already been approved for this permission, you can continue using it to publish videos until August 1, 2018. To publish videos to User timelines, Groups, or Pages after that date, please use the Sharing Dialog.

Limitations

If you upload a video with a multi-part HTTP request or by providing a URL to a video, the video cannot exceed 1GB in size and 20 minutes in duration. (When using file_url The video should be downloaded within 5 minutes).

Resumable video upload supports uploading videos that are up to 1.75GB and 45 minutes long.


You can make a POST request to videos edge from the following paths:
When posting to this edge, a Video will be created.

Parameters

ParameterDescription
ad_breaks
array

Time offsets of ad breaks in milliseconds. Ad breaks are short ads that play within a video. Place new ad breaks or delete existing ones.

audio_story_wave_animation_handle
string

Everstore handle of wave animation used to burn audio story video

backdated_post
array

Settings to allow backdated video post.A backdated post needs to be published.

backdated_time
datetime

The time when the video post was created.

Required
backdated_time_granularity
enum{year, month, day, hour, min, none}
Default value: none

Accuracy of the backdated time.

hide_from_newsfeed
boolean
Default value: false

Whether to hide the video from newsfeed display.

content_category
enum {BEAUTY_FASHION, BUSINESS, CARS_TRUCKS, COMEDY, CUTE_ANIMALS, ENTERTAINMENT, FAMILY, FOOD_HEALTH, HOME, LIFESTYLE, MUSIC, NEWS, POLITICS, SCIENCE, SPORTS, TECHNOLOGY, VIDEO_GAMING, OTHER}

Content category of this video.

content_tags
list<numeric string>

Tags that describe the contents of the video. Use search endpoint with type=adinterest to get possible IDs.

                                                              Example:
                                                              ~~~~
                                                              /search?type=adinterest&q=couscous
                                                              ~~~~

crossposted_video_id
numeric string or integer

The video id that the new video post will be reusing

custom_labels
list<string>

Labels used to describe the video. Unlike content tags, custom labels are not published and only appear in insights data.

description
UTF-8 string

                                                                    The text describing a post that may be shown in a story about it.
                                                                    It may include rich text information, such as entities and emojis.

Supports Emoji
direct_share_status
int64

The status to allow sponsor directly boost the post.

embeddable
boolean

Whether the video is embeddable.

end_offset
int64

end_offset

expiration
Object

Time the video expires and whether it will be removed or hidden.

time
string

type
enum{expire_and_delete, expire_only}

feed_targeting
feed target

Object that controls news feed targeting for this content. Anyone in these demographics will be more likely to see this content, those not will be less likely, but may still see it anyway. Any of the targeting fields shown here can be used, none are required.

geo_locations
Object

countries
list<string>

regions
list<Object>

key
int64

cities
list<Object>

key
int64

zips
list<Object>

key
string

locales
list<string>

Values for targeted locales. Use type of adlocale to find Targeting Options and use the returned key to specify.

age_min
int64

Must be 13 or higher. Default is 0.

age_max
int64

Maximum age.

genders
list<int64>

Target specific genders. 1 targets all male viewers and 2 females. Default is to target both.

college_years
list<int64>

Array of integers. Represent graduation years from college.

education_statuses
list<int64>

Array of integers which represent current educational status. Use 1 for high school, 2 for undergraduate, and 3 for alum (or localized equivalents).

interested_in
list<int64>

Deprecated. Please see the Graph API Changelog for more information.

Deprecated
relationship_statuses
list<int64>

Array of integers for targeting based on relationship status. Use 1 for single, 2 for 'in a relationship', 3 for married, and 4 for engaged. Default is all types.

interests
list<int64>

One or more IDs of pages to target fans of pages.Use type of page to get possible IDs as find Targeting Options and use the returned id to specify.

file_size
int64

The size of the entire video file in bytes.

file_url
string

Accessible URL of a video file. Cannot be used with upload_phase.

fisheye_video_cropped
boolean

Whether the single fisheye video is cropped or not

fov
int64

360 video only: Vertical field of view

front_z_rotation
float

The front z rotation in degrees on the single fisheye video

guide
list<list<int64>>

360 video only: Guide keyframes data. An array of keyframes, each of which is an array of 3 or 4 elements in the following order: [video timestamp (seconds), pitch (degrees, -90 ~ 90), yaw (degrees, -180 ~ 180), field of view (degrees, 40 ~ 90, optional)], ordered by video timestamp in strictly ascending order.

guide_enabled
boolean

360 video only: Whether Guide is active.

initial_heading
int64

360 video only: Horizontal camera perspective to display when the video begins.

initial_pitch
int64

360 video only: Vertical camera perspective to display when the video begins.

is_voice_clip
boolean

is_voice_clip, used to indicate that if a video is used as audio record

multilingual_data
list<Object>

The data of multilingual messages and their dialects

multilingual_status_lang
string

multilingual_status
UTF-8 string

Supports Emoji
no_story
boolean

If set to true, this will suppress feed and timeline story.

original_fov
int64

Original field of view of the source camera

original_projection_type
enum {equirectangular, cubemap, equiangular_cubemap, half_equirectangular}

360 video only: The original projection type of the 360 video being uploaded.

published
boolean
Default value: true

Whether a post about this video is published. Non-published videos cannot be backdated.

react_mode_metadata
JSON-encoded string

This metadata is required for clip reacts feature

referenced_sticker_id
numeric string or integer

Sticker id of the sticker in the post

replace_video_id
numeric string or integer

The video id your uploaded video about to replace

scheduled_publish_time
int64

Time when the page post about this video should go live, this should be between 10 mins and 6 months from the time of publishing the video.

secret
boolean

If set to true, this video will not appear anywhere on Facebook and is not searchable. It can be viewed and shared using permalink and embeds. Default value is false.

slideshow_spec
JSON object

Specification of a list of images that are used to generate video.

images_urls
list<URL>

A 3-7 element array of the URLs of the images. Required.

Required
duration_ms
integer

The duration in milliseconds of each image. Default value is 1000.

transition_ms
integer

The duration in milliseconds of the crossfade transition between images. Default value is 1000.

social_actions
boolean

This can be used to enable or prohibit the use of Facebook socialactions (likes, comments, and sharing) on an unlisted video. Default value is false

source
string

The video, encoded as form data. This field is required.

specified_dialect
string

The default dialect of a multilingual post

spherical
boolean
Default value: false

Set if the video was recorded in 360 format.

sponsor_id
numeric string or integer

Facebook Page id that is tagged as sponsor in the video post

sponsor_relationship
int64

Sponsor Relationship, such as Presented By or Paid PartnershipWith

start_offset
int64

Start byte position of the file chunk.

swap_mode
enum {replace}

Type of replacing video request

targeting
target

Object that limits the audience for this content. Anyone not in these demographics will not be able to view this content. This will not override any Page-level demographic restrictions that may be in place.

geo_locations
Object

countries
list<string>

regions
list<Object>

key
int64

cities
list<Object>

key
int64

zips
list<Object>

key
string

locales
list<string>

excluded_countries
list<string>

excluded_regions
list<int64>

excluded_cities
list<int64>

excluded_zipcodes
list<string>

timezones
list<int64>

age_min
enum {13, 17, 18, 19, 21}

thumb
image

The video thumbnail raw data to be uploaded and associated with a video.

title
UTF-8 string

The title of the video.

Supports Emoji
transcode_setting_properties
string

Properties used in computing transcode settings for the video

universal_video_id
string

The publishers asset management code for this video.

unpublished_content_type
enum {SCHEDULED, SCHEDULED_RECURRING, DRAFT, ADS_POST, INLINE_CREATED, PUBLISHED}

Type of unpublished content, such as scheduled, draft or ads_post.

upload_phase
enum {start, transfer, finish, cancel}

Type of chunked upload request.

upload_session_id
numeric string or integer

ID of the chunked upload session.

video_file_chunk
string

The video file chunk, encoded as form data. This field is required during transfer upload phase.

Return Type

Struct {
id: numeric string,
upload_session_id: numeric string,
video_id: numeric string,
start_offset: numeric string,
end_offset: numeric string,
success: bool,
skip_upload: bool,
upload_domain: string,
region_hint: string,
transcode_bit_rate_bps: numeric string,
transcode_dimension: numeric string,
}

Validation Rules

ErrorDescription
200Permissions error
6001There was a problem uploading your video. Please try again.
389Unable to fetch video file from URL.
100Invalid parameter
390There was a problem uploading your video file. Please try again.
6000There was a problem uploading your video file. Please try again with another file.
356There was a problem uploading your video file. Please try again.
351There was a problem with your video file. Please try again with another file,
475You have been temporarily blocked from posting videos because you added videos containing content that may belong to someone else.

Updating

You can't perform this operation on this endpoint.

Deleting

You can't delete using this edge, however you can delete videos using the /{video-id} node. See Graph API Reference, Video


You can't perform this operation on this endpoint.