Graph API Version

Live Video

For more information about the Live API, check out our Live API intro docs.

Reading

A live video

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
  • manage_pages
  • pages_show_list
Other Apps
Permissions are not usually requested.

Examples

Graph API Explorer
GET /v2.10/{live-video-id} HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{live-video-id}'
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
/* make the API call */
FB.api(
    "/{live-video-id}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{live-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:@"/{live-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

ad_break_config

LiveVideoAdBreakConfig

The ad break configurations for clients implementing triggering an ad break ui. Contains ad break eligibility and constants to renderthe ui.

ad_break_failure_reason

enum

Ad Break failure reason

broadcast_start_time

datetime

The time the video was initially published

copyright

The copyright information for the live video

creation_time

datetime

The creation time of the live video

dash_preview_url

string

Preview URL for dash player

description

string

The description of the live video

embed_html

string

The embed html of the live video

from

The originator of the live video

id

numeric string

The live video ID

is_manual_mode

bool

Whether schedule live is in manual mode, in which live video will start manually instead of on schedled time

is_reference_only

bool

Whether the live video is exclusively used for copyright monitoring

live_views

unsigned int32

The instant viewer count of the live video now

permalink_url

string

The permalink URL of this video on Facebook.

planned_start_time

datetime

Planned start time for a live video

seconds_left

int32

Seconds left in the maximum possible duration for this live video

secure_stream_url

string

The secure stream url of the live video. Check with your encoder whether this is supported before adapting

status

enum

The status of the live video

stream_url

string

The stream url of the live video

title

string

The title of the live video

video

The inside video of live video - only visible when the live video has ended.

Edges

EdgeDescription

blocked_users

The users who are blocked from commenting on the live video

comments

Comments made on this

errors

Errors that occurred during the live stream

likes

People who like this

reactions

People who reacted on this

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error

Creating

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

Parameters

NameDescription
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
description
UTF-8 string

The description of the live video.

Supports Emoji
enable_backup_ingest
boolean

Set this to true to enable a backup ingest url. stop_on_delete_stream defaults to false when set

encoding_settings
string

Identifier of the encoding settings group the broadcaster is using for this stream.

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

is_spherical
boolean

Flag that denotes the broadcast is a 360 live broadcast.

original_fov
int64

Original field of view of the camera

planned_start_time
integer

Unix timestamp when the broadcaster plans to go live.

privacy
Privacy Parameter

Privacy for this live video.

published
boolean

Set this to false to preview the stream before going live.

Deprecated. Prefer setting the status instead.

save_vod
boolean

Whether or not the video data should be saved for later consumption in VOD format. Default is true, except for certain broadcasts types (e.g. AMBIENT)

schedule_custom_profile_image
image

Custom image that will appear in the scheduled live story and lobby.

spatial_audio_format
enum {ambiX_4}

Denotes the format of the spatial audio stream. When unspecified audio is presumed to be mono or stereo.

status
enum {UNPUBLISHED, LIVE_NOW, SCHEDULED_UNPUBLISHED, SCHEDULED_LIVE, SCHEDULED_CANCELED}

Choose between UNPUBLISHED or LIVE_NOW.

stop_on_delete_stream
boolean

Set this to true if stream should be stopped when deleteStream RTMP command received.

stream_type
enum {REGULAR, AMBIENT}

The type of stream. Default value: REGULAR. Use AMBIENT for continuous broadcasts that last days or weeks (like panda cams). Ambient broadcasts do not generate VOD or notifications.

title
UTF-8 string

The title of the live video.

Supports Emoji

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
stream_url: string,
secure_stream_url: string,
stream_secondary_urls: List [
string
],
secure_stream_secondary_urls: List [
string
],
}
You can make a POST request to live_videos edge from the following paths:
When posting to this edge, a LiveVideo will be created.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
No data
Page management Apps
No data
Other Apps
  • publish_actions

Parameters

NameDescription
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
description
UTF-8 string

The description of the live video.

Supports Emoji
enable_backup_ingest
boolean

Set this to true to enable a backup ingest url. stop_on_delete_stream defaults to false when set

encoding_settings
string

Identifier of the encoding settings group the broadcaster is using for this stream.

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

is_spherical
boolean

Flag that denotes the broadcast is a 360 live broadcast.

original_fov
int64

Original field of view of the camera

planned_start_time
integer

Unix timestamp when the broadcaster plans to go live.

privacy
Privacy Parameter

Privacy for this live video.

published
boolean

Set this to false to preview the stream before going live.

Deprecated. Prefer setting the status instead.

save_vod
boolean

Whether or not the video data should be saved for later consumption in VOD format. Default is true, except for certain broadcasts types (e.g. AMBIENT)

schedule_custom_profile_image
image

Custom image that will appear in the scheduled live story and lobby.

spatial_audio_format
enum {ambiX_4}

Denotes the format of the spatial audio stream. When unspecified audio is presumed to be mono or stereo.

status
enum {UNPUBLISHED, LIVE_NOW, SCHEDULED_UNPUBLISHED, SCHEDULED_LIVE, SCHEDULED_CANCELED}

Choose between UNPUBLISHED or LIVE_NOW.

stop_on_delete_stream
boolean

Set this to true if stream should be stopped when deleteStream RTMP command received.

stream_type
enum {REGULAR, AMBIENT}

The type of stream. Default value: REGULAR. Use AMBIENT for continuous broadcasts that last days or weeks (like panda cams). Ambient broadcasts do not generate VOD or notifications.

title
UTF-8 string

The title of the live video.

Supports Emoji

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
stream_url: string,
secure_stream_url: string,
stream_secondary_urls: List [
string
],
secure_stream_secondary_urls: List [
string
],
}
You can make a POST request to live_videos edge from the following paths:
When posting to this edge, a LiveVideo will be created.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
  • manage_pages
  • publish_pages
  • pages_show_list
