Graph API Version

Live Video

Reading

Live videos from this page

Permissions

To read Live Videos your app will need:

  • A Page Access Token
Graph API Explorer
GET /v2.9/{page-id}/live_videos HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{page-id}/live_videos'
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
/* make the API call */
FB.api(
    "/{page-id}/live_videos",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{page-id}/live_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}/live_videos"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Parameters

NameDescription
broadcast_status
list<enum {UNPUBLISHED, LIVE, LIVE_STOPPED, PROCESSING, VOD, SCHEDULED_UNPUBLISHED, SCHEDULED_LIVE, SCHEDULED_EXPIRED, SCHEDULED_CANCELED}>

Allows you to specify what kind of live videos return.No value returns all status types

type
enum{tagged, uploaded}
Default value: uploaded

Allows you to query which type of live videos to return

Fields

Reading from this edge will return a JSON formatted result:

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

data

A list of LiveVideo nodes.

paging

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

Validation Rules

ErrorDescription
100Invalid parameter

Creating

Permissions

To publish a Live Video your app will need:

  • A Page Access Token with the publish_actions and publish_pages permissions
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
encoding_settings
string

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

is_spherical
boolean

Flag that denotes the broadcast is a 360 live broadcast.

live_encoder
numeric string or integer

Live Encoder that will broadcast to this live video

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
Default value: true

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

Validation Rules

ErrorDescription
475Due to activity related to copyright infringement on your Facebook account, we have disabled your ability to upload any further videos.
100Invalid parameter

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.