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.

Requirements

This guide assumes you have read the Instagram API Overview and implemented the needed components for using this API, such as Instagram Login for Business to receive Instagram User access tokens and a webhooks server to receive notifications.

You will need the following:

Access Level

Advanced Access if your app serves Instagram professional accounts you don't own or manage
Standard Access if your app serves Instagram professional accounts you own or manage and have added to your app in the App Dashboard

Access tokens

An Instagram User access token requested from a person who can publish content on the Instagram professional account

Base URL

All endpoints can be accessed via the graph.instagram.com host.

Endpoints

/<IG_ID>/media — upload media and create media containers.
/<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.

IDs

The ID for the person who can publish content on the Instagram professional account (<IG_ID>)

Permissions

instagram_business_basic permission
instagram_business_content_publish permission

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.

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.

Single media posts

Publishing single image, video, story or reel is a two-step process:

Create a container from an image or video
Publish the container

Step 1: Create media container

Let's say you have an image at...

https://www.example.com/images/bronz-fonz.jpg

To create the media container, send a POST request to the /<IG_ID>/media endpoint with the following parameters:

image_url set to the URL for your image

Example Request

Formatted for readability.

curl -X POST "https://graph.instagram.com/v20.0/<IG_ID>/media"
     -H "Content-Type: application/json" 
     -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": "17889455560051444"  // Instagram Container ID
}

Step 2: Publish container

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

creation_id set to the <IG_CONTAINER_ID> from the previous step

Example Request

Formatted for readability.

curl -X POST "https://graph.instagram.com/v20.0/17841400008460056/media_publish"
     -H "Content-Type: application/json" 
     -d '{
           "creation_id=17889455560051444"
         }'

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

{
  "id": "17920238422030506" // Instagram Media ID
}

Carousel posts

You can publish up to 10 images, videos, or a mix of the two in a single post (a carousel post). Publishing carousels is a three step process:

Create a container for each image and video that will appear in the carousel.
Create a single carousel container for the containers.
Publish the carousel container.

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.

Step 1: Create media container

To create the media container, send a POST request to the /<IG_ID>/media endpoint with the following parameters:

is_carousel_item — Set to true. Indicates image or video will appear in a carousel.
image_url — (images only) The path to the image. We will cURL your image using the passed in URL so it must be on a public server.
media_type — (videos only) Set to VIDEO. Indicates media is a video.
video_url — (videos only) Path to the video. We will cURL your video using the passed in URL so it must be on a public server.

Example Request

Formatted for readability.

curl -X POST "https://graph.instagram.com/v20.0/90010177253934/media"
     -H "Content-Type: application/json" 
     -d '{
           "image_url":"https%3A%2F%2Fsol...",
           "is_carousel_item":"true"
         }'

On success, your app receives a JSON response with the Instagram Container ID for the image or video.

{
  "id": "17889455560051444"  // Instagram Container ID
}

Repeat this step for each image or video that should appear in the carousel.

Step 2: Create carousel container

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 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.

Example Request

Formatted for readability.

curl -X POST "https://graph.instagram.com/v20.0/90010177253934/media"
     -H "Content-Type: application/json" 
     -d '{  
           "caption":"Fruit%20candies"
           "media_type":"CAROUSEL"
           "children":"17899506308402767,18193870522147812,17853844403701904"
         }'

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

{
  "id": "18000748627392977" // INSTAGRAM Carousel Container ID
}

Step 3: Publish carousel container

To publish the carousel container, send a POST request to the /<IG_ID>/media_publish endpoint with the following parameters:

creation_id — The carousel container ID.

Example Request

curl -X POST "https://graph.instagram.com/v20.0/90010177253934/media_publish"
     -H "Content-Type: application/json" 
     -d '{  
           "creation_id":"18000748627392977"
         }'

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

{
  "id": "90010778390276"  //Instagram Media ID
}

Reels posts

Reels are short-form videos that are eligible to appear in the Reels tab of the Instagram app if they meet certain specifications and are selected by our algorithm. To publish a reel, follow the steps for publishing a single media post and include the media_type=REELS parameter along with the path to the video using the video_url parameter.

Reels are not a new media type, even though you set media_type=REELS when you publish a reel. 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.

To make it more convenient for developers, Meta has published the full set of Graph API calls for Instagram Reels on the Postman API Platform. For more information, see Postman Collections for Facebook Reels and Instagram Reels.

For more information about Reels, see Reels Developer Documentation.

Story posts

To publish a story, follow the steps for publishing a single media post and include the media_type parameter set to STORIES.

Note: Stories are not a new media type even though you are setting media_type=STORIES when publishing a story. 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 has been designated as 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.