Page management Apps
  • manage_pages
  • publish_pages
  • pages_show_list
Other Apps
No data

Parameters

NameDescription
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

The description of the live video.

Supports Emoji
enable_backup_ingest
boolean

Set this to true to enable a backup ingest url. stop_on_delete_stream defaults to false when set

encoding_settings
string

Identifier of the encoding settings group the broadcaster is using for this stream.

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

is_spherical
boolean

Flag that denotes the broadcast is a 360 live broadcast.

original_fov
int64

Original field of view of the camera

planned_start_time
integer

Unix timestamp when the broadcaster plans to go live.

privacy
Privacy Parameter

Privacy for this live video.

product_items
list<numeric string>

Products which will be shown with live videos.

published
boolean

Set this to false to preview the stream before going live.

Deprecated. Prefer setting the status instead.

save_vod
boolean

Whether or not the video data should be saved for later consumption in VOD format. Default is true, except for certain broadcasts types (e.g. AMBIENT)

schedule_custom_profile_image
image

Custom image that will appear in the scheduled live story and lobby.

spatial_audio_format
enum {ambiX_4}

Denotes the format of the spatial audio stream. When unspecified audio is presumed to be mono or stereo.

status
enum {UNPUBLISHED, LIVE_NOW, SCHEDULED_UNPUBLISHED, SCHEDULED_LIVE, SCHEDULED_CANCELED}

Choose between UNPUBLISHED or LIVE_NOW.

stop_on_delete_stream
boolean

Set this to true if stream should be stopped when deleteStream RTMP command received.

stream_type
enum {REGULAR, AMBIENT}

The type of stream. Default value: REGULAR. Use AMBIENT for continuous broadcasts that last days or weeks (like panda cams). Ambient broadcasts do not generate VOD or notifications.

targeting
target

Object that limits the audience for this content. Anyone not in these demographics will not be able to view this content.

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.

excluded_countries
list<string>

Values for excluded countries. You can specify up to 25 countries. Use ISO 3166 format codes.

excluded_regions
list<int64>

Values for excluded regions. Use type of adregion and list of GLOBAL to find Targeting Options and use the returned key to specify. For example:

search/?type=adregion&q=California&list=GLOBAL
excluded_cities
list<int64>

Values for excluded cities. Use type of adcity to find Targeting Options and use the returned key to specify.

excluded_zipcodes
list<string>

Values for excluded zipcodes. Use type of adzipcode to find Targeting Options and use the returned key to specify.

excluded_locales
list<string>
timezones
list<int64>

ID for the timezone. See here.

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.

title
UTF-8 string

The title of the live video.

Supports Emoji

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
stream_url: string,
secure_stream_url: string,
stream_secondary_urls: List [
string
],
secure_stream_secondary_urls: List [
string
],
}
You can make a POST request to live_videos edge from the following paths:
When posting to this edge, a LiveVideo will be created.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
  • publish_actions
  • user_managed_groups
  • user_events
  • user_videos
  • user_friends
Page management Apps
  • pages_show_list
  • publish_actions
Other Apps
  • publish_actions

Parameters

NameDescription
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
description
UTF-8 string

The description of the live video.

Supports Emoji
enable_backup_ingest
boolean

Set this to true to enable a backup ingest url. stop_on_delete_stream defaults to false when set

encoding_settings
string

Identifier of the encoding settings group the broadcaster is using for this stream.

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

is_spherical
boolean

Flag that denotes the broadcast is a 360 live broadcast.

original_fov
int64

Original field of view of the camera

planned_start_time
integer

Unix timestamp when the broadcaster plans to go live.

privacy
Privacy Parameter

Privacy for this live video.

published
boolean

Set this to false to preview the stream before going live.

Deprecated. Prefer setting the status instead.

save_vod
boolean

Whether or not the video data should be saved for later consumption in VOD format. Default is true, except for certain broadcasts types (e.g. AMBIENT)

schedule_custom_profile_image
image

Custom image that will appear in the scheduled live story and lobby.

spatial_audio_format
enum {ambiX_4}

Denotes the format of the spatial audio stream. When unspecified audio is presumed to be mono or stereo.

status
enum {UNPUBLISHED, LIVE_NOW, SCHEDULED_UNPUBLISHED, SCHEDULED_LIVE, SCHEDULED_CANCELED}

