Graph API Version

Video

Represents an individual video on Facebook.

Reading

Feature Permissions

NameDescription
Page Public Content AccessThis feature permission may be required.

A Video

Permissions

As long as a video doesn't contain licensed music, you can retrieve it with the following permissions:

  • A Page access token can read all videos posted to or posted by that Page.
  • A User access token can read any video your application created on behalf of that User.
  • A User's videos can be read if the owner has granted the user_videos or user_posts permission.
  • A User access token may read a video that User is tagged in if the User granted the user_videos or user_posts permission. However, in some cases the video owner's privacy settings may not allow your application to access it.
  • The source field will not be returned for Page-owned videos unless the User making the request is an admin of the owning Page.

Features

Source URL

Note: The source URL for reading a posted video changes over time by design. If you save the URL and use it later it will not work.

Example

Graph API Explorer
GET /v5.0/{video-id} 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(
    '/{video-id}',
    '{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(
    "/{video-id}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{video-id}",
    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:@"/{video-id}"
                                      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

This endpoint doesn't have any parameters.

Fields

FieldDescription
id
numeric string

The video ID.

ad_breaks
list<integer>

Time offsets of ad breaks in milliseconds. Ad breaks are short ads that play within a video.

backdated_time
datetime

A user-specified time for when this object was created

backdated_time_granularity
enum

How accurate the backdated time is

content_category
enum

The content category of this video.

content_tags
list<numeric string>

Tags that describe the contents of the video.

created_time
datetime

The time the video was initially published.

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
string

The description of the video.

embed_html
string

The HTML element that may be embedded in a Web page to play the video.

embeddable
bool

Whether the video is embeddable.

event

If this object has a place, the event associated with the place

format

The different formats of the video.

from
User|Page

The profile that created the video.

icon
string

The icon that Facebook displays when videos are published to the feed.

is_crosspost_video
bool

Whether the video is crossposted from other page.

is_crossposting_eligible
bool

Specifies if the video is eligible for crossposting. Page access-token is required to query this field.

is_instagram_eligible
bool

Whether the video is eligible to be promoted on Instagram

is_reference_only
bool

Whether the video is exclusively used for copyright monitoring

length
float

Duration of this video in seconds.

live_status
enum

The live status of the video

music_video_copyright
MusicVideoCopyright

The music video copyright of this video

permalink_url
string

URL to the permalink page of the video.

place

Place info

premiere_living_room_status
enum

The status of the Premiere Watch Party, if any

privacy

Privacy setting for the video.

published
bool

Whether a post about this video is published. The post is not scheduled, draft, or ads_post.

scheduled_publish_time
datetime

The time that the video is scheduled to publish.

source
string

A URL to the raw, playable video file.

status

Object describing the status attributes of a video.

title
string

The video title or caption.

universal_video_id
string

The publishers asset management code for this video.

updated_time
datetime

The last time the video or its caption was updated.

Edges

EdgeDescription

Captions for the video.

Comments made on this

The pages that this video being crossposting shared to.

People who like this

string

The URL for the thumbnail picture of the video.

Settings for polls on the video

Video polls attached to this video

People who reacted on this

Shared posts

Sponsor pages tagged in the video.

Users tagged in the video.

Thumbnails for the video.

Total insights from all video posts associated with this video.

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
210User not visible
159Invalid protocol, must be https
190Invalid OAuth 2.0 Access Token

Creating

You can publish videos by using the following edges:

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
audio_story_wave_animation_handle
string

Everstore handle of wave animation used to burn audio story video

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

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
embeddable
boolean

Whether the video is embeddable

end_offset
int64

end_offset

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

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

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

Scheduled publish time for group posts.

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.

reordering_opt_in
boolean
Default value: false

music_variations_opt_in
boolean
Default value: false

source
string

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

spherical
boolean
Default value: false

Set if the video was recorded in 360 format

start_offset
int64

Start byte position of the file chunk

swap_mode
enum {replace}

Type of replacing video request

title
UTF-8 string

The title of the video

Supports Emoji
transcode_setting_properties
string

transcode_setting_properties

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

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,
should_expand_to_transcode_dimension: bool,
action_id: string,
}

