Live Video API

Broadcasting

Updated: Jul 2, 2026
Copy for LLM
To broadcast a live video, you must first create a LiveVideo object. The LiveVideo object represents the broadcast, and you can manipulate the object’s properties to control the broadcast’s settings. Upon creation, the API will return the LiveVideo object’s ID and a stream URL, which you can pass to your encoder and use to stream data to the LiveVideo object.
On June 10th, 2024, Meta is launching new requirements that must meet before an account can go live on Facebook. The new requirements are as follows:
Visit our
Help Center
to learn more about this change.

Prerequisites

Before you broadcast a live video, make sure you have the following:
  • A streaming encoder that can send data to an RTMP or RTMPS stream URL.
  • To broadcast on a User, a User access token with the publish_video permission.
  • To broadcast on a Page, a Page access token for an admin of the Page with the pages_read_engagement and pages_manage_posts permissions.

Broadcast on a User

To broadcast on a User object, get a User access token with the publish_video permission and send a request to:
POST /<USER_ID>/live_videos?status=LIVE_NOW
Refer to the /live_videos edge reference to see additional query string parameters you can include to describe the broadcast, such as a title and description.
When testing an API call, you can include the access_token parameter set to your access token. However, when making secure calls from your app, use the access token class.
Upon success, the API will create a LiveVideo object on the User and return a secure_stream_url and the LiveVideo object’s id. The broadcast will appear in a post on the User’s profile as soon as you send data to the secure stream URL. You can query the LiveVideo object to monitor the broadcast’s health and to end the broadcast.

Sample request

curl -i -X POST \
 "https://graph.facebook.com/v26.0/<USER_ID>/live_videos
   ?status=LIVE_NOW
   &title=Today%27s%20Live%20Video
   &description=This%20is%20the%20live%20video%20for%20today."

Sample response

{
  "id": "1953020644813104",      //<LIVE_VIDEO_ID>
  "stream_url": "rtmp://rtmp-api.facebook...",
  "secure_stream_url":"rtmps://rtmp-api.facebook..."
}

Broadcast on a Page

To broadcast a live video on a Page, get a Page access token of an admin of the Page with the pages_read_engagement and pages_manage_posts permissions, then send a request to:
POST /<PAGE_ID>/live_videos?status=LIVE_NOW
Refer to the /live_videos edge reference to see additional query string parameters you can include to describe the broadcast, such as a title and description.
When testing an API call, you can include the access_token parameter set to your access token. However, when making secure calls from your app, use the access token class.
Upon success, the API will create a LiveVideo object on the Page and return a secure_stream_url and the LiveVideo object’s id. The broadcast will appear in a post on the Page as soon as you send data to the secure stream URL. You can query the LiveVideo object to monitor the broadcast’s health and to end the broadcast.

Sample request

curl -i -X POST \
  "https://graph.facebook.com/v26.0/<PAGE_ID>/live_videos
    ?status=LIVE_NOW
    &title=Today%27s%20Page%20Live%20Video
    &description=This%20is%20the%20live%20video%20for%20the%20Page%20for%20today"

Sample response

{
  "id": "1953020644813108",     //<LIVE_VIDEO_ID>
  "stream_url": "rtmp://rtmp-api.facebook...",
  "secure_stream_url":"rtmps://rtmp-api.facebook..."
}

Get broadcast stream data

You can read a LiveVideo object to get the broadcast stream’s preview URLs and data on streaming health, such as bitrates and frame rates. Stream health data refreshes every 2 seconds, so limit queries to no more than once every 2 seconds. A stream timeout will be detected and reported after 4 seconds of no data being received.
To read a LiveVideo object, get an appropriate User or Page access token with the publish_video permission, then send a query to:
GET /<LIVE_VIDEO_ID>?fields=<COMMA_SEPARATED_LIST_OF_FIELDS>
Use the {fields} parameter to specify the LiveVideo object fields you want returned. For example, here’s a request to get the ingest_streams on the LiveVideo object, which includes data about stream health:

Sample request

curl -i -X GET \
  "https://graph.facebook.com/v26.0/<LIVE_VIDEO_ID>?fields=ingest_streams"

Sample response

{
  "ingest_streams": [
    {
      "stream_id": "0",
      "stream_url": "rtmp://rtmp-api.facebook...",
      "secure_stream_url": "rtmps://rtmp-api.facebook...",
      "is_master": true,
      "stream_health": {
        "video_bitrate": 4024116,
        "video_framerate": 60,
        "video_gop_size": 2000,
        "video_height": 720,
        "video_width": 1280,
        "audio_bitrate": 128745.4921875
      },
      "id": "1914910145231512"  // <INGEST_STREAM_ID>
    }
  ],
  "id": "<LIVE_VIDEO_ID>"
}
Response Properties
Field Name Description
audio_bitrate
Bits per second of the incoming audio stream.
is_master
true if the Live Video ID being queried is the video being delivered to an audience.
secure_stream_url
The secure RTMPS ingest URL for the Live Video ID being queried.
stream_url
The RTMP ingest URL for the Live Video ID being queried.
video_bitrate
Bits per second of the incoming video stream.
video_framerate
Frames per second of the incoming video stream.
video_gop_size
GOP (group of pictures) size in milliseconds.
video_height
Height in pixels of the incoming video frame.
video_width
Width in pixels of the incoming video frame.

End a broadcast

To end a broadcast, stop streaming live video data from your encoder to the stream URL or send a request to:
POST /<LIVE_VIDEO_ID>?end_live_video=true
This sets the LiveVideo object’s status to VOD and saves it as a video-on-demand (VOD) so you can view it later.
Upon success, the API will return the LiveVideo object’s ID.

Sample request