Choose between UNPUBLISHED or LIVE_NOW.

stop_on_delete_stream
boolean

Set this to true if stream should be stopped when deleteStream RTMP command received.

stream_type
enum {REGULAR, AMBIENT}

The type of stream. Default value: REGULAR. Use AMBIENT for continuous broadcasts that last days or weeks (like panda cams). Ambient broadcasts do not generate VOD or notifications.

title
UTF-8 string

The title of the live video.

Supports Emoji

Return Type

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

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
475You have been temporarily blocked from posting videos because you added videos containing content that may belong to someone else.

Updating

You can update a LiveVideo by making a POST request to /{live_video_id}.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
No data
Page management Apps
  • manage_pages
  • publish_pages
  • pages_show_list
Other Apps
  • publish_actions

Parameters

NameDescription
ad_break_drop_live_stream
boolean

Should facebook drop the video frames during the duration of the ad break.

ad_break_duration
int64

Start an Ad Break with a specific duration, in milliseconds.

ad_break_encoder_drops_live_stream
boolean

Will the encoder drop the live stream during the ad break duration.

ad_break_intent
boolean

Inform clients that you will start an ad break soon.

ad_break_start_now
boolean

Start an Ad Break now at the current time offset of the stream.

ad_break_time_offset
float

Start an Ad Break at the time offset in milliseconds.

attribution_app_id
numeric string or integer

App ID to which the video should be attributed, if any.

attribution_app_metadata
string

Metadata for the attribution of the video, if any.

commercial_break_durations
list<int64>

Durations of commercial breaks taken during the broadcast

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
copyrights_violation_dialog_state
enum {NO_MSG_WAS_SENT, PRIVATE_BROADCAST_MSG_SENT, PUBLIC_BROADCAST_MSG_SENT, BROADCASTER_CLAIMED_RIGHTS, BROADCASTER_CONTINUED_BLOCKED_STREAM, BROADCAST_WAS_STOPPED, NOTIF_SENT_FOR_API_STREAM, NOTIF_SENT_FOR_LIVE_WWW_STREAM, MATCH_CREATED_MSG_SENT, MATCH_BLOCKED_MSG_SENT, LIVE_TAKEDOWN_MSG_SENT}

Broadcaster-FB dialog regarding copyrights violation found, if any.

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 description of live video

Supports Emoji
direct_share_status
int64

The status to allow sponsor directly boost the post.

disturbing
boolean

If true, autoplay will be disabled and live video will have a graphic content warning overlay

embeddable
boolean

If true, live video will be embeddable

end_live_video
boolean

If true, the live video will be ended. Only valid if the live video is still running

is_manual_mode
boolean

Flag to indicate that the scheduled broadcast is switched to manual mode

live_comment_moderation_setting
list<enum {FOLLOWER, SLOW, DISCUSSION}>

Set of comment moderation settings for the live video

place
place tag

Location associated with the video, if any.

planned_start_time
integer

Planned start time for a scheduled live video

privacy
Privacy Parameter

The privacy setting of live video

product_items
list<numeric string>

Products which will be shown with live videos.

published
boolean

Should the live video be published? Only valid if not yet published.

Deprecated. Prefer setting the status instead.

schedule_custom_profile_image
image

Custom image that will appear in the scheduled live story and lobby.

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

status
enum {UNPUBLISHED, LIVE_NOW, SCHEDULED_UNPUBLISHED, SCHEDULED_LIVE, SCHEDULED_CANCELED}

Choose between UNPUBLISHED or LIVE_NOW.

stream_type
enum {REGULAR, AMBIENT}

The type of stream. Default value: REGULAR. Use AMBIENT for continuous broadcasts that last days or weeks (like panda cams). Ambient broadcasts do not generate VOD or notifications.

tags
list<int>

Users tagged in the live video.

targeting
target

Object that limits the audience for this content. Anyone not in these demographics will not be able to view this content.

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.

excluded_countries
list<string>

Values for excluded countries. You can specify up to 25 countries. Use ISO 3166 format codes.

excluded_regions
list<int64>

Values for excluded regions. Use type of adregion and list of GLOBAL to find Targeting Options and use the returned key to specify. For example:

search/?type=adregion&q=California&list=GLOBAL
excluded_cities
list<int64>

Values for excluded cities. Use type of adcity to find Targeting Options and use the returned key to specify.

excluded_zipcodes
list<string>

Values for excluded zipcodes. Use type of adzipcode to find Targeting Options and use the returned key to specify.

excluded_locales
list<string>
timezones
list<int64>

ID for the timezone. See here.

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.

title
UTF-8 string

The title of the live video.

Supports Emoji

Return Type

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

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
475You have been temporarily blocked from posting videos because you added videos containing content that may belong to someone else.

Deleting

You can delete a LiveVideo by making a DELETE request to /{live_video_id}.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
  • manage_pages
  • publish_pages
Page management Apps
  • manage_pages
  • publish_pages
Other Apps
  • publish_actions
  • user_videos

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error