Validation Rules

ErrorDescription
6001There was a problem uploading your video. Please try again.
200Permissions error
6000There was a problem uploading your video file. Please try again with another file.
100Invalid parameter
368The action attempted has been deemed abusive or is otherwise disallowed
356There was a problem uploading your video file. Please try again.
389Unable to fetch video file from URL.
210User not visible
390There was a problem uploading your video file. Please try again.
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

reference_only
boolean

If set to true, this video will not appear anywhere on Facebook and can not be viewed or shared using permalink. After creating copyright for the video, the video can be used as copyright reference video. Default value is false.

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.

reordering_opt_in
boolean
Default value: false

music_variations_opt_in
boolean
Default value: false

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, REVIEWABLE_BRANDED_CONTENT}

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,
should_expand_to_transcode_dimension: bool,
action_id: string,
}

Validation Rules

ErrorDescription
6001There was a problem uploading your video. Please try again.
200Permissions error
6000There was a problem uploading your video file. Please try again with another file.
100Invalid parameter
368The action attempted has been deemed abusive or is otherwise disallowed
210User not visible
389Unable to fetch video file from URL.
390There was a problem uploading your video file. Please try again.
475You have been temporarily blocked from posting videos because you added videos containing content that may belong to someone else.
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
audio_story_wave_animation_handle
string

Everstore handle of wave animation used to burn audio story video

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.

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

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

no_story
boolean
Default value: false

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.

privacy
Privacy Parameter

Determines the privacy settings of the video. If not supplied, this defaults to the privacy level granted to the app in the Login Dialog. This field cannot be used to set a more open privacy setting than the one granted.

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

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.

reordering_opt_in
boolean
Default value: false

music_variations_opt_in
boolean
Default value: false

source
string

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

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

start_offset
int64

Start byte position of the file chunk.

swap_mode
enum {replace}

Type of replacing video request

title
UTF-8 string

The title of the video

Supports Emoji
transcode_setting_properties
string

Properties used in computing transcode settings for the video

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

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,
should_expand_to_transcode_dimension: bool,
action_id: string,
}

Validation Rules

ErrorDescription
6001There was a problem uploading your video. Please try again.
6000There was a problem uploading your video file. Please try again with another file.
100Invalid parameter
356There was a problem uploading your video file. Please try again.
368The action attempted has been deemed abusive or is otherwise disallowed
200Permissions error
332The image you tried to upload is too small. Please try again with a larger image.
190Invalid OAuth 2.0 Access Token
381There was a problem uploading your video file. Please try again.
You can make a POST request to polls edge from the following paths:
When posting to this edge, a Video will be created.

Parameters

ParameterDescription
correct_option
int64

Number of the correct option (in order, starting from 1)

options
array<string>

Text options for users to select in order

Required
question
string

Question text

Required
show_results
boolean

True to show the results after voting, otherwise false

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
option_ids: List [
numeric string
],
}

Validation Rules

ErrorDescription
100Invalid parameter
You can make a POST request to advideos edge from the following paths:
When posting to this edge, a Video will be created.

Example

Graph API Explorer
POST /v5.0/act_<AD_ACCOUNT_ID>/advideos HTTP/1.1
Host: graph.facebook.com

