Content Publishing

This guide shows you how to publish single images, videos, reels (single media posts), or posts containing multiple images and videos (carousel posts) on Instagram professional accounts using the Instagram Platform.

Requirements

Media on a public server

We cURL media used in publishing attempts, so the media must be hosted on a publicly accessible server at the time of the attempt.

Page Publishing Authorization

An Instagram professional account connected to a Page that requires Page Publishing Authorization (PPA) cannot be published to until PPA has been completed.

It's possible that an app user may be able to perform Tasks on a Page that initially does not require PPA but later requires it. In this scenario, the app user would not be able to publish content to their Instagram professional account until completing PPA. Since there's no way for you to determine if an app user's Page requires PPA, we recommend that you advise app users to preemptively complete PPA.

You will need the following:

Endpoints

• /<IG_ID>/media — Create media container and upload the media
  • upload_type=resumable — Create a resumbable upload session to upload large videos from an area with frequent network interruptions or other transmission failures. Only for apps that have implemented Facebook Login for Business.
• /<IG_ID>/media_publish — publish uploaded media using their media containers.
• /<IG_CONTAINER_ID>?fields=status_code — check media container publishing eligibility and status.

• /<IG_ID>/content_publishing_limit — check app user's current publishing rate limit usage.

• POST https://rupload.facebook.com/ig-api-upload/<IG_MEDIA_CONTAINER_ID> — Upload the video to Meta servers

• GET /<IG_MEDIA_CONTAINER_ID>?fields=status_code — Check publishing eligibility and status of the video

HTML URL encoding troubleshooting

• Some of the parameters are supported in list/dict format.
• Some characters need to be encoded into a format that can be transmitted over the Internet. For example: user_tags=[{username:’ig_user_name’}] is encoded to user_tags=%5B%7Busername:ig_user_name%7D%5D where [ is encoded to %5B and { is encoded to %7B. For more conversions, please refer to the HTML URL Encoding standard.

Limitations

• JPEG is the only image format supported. Extended JPEG formats such as MPO and JPS are not supported.
• Shopping tags are not supported.
• Branded content tags are not supported.
• Filters are not supported.

For additional limitations, see each endpoint's reference.

Rate Limit

Instagram accounts are limited to 50 API-published posts within a 24-hour moving period. Carousels count as a single post. This limit is enforced on the POST /<IG_ID>/media_publish endpoint when attempting to publish a media container. We recommend that your app also enforce the publishing rate limit, especially if your app allows app users to schedule posts to be published in the future.

To check an Instagram professional account's current rate limit usage, query the GET /<IG_ID>/content_publishing_limit endpoint.

Create a container

In order to publish a media object, it must have a container. To create the media container and upload a media file, send a POST request to the /<IG_ID>/media endpoint with the following parameters: access_token – Set to your app user's access token image_url or video_url – Set to the path of the image or video. We will cURL your image using the passed in URL so it must be on a public server. media_type — If the container will be for a video, set to VIDEO, REELS, or STORIES. is_carousel_item – If the media will be part of a carousel, set to true upload_type – Set to resumable, if creating a resumable upload session for a large video file Visit the Instagram User Media Endpoint Reference for additional optional parameters.

Example Request

Formatted for readability.

curl -X POST "https://<HOST_URL>/<LATEST_API_VERSION>/<IG_ID>/media"
     -H "Content-Type: application/json" 
     -H "Authorization: Bearer <ACCESS_TOKEN>" 
     -d '{
           "image_url":"https://www.example.com/images/bronz-fonz.jpg"
         }'

On success, your app receives a JSON response with the Instagram Container ID.

{
  "id": "<IG_CONTAINER_ID>"  
}

Create a carousel container

To publish up to 10 images, videos, or a combination of the two, in a single post, a carousel post, you must create a carousel container. This carousel containter will contain a list of all media containers. To create the carousel container, send a POST request to the /<IG_ID>/media endpoint with the following parameters: media_type — Set to CAROUSEL. Indicates that the container is for a carousel. children — A comma separated list of up to 10 container IDs of each image and video that should appear in the published carousel.

Limitations

• Carousels are limited to 10 images, videos, or a mix of the two.
• Carousel images are all cropped based on the first image in the carousel, with the default being a 1:1 aspect ratio.
• Accounts are limited to 50 published posts within a 24-hour period. Publishing a carousel counts as a single post.

Example Request

Formatted for readability.

curl -X POST "https://graph.instagram.com/v22.0/90010177253934/media"
     -H "Content-Type: application/json" 
     -d '{  
           "caption":"Fruit%20candies"
           "media_type":"CAROUSEL"
           "children":"<IG_CONTAINER_ID_1>,<IG_CONTAINER_ID_2>,<IG_CONTAINER_ID_3>"
         }'