curl -i -X POST \
  "https://graph.facebook.com/v26.0/<LIVE_VIDEO_ID>?end_live_video=true"

Sample response

{
  "id": "10213570560993813"  //<LIVE_VIDEO_ID>
}
You can perform a GET operation on the LiveVideo ID to confirm that its status has been set to VOD:
GET /<LIVE_VIDEO_ID>?fields=status

Sample response

{
  "status": "VOD",  // Broadcast ended, saved as VOD
  "id": "10213570560993813"    //<LIVE_VIDEO_ID>
}

Delete a broadcast

Caution: Deleting a broadcast is permanent and cannot be undone. Once you delete a broadcast, its saved VOD is removed and cannot be recovered.
To delete a broadcast that has ended and saved as a VOD, send a request to:
DELETE /<LIVE_VIDEO_ID>

Sample request

curl -i -X DELETE \
 "https://graph.facebook.com/v26.0/<LIVE_VIDEO_ID>"

Sample response

{
  success: true
}

Frame-accurate go-live

A broadcast can experience a slight delay before it goes live while the API decodes its initial streaming data and processes any associated API requests. This delay can make it difficult for on-air talent to know exactly when a broadcast has started. To avoid this problem, LiveVideo objects can be set to accept streaming data but to not go live to audiences until a go-live RTMP message is detected within the streaming data itself. This allows anyone who is able to preview a broadcast to see it, while allowing the streaming encoder to precisely control both the time at which the broadcast goes live for an audience and the first frame that the audience sees.
To enable frame-accurate go-live, first create a LiveVideo object as you normally would and set its status to PREVIEW. Once it has been created, query the LiveVideo object and request the secure_stream_url field with the following nested fields:
secure_stream_url.inband_go_live(require_inband_signal)
This will enable frame-accurate go-live on the LiveVideo object and the API will respond with a new secure stream URL which you can then stream to. You can disregard the initial secure stream url that was sent to you when you first created the LiveVideo object.
The broadcast goes live and becomes visible to the audience after both of the following conditions are met:
  • The broadcast status is set to LIVE, either through a Graph API call or by a user publishing from Live Producer.
  • The encoder sends the go-live RTMP message.

Go-live RTMP message structure

An AMF0 packet (type 0x12) containing:
  • the string onGoLive
  • an ECMA array (type 0x08) containing a single key-value pair:
    • Key: string (type 0x02) timestamp
    • Value: number (type 0x00): the timestamp of the first video frame that will be publicly visible
For more information, see the RTMP⁠ and AMF0⁠ specifications.

Sample request

Sample request to enable frame-accurate go-live on a LiveVideo.
curl -i -X GET \
   "https://graph.facebook.com/v26.0/LIVE_VIDEO_ID?fields=secure_stream_url.inband_go_live(require_inband_signal)&access_token=12345..."

Sample response

Secure stream URL for a LiveVideo object with frame-accurate go-live enabled.
{
  "secure_stream_url": "rtmps://rtmp-pc.facebook.com:443/rtmp/LIVE_VIDEO_ID?s_bl=1&s_gl=1&...",
  "id": "LIVE_VIDEO_ID"
}

Get error code data

To get error code data associated with a broadcast, send a request to:
GET /<LIVE_VIDEO_ID>?fields=errors
The API will respond with the error code, type, message, and a timestamp.

Sample response

curl -i -X GET \
 "https://graph.facebook.com/v26.0/<LIVE_VIDEO_ID>?fields=errors"

Sample response

{
  "errors": {
    "data": [
      {
        "error_code": 1969004,
        "error_type": "stream",
        "error_message": "Video signal lost",
        "creation_time": "2018-12-05T23:58:52+0000"
      },
      {
        "error_code": 1969004,
        "error_type": "stream",
        "error_message": "Video signal lost",
        "creation_time": "2018-12-05T23:58:52+0000"
      },
      {
        "error_code": 0,
        "error_type": "info",
        "error_message": "Live Service received the video signal",
        "creation_time": "2018-12-05T23:58:02+0000"
      },
      {
        "error_code": 0,
        "error_type": "info",
        "error_message": "Live Service received the video signal",
        "creation_time": "2018-12-05T23:58:02+0000"
      }
    ]
  },
  "id": "{your-live-video-id}"
}

Common Live Video API error codes

error_subcode Error Summary Description
COPYRIGHT__LIVE_COPYRIGHT_VIOLATION
Live Copyright Violation
Your live video has been stopped because it may contain audio or visual content that belongs to a different Page.
VIDEO__CREATE_FAILED
Upload Problem
There was a problem and your video was not uploaded. Please try again.
LIVE_VIDEO__DELETE_FAILED
Live Video Not Deleted
There was a problem and your live video was not deleted. Please try again.
LIVE_VIDEO__EDIT_API_NOT_ALLOWED
Editing Via Video API Is Not Allowed While Live
Editing a live video using the Video Edit API is not allowed. Use the live video ID.
LIVE_VIDEO__LIVE_STREAM_ERROR
Generic Stream
There was an error during the stream
LIVE_VIDEO__NOT_EXIST
Live Video Does Not Exist
The live video you are trying to access does not exist in the system any more.
LIVE_VIDEO__PRIVACY_REQUIRED
Privacy Setting Required
You need to set a privacy before going live.

Permission error codes

Code Subcode Message Type Mitigation messaging
200
1363120
Permissions error
OAuthException
You’re not eligible to go live
Your profile needs to be at least 60 days old before you can go live on Facebook. Learn more at https://www.facebook.com/business/help/167417030499767?id=1123223941353904
200
1363144
Permissions error
OAuthException
You’re not eligible to go live
You need at least 100 followers before you can go live from your profile. Learn more at https://www.facebook.com/business/help/167417030499767?id=1123223941353904

See also