source=%40%3CVIDEO_PATH%3E
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/act_<AD_ACCOUNT_ID>/advideos',
    array (
      'source' => '@<VIDEO_PATH>',
    ),
    '{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(
    "/act_<AD_ACCOUNT_ID>/advideos",
    "POST",
    {
        "source": "@<VIDEO_PATH>"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("source", "@<VIDEO_PATH>");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/act_<AD_ACCOUNT_ID>/advideos",
    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_PATH>",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/act_<AD_ACCOUNT_ID>/advideos"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
curl -X POST \
  -F 'source="@<VIDEO_PATH>"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v5.0/act_<AD_ACCOUNT_ID>/advideos
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

ParameterDescription
audio_story_wave_animation_handle
string

Everstore handle of wave animation used to burn audio story video

composer_session_id
string

SELF_EXPLANATORY

description
UTF-8 string

SELF_EXPLANATORY

Supports Emoji
end_offset
int64

end_offset

file_size
int64

The size of the video file in bytes. Using during chunked upload.

file_url
string

SELF_EXPLANATORY

fisheye_video_cropped
boolean

Whether the single fisheye video is cropped or not

front_z_rotation
float

The front z rotation in degrees on the single fisheye video

name
string

The name of the video in the library.

og_action_type_id
numeric string or integer

SELF_EXPLANATORY

og_icon_id
numeric string or integer

SELF_EXPLANATORY

og_object_id
OG object ID or URL string

SELF_EXPLANATORY

og_phrase
string

SELF_EXPLANATORY

og_suggestion_mechanism
string

SELF_EXPLANATORY

original_fov
int64

Original field of view of the source camera

original_projection_type
enum {equirectangular, cubemap, equiangular_cubemap, half_equirectangular}

Original Projection type of the video being uploaded

react_mode_metadata
JSON-encoded string

This metadata is used in clip reaction feature

referenced_sticker_id
numeric string or integer

SELF_EXPLANATORY

slideshow_spec
JSON object

An object required for slideshow 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.

reordering_opt_in
boolean
Default value: false

music_variations_opt_in
boolean
Default value: false

source
string

The video, encoded as form data. See the Video Format doc for more details on video formats.

start_offset
int64

The start position in byte of the chunk that is being sent, inclusive. Used during chunked upload.

time_since_original_post
int64

SELF_EXPLANATORY

title
UTF-8 string

The name of the video being uploaded. Must be less than 255 characters. Special characters may count as more than 1 character.

Supports Emoji
transcode_setting_properties
string

Properties used in computing transcode settings for the video

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

SELF_EXPLANATORY

upload_phase
enum {start, transfer, finish, cancel}

The phase during chunked upload. Using during chunked upload.

upload_session_id
numeric string or integer

The session ID of this chunked upload. Using during chunked upload.

video_file_chunk
string

The chunk of the video, between start_offset and end_offset. Using during chunked upload.

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,
should_expand_to_transcode_dimension: bool,
action_id: string,
}

Validation Rules

ErrorDescription
389Unable to fetch video file from URL.
200Permissions error
6000There was a problem uploading your video file. Please try again with another file.
80004There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
6001There was a problem uploading your video. Please try again.
390There was a problem uploading your video file. Please try again.
100Invalid parameter
381There was a problem uploading your video file. Please try again.
222Video not visible
382The video file you tried to upload is too small. Please try again with a larger file.

Updating

Permissions

  • To update a User video, a User access token with the user_videos permission is required.
  • To update a Page video, a Page access token with the publish_pages permission is required.
You can update a Video by making a POST request to /{video_id}.

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.

allow_bm_crossposting
boolean

If set to true, Pages under your Business Manager will be able to crosspost the video.

allow_crossposting_for_pages
list<VideoPageCrosspostingPermissionParam>

Enable or disable pages from crosspoting the video

page_id
Page ID

Required
allow
boolean

Required
backdated_time
datetime

The time when the video post was created. A backdated post needs to be published.

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

Accuracy of the backdated time. A backdated post needs to be published.

call_to_action
Object

Call to action for someone viewing a video, such as Reply. You can add a call to action button to an uploaded video. This should be the action you want people to take when they reach the end of the video.

Supports Emoji
type
enum{SHOP_NOW, BOOK_TRAVEL, LEARN_MORE, SIGN_UP, DOWNLOAD, WATCH_MORE, NO_BUTTON, MESSAGE_PAGE, GET_MOBILE_APP, INSTALL_MOBILE_APP, USE_MOBILE_APP, INSTALL_APP, USE_APP, PLAY_GAME, WATCH_VIDEO, OPEN_LINK, LISTEN_MUSIC, MOBILE_DOWNLOAD, GET_OFFER, GET_OFFER_VIEW, BUY_NOW, BUY_TICKETS, UPDATE_APP, BET_NOW, GET_DIRECTIONS, ADD_TO_CART, ORDER_NOW, SELL_NOW, GET_SHOWTIMES, LISTEN_NOW, GET_EVENT_TICKETS, SEARCH_MORE, PRE_REGISTER, BOOK_TEST_DRIVE, CHECK_AVAILABILITY}