On success, your app receives a JSON response with the Instagram Carousel Container ID.

{
  "id": "<IG_CAROUSEL_CONTAINER_ID>" 
}

Resumable Upload Session

If you created a container for a resumable video upload in Step 1, your need to upload the video before it can be published.

Most API calls use the graph.facebook.com host however, calls to upload videos for Reels use rupload.facebook.com.

The following file sources are supported for uploaded video files:

• A file located on your computer
• A file hosted on a public facing server, such as a CDN

To start the upload session, send a POST request to the /<IG_MEDIA_CONTAINER_ID endpoint on the rupload.facebook.com host with the following parameters:

• access_token

Sample request upload a local video file

With the ig-container-id returned from a resumable upload session call, upload the video.

• Be sure the host is rupload.facebook.com.
• All media_type shares the same flow to upload the video.
• ig-container-id is the ID returned from resumable upload session calls.
• access-token is the same one used in previous steps.
• offset is set to the first byte being upload, generally 0.
• file_size is set to the size of your file in bytes.
• Your_file_local_path is set to the file path of your local file, for example, if uploading a file from, the Downloads folder on macOS, the path is @Downloads/example.mov.

curl -X POST "https://rupload.facebook.com/ig-api-upload/<API_VERSION>/<IG_MEDIA_CONTAINER_ID>`" \
     -H "Authorization: OAuth <ACCESS_TOKEN>" \
     -H "offset: 0" \
     -H "file_size: Your_file_size_in_bytes" \
     --data-binary "@my_video_file.mp4"

Sample request upload a public hosted video

curl -X POST "https://rupload.facebook.com/ig-api-upload/<API_VERSION>/<IG_MEDIA_CONTAINER_ID>`" \
     -H "Authorization: OAuth <ACCESS_TOKEN>" \
     -H "file_url: https://example_hosted_video.com"

Sample Response

// Success Response Message
{
  "success":true,
  "message":"Upload successful."
}

// Failure Response Message
{
  "debug_info":{
    "retriable":false,
    "type":"ProcessingFailedError",
    "message":"{\"success\":false,\"error\":{\"message\":\"unauthorized user request\"}}"
  }
}

Publish the container

To publish the media,

Send a POST request to the /<IG_ID>/media_publish endpoint with the following parameters:

• creation_id set to the container ID, either for a single media container or a carousel container

Example Request

Formatted for readability.

    
curl -X POST "https://<HOST_URL>/<LATEST_API_VERSION>/<IG_ID>/media_publish"
     -H "Content-Type: application/json" 
     -H "Authorization: Bearer <ACCESS_TOKEN>"     
     -d '{
           "creation_id":"<IG_CONTAINER_ID>" 
         }'

On success, your app receives a JSON response with the Instagram Media ID.

{
  "id": "<IG_MEDIA_ID>"
}

Reels posts

Reels are short-form videos that appears in the Reels tab of the Instagram app. To publish a reel, create a container for the video and include the media_type=REELS parameter along with the path to the video using the video_url parameter.

If you publish a reel and then request its media_type field, the value returned is VIDEO. To determine if a published video has been designated as a reel, request its media_product_type field instead.

You can use the code sample on GitHub (insta_reels_publishing_api_sample) to learn how to publish Reels to Instagram.

Story posts

To publish a reel, create a container for the media object and include the media_type parameter set to STORIES.

If you publish a story and then request its media_type field, the value will be returned as IMAGE/VIDEO. To determine if a published image/video is a story, request its media_product_type field instead.

Troubleshooting

If you are able to create a container for a video but the POST /<IG_ID>/media_publish endpoint does not return the published media ID, you can get the container's publishing status by querying the GET /<IG_CONTAINER_ID>?fields=status_code endpoint. This endpoint will return one of the following:

• EXPIRED — The container was not published within 24 hours and has expired.
• ERROR — The container failed to complete the publishing process.
• FINISHED — The container and its media object are ready to be published.
• IN_PROGRESS — The container is still in the publishing process.
• PUBLISHED — The container's media object has been published.

We recommend querying a container's status once per minute, for no more than 5 minutes.

Errors

See the Error Codes reference.

Next Steps

Now that you have published to an Instagram professional account, learn how to moderate comments on your media.