The type of the action. Not all types can be used for all ads. Check Ads Product Guide to see which type can be used for based on the objective of your campaign.

Required
value
Object
Default value: Array

JSON containing the call to action data.

Supports Emoji
link
URL

app_link
string

page
numeric string or integer

link_format
enum {VIDEO_LEAD, VIDEO_LPP, VIDEO_NEKO, VIDEO_NON_LINK, VIDEO_SHOP}

application
numeric string or integer

link_title
string

Supports Emoji
link_description
string

Supports Emoji
link_caption
string

product_link
string

get_movie_showtimes
boolean

sponsorship
Object

link
URL

image
URL

video_annotation
Object

annotations
list<Object>

start_time_in_sec
int64

end_time_in_sec
int64

link
URL

link_title
string

link_description
string

link_caption
string

image_url
URL

header_color
string

logo_url
URL

post_click_cta_title
string

post_click_description_title
string

offer_id
numeric string or integer

offer_view_id
numeric string or integer

advanced_data
Object

offer_id
numeric string or integer

lead_gen_form_id
numeric string or integer

fundraiser_campaign_id
numeric string or integer

event_id
numeric string or integer

event_tour_id
numeric string or integer

app_destination
enum {MESSENGER, MESSENGER_EXTENSIONS, MESSENGER_GAMES, LINK_CARD, MARKETPLACE, WHATSAPP}

app_destination_page_id
numeric string or integer

is_canvas_video_transition_enabled
boolean

whatsapp_number
string

preinput_text
string

customized_message_page_cta_text
string

external_offer_provider_id
numeric string or integer

origins
enum {COMPOSER, CAMERA}

object_store_urls
array<string>

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}

The 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

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

Description of the video.

Supports Emoji
direct_share_status
int64

The status to allow sponsor directly boost the post.

embeddable
boolean

Whether the video is embeddable.

expiration
Object

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

time
string

type
enum{expire_and_delete, expire_only}

expire_now
boolean

If set to true, the video will expire now.

increment_play_count
boolean

Increment count for times video played.

name
UTF-8 string

Video title or caption.

Supports Emoji
preferred_thumbnail_id
numeric string

Preferred thumbnail image ID

privacy
Privacy Parameter

Privacy setting for the video.

publish_to_news_feed
boolean

Distributes video item publicly to News Feed, Page Timeline, and Page Videos tab.

publish_to_videos_tab
boolean

Distributes video item publicly to the Page's Videos tab, but not News Feed or Timeline. This field can only be applied on an existing secret video.

published
boolean

Whether the video is published or not. Non-published videos cannot be backdated.

scheduled_publish_time
int64

Scheduled publish time for the video.

social_actions
boolean

Whether the video has likes, comments and shares disabled.

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

tags
list<numeric string>

Users tagged in the video.

target
numeric string

Target id of the video.

universal_video_id
string

The publishers asset management code for this video.

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
}

Validation Rules

ErrorDescription
200Permissions error
100Invalid parameter
475You have been temporarily blocked from posting videos because you added videos containing content that may belong to someone else.
190Invalid OAuth 2.0 Access Token
You can update a Video by making a POST request to /{video_id}/poll_settings.

Parameters

ParameterDescription
enable_was_live_voting
boolean

Should we enable was live voting for this video.

video_poll_www_placement
enum {TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT}

Where should we place the poll on videos in WWW.

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}

Validation Rules

ErrorDescription
100Invalid parameter

Deleting

Permissions

  • To delete a User video, a User access token with the user_videos permission is required.
  • To delete a Page video, a Page access token with the publish_pages permission is required.
  • Your app needs a User access token with the publish_pages permission to delete a video.
You can delete a Video by making a DELETE request to /{video_id}.

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
You can dissociate a Video from an AdAccount by making a DELETE request to /act_{ad_account_id}/advideos.

Parameters

ParameterDescription
video_id
video ID

Ad account library video ID

Required

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter