IG User Media

Represents a collection of IG Media objects on an IG User.

Creating

POST /<YOUR_APP_USERS_INSTAGRAM_USER_ID>/media

  • Create an image, carousel, story or reel IG Container for use in the post publishing process. See the Content Publishing guide for complete publishing steps.

Steps to publish a media object include the following:

  1. Create a container
  2. Upload the media to the container
  3. Publish the container

Limitations

General Limitations

  • Containers expire after 24 hours
  • An Instagram account can only create 400 containers within a rolling 24 hour period
  • If the Page connected to the targeted Instagram professional account requires Page Publishing Authorization (PPA), PPA must be completed or the request will fail
  • If the Page connected to the targeted Instagram professional account requires two-factor authentication, the Facebook User must also have performed two-factor authentication or the request will fail
  • We strongly recommended the HTTP IETF standard character set for URLs, URLs that contain only US ASCII characters, or the request will fail

Reels Limitations

  • Reels cannot appear in carousels
  • Account privacy settings are respected upon publish. For example, if Allow remixing is enabled, published reels will have remixing enabled upon publish but remixing can be disabled on published reels manually through the Instagram app.
  • Music tagging is only available for original audio.

Story Limitations

  • Stories expire after 24 hours.
  • Support either video URL or Reels URL but not both.
  • Publishing stickers (i.e., link, poll, location) is not supported.

Requirements

TypeDescription

Access Tokens

User

Business Roles

If creating containers for product tagging, the app user must have an admin role on the Business Manager that owns the IG User's Instagram Shop.

Permissions

instagram_basic
instagram_content_publish
pages_read_engagement or pages_show_list

If the app user was granted a role on the Page via the Business Manager, you will also need one of:

ads_management
business_management

If creating containers for product tagging, you will also need:

catalog_management
instagram_shopping_tag_products

Tasks

Your app user must be able to perform the MANAGE or CREATE_CONTENT tasks on the Page linked to their Instagram professional account.

Image Specifications

  • Format: JPEG
  • File size: 8 MB maximum.
  • Aspect ratio: Must be within a 4:5 to 1.91:1 range
  • Minimum width: 320 (will be scaled up to the minimum if necessary)
  • Maximum width: 1440 (will be scaled down to the maximum if necessary)
  • Height: Varies, depending on width and aspect ratio
  • Color Space: sRGB. Images using other color spaces will have their color spaces converted to sRGB.

Reel Specifications

The following are the specifications for Reels:

  • Container: MOV or MP4 (MPEG-4 Part 14), no edit lists, moov atom at the front of the file.
  • Audio codec: AAC, 48khz sample rate maximum, 1 or 2 channels (mono or stereo).
  • Video codec: HEVC or H264, progressive scan, closed GOP, 4:2:0 chroma subsampling.
  • Frame rate: 23-60 FPS.
  • Picture size:
    • Maximum columns (horizontal pixels): 1920
    • Required aspect ratio is between 0.01:1 and 10:1 but we recommend 9:16 to avoid cropping or blank space.
  • Video bitrate: VBR, 25Mbps maximum
  • Audio bitrate: 128kbps
  • Duration: 15 mins maximum, 3 seconds minimum
  • File size: 1GB maximum

The following are the specifications for a Reels cover photo:

  • Format: JPEG
  • File size: 8MB maximum
  • Color Space: sRGB. Images that use other color spaces will be converted to sRGB.
  • Aspect ratio: We recommend 9:16 to avoid cropping or blank space. If the aspect ratio of the original image is not 9:16, we crop the image and use the middle most 9:16 rectangle as the cover photo for the reel. If you share a reel to your feed, we crop the image and use the middle most 1:1 square as the cover photo for your feed post.

Story Image Specifications

  • Format: JPEG
  • File size: 8 MB maximum.
  • Aspect ratio: We recommended 9:16 to avoid cropping or blank space
  • Color Space: sRGB. Images using other color spaces will have their color spaces converted to sRGB

Story Video Specifications

  • Container: MOV or MP4 (MPEG-4 Part 14), no edit lists, moov atom at the front of the file.
  • Audio codec: AAC, 48khz sample rate maximum, 1 or 2 channels (mono or stereo).
  • Video codec: HEVC or H264, progressive scan, closed GOP, 4:2:0 chroma subsampling.
  • Frame rate: 23-60 FPS.
  • Picture size:
    • Maximum columns (horizontal pixels): 1920
    • Required aspect ratio is between 0.1:1 and 10:1 but we recommend 9:16 to avoid cropping or blank space
  • Video bitrate: VBR, 25Mbps maximum
  • Audio bitrate: 128kbps
  • Duration: 60 seconds maximum, 3 seconds minimum
  • File size: 100MB maximum

Request Syntax

Image Containers

POST https://graph.facebook.com/v21.0/<YOUR_APP_USERS_INSTAGRAM_USER_ID>/media
?image_url=<IMAGE_URL>
&is_carousel_item=<TRUE_OR_FALSE>
&caption=<IMAGE_CAPTION>
&location_id=<LOCATION_PAGE_ID>
&user_tags=<ARRAY_OF_USERS_FOR_TAGGING>>
&product_tags=<ARRAY_OF_PRODUCTS_FOR_TAGGING>
&access_token=<USER_ACCESS_TOKEN>

Reel Containers

Standard upload
POST https://graph.facebook.com/v21.0/<YOUR_APP_USERS_INSTAGRAM_USER_ID>/media
?media_type=REELS
&video_url=<REEL_URL>
&caption=<IMAGE_CAPTION>
&share_to_feed=<TRUE_OR_FALSE>
&collaborators=<COLLABORATOR_USERNAMES>
&cover_url=<COVER_URL>
&audio_name=<AUDIO_NAME>
&user_tags=<ARRAY_OF_USERS_FOR_TAGGING>>
&location_id=<LOCATION_PAGE_ID>
&thumb_offset=<THUMB_OFFSET>
&share_to_feed=<TRUE_OR_FALSE>
&access_token=<USER_ACCESS_TOKEN>
Resumable upload session
POST https://graph.facebook.com/v21.0/<YOUR_APP_USERS_INSTAGRAM_USER_ID>/media
?media_type=REELS
&upload_type=resumable
&caption=<IMAGE_CAPTION>
&collaborators=<COLLABORATOR_USERNAMES>
&cover_url=<COVER_URL>
&audio_name=<AUDIO_NAME>
&user_tags=<ARRAY_OF_USERS_FOR_TAGGING>>
&location_id=<LOCATION_PAGE_ID>
&thumb_offset=<THUMB_OFFSET>
&access_token=<USER_ACCESS_TOKEN>

On success, an ig-container-id and a uri is returned in the response, which will be used in subsequent steps, such as:

{
  "id": "<IG_CONTAINER_ID>",
  "uri": "https://rupload.facebook.com/ig-api-upload/v21.0/<IG_CONTAINER_ID>"
}

Carousel Containers

Carousel containers only. To create carousel item containers, create image or video containers instead (reels are not supported). See Carousel Posts for complete publishing steps.

Standard upload
POST https://graph.facebook.com/v21.0/<YOUR_APP_USERS_INSTAGRAM_USER_ID>/media
?media_type=CAROUSEL
&caption=<IMAGE_CAPTION>
&share_to_feed=<TRUE_OR_FALSE>
&collaborators=<COLLABORATOR_USERNAMES>
&location_id=<LOCATION_PAGE_ID>
&product_tags=<ARRAY_OF_PRODUCTS_FOR_TAGGING>
&children=<ARRAY_OF_CAROUSEL_CONTAINTER_IDS>
&access_token=<USER_ACCESS_TOKEN>
Resumable upload session
POST https://graph.facebook.com/v21.0/<YOUR_APP_USERS_INSTAGRAM_USER_ID>/media
?media_type=VIDEO
&is_carousel_item=true
&upload_type=resumable
&access_token=<USER_ACCESS_TOKEN>

On success, an ig-container-id and a uri is returned in the response, which will be used in subsequent steps.

Image Story Containers

POST https://graph.facebook.com/v21.0/<YOUR_APP_USERS_INSTAGRAM_USER_ID>/media
?image_url=<IMAGE_URL>
&media_type=STORIES
&access_token=<USER_ACCESS_TOKEN>

Video Story Containers

Standard upload
POST https://graph.facebook.com/v21.0/<YOUR_APP_USERS_INSTAGRAM_USER_ID>/media
?video_url=<VIDEO_URL>
&media_type=STORIES
&access_token=<USER_ACCESS_TOKEN>
Resumable upload session
POST https://graph.facebook.com/v21.0/<YOUR_APP_USERS_INSTAGRAM_USER_ID>/media
?media_type=STORIES
&upload_type=resumable
&access_token=<USER_ACCESS_TOKEN>

On success, an Instagram container ID and a URI is returned in the response, which will be used in subsequent steps.

Upload a video through resumable upload protocol

Once the Instagram container ID returns from a resumable upload session call, send a POST request to the https://rupload.facebook.com/ig-api-upload/

v21.0

/<IG_CONTAINER_ID> endpoint.

  • All media_type shares the same flow to upload the video.
  • ig-container-id is the ID from the resumable reels, carousel and video container upload session examples above.
  • access-token is the same one used in other 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 sets 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/v21.0/<IG_CONTAINER_ID>" \
     -H "Authorization: OAuth <USER_ACCESS_TOKEN>" \
     -H "offset: 0" \
     -H "file_size: Your_file_size_in_bytes" \
     --data-binary "@Your_local_file_path.extension"

On success, you should see response like this example:

{
  "success":true,
  "message":"Upload successful. ..."
}  

Upload a video from a hosted URL

This service can also support video upload from a hosted URL.

curl -X POST "https://rupload.facebook.com/ig-api-upload/v21.0/<IG_CONTAINER_ID>" \
     -H "Authorization: OAuth <USER_ACCESS_TOKEN>" \
     -H "file_url: <VIDEO_URL>"

Path Parameters

PlaceholderValue

`

v21.0

`

API version.

<YOUR_APP_USERS_INSTAGRAM_USER_ID>
Required

App user's app-scoped user ID.

Query String Parameters

KeyPlaceholderDescription

access_token

<USER_ACCESS_TOKEN>

Required. App user's User access token.

audio_name

<AUDIO_NAME>

For Reels only. Name of the audio of your Reels media. You can only rename once, either while creating a reel or after from the audio page.

caption

<IMAGE_CAPTION>

A caption for the image, video, or carousel. Can include hashtags (example: #crazywildebeest) and usernames of Instagram users (example: @natgeo). @Mentioned Instagram users receive a notification when the container is published. Maximum 2200 characters, 30 hashtags, and 20 @ tags.


Not supported on images or videos in carousels.

collaborators

<LIST_OF_COLLABORATORS>

For Feed image, Reels and Carousels only. A list of up to 3 instagram usernames as collaborators on an ig media.


Not supported for Stories.

children

<ARRAY_OF_CAROUSEL_CONTAINTER_IDS

Required for carousels. Applies only to carousels. An array of up to 10 container IDs of each image and video that should appear in the published carousel. Carousels can have up to 10 total images, vidoes, or a mix of the two.

cover_url

<COVER_URL>

For Reels only. The path to an image to use as the cover image for the Reels tab. We will cURL the image using the URL that you specify so the image must be on a public server. If you specify both cover_url and thumb_offset, we use cover_url and ignore thumb_offset. The image must conform to the specifications for a Reels cover photo.

image_url

<IMAGE_URL>

For images only and required for images. The path to the image. We will cURL the image using the URL that you specify so the image must be on a public server.

is_carousel_item

<TRUE_OR_FALSE>

Applies only to images and video. Set to true. Indicates image or video appears in a carousel.

location_id

<LOCATION_PAGE_ID>

The ID of a Page associated with a location that you want to tag the image or video with.


Use the Pages Search API to search for Pages whose names match a search string, then parse the results to identify any Pages that have been created for a physical location. Include the location field in your query and verify that the Page you want to use has location data. Attempting to create a container using a Page that has no location data will fail with coded exception INSTAGRAM_PLATFORM_API__INVALID_LOCATION_ID.


Not supported on images or videos in carousels.

media_type

<MEDIA_TYPE>

Required for carousels, stories, and reels. Indicates container is for a carousel, story or reel. Value can be:

  • CAROUSEL
  • REELS
  • STORIES

product_tags

<ARRAY_OF_PRODUCTS_FOR_TAGGING>

Required for product tagging. Applies only to images and videos. An array of objects specifying which product tags to tag the image or video with (maximum of 5; tags and product IDs must be unique). Each object should have the following information:


  • product_idRequired. Product ID.
  • xImages only. An optional float that indicates percentage distance from left edge of the published media image. Value must be within 0.01.0 range.
  • yImages only. An optional float that indicates percentage distance from top edge of the published media image. Value must be within 0.01.0 range.

For example:


[{product_id:'3231775643511089',x: 0.5,y: 0.8}]

share_to_feed

<TRUE_OR_FALSE>

For Reels only. When true, indicates that the reel can appear in both the Feed and Reels tabs. When false, indicates the reel can only appear in the Reels tab.

Neither value determines whether the reel actually appears in the Reels tab because the reel may not meet eligibilty requirements or may not be selected by our algorithm. See reel specifications for eligibility critera.

thumb_offset

<THUMB_OFFSET>

For videos and reels. Location, in milliseconds, of the video or reel frame to be used as the cover thumbnail image. The default value is 0, which is the first frame of the video or reel. For reels, if you specify both cover_url and thumb_offset, we use cover_url and ignore thumb_offset.

upload_type

<UPLOAD_TYPE>

An optional parameter for users want to upload video through the rupload protocol, values can be set to lowercase string value: resumable.

user_tags

<ARRAY_OF_USERS_FOR_TAGGING>>

Required for user tagging in images and videos. Videos in carousels are not supported. An array of public usernames and x/y coordinates for any public Instagram users who you want to tag in the image. Each object should have the following information:

  • usernamesRequired. Usernames.
  • xImages only. An optional float that indicates percentage distance from left edge of the published media image. Value must be within 0.01.0 range.
  • yImages only. An optional float that indicates percentage distance from top edge of the published media image. Value must be within 0.01.0 range.

video_url

<VIDEO_URL>

Required for videos and reels. Applies only to videos and reels. Path to the video. We cURL the video using the passed-in URL, so it must be on a public server.

Response

A JSON-formatted object containing an IG Container ID which you can use to publish the container.

Video uploads are asynchronous, so receiving a container ID does not guarantee that the upload was successful. To verify that a video has been uploaded, request the status_code field on the IG Container. If its value is FINISHED, the video was uploaded successfully.

{
  "id":"<IG_CONTAINER_ID>"
}

Sample Request

POST graph.facebook.com/17841400008460056/media
  ?image_url=curls//www.example.com/images/bronzed-fonzes.jpg
  &caption=#BronzedFonzes!
  &collaborators= [‘username1’,’username2’]
  &user_tags=[
    {
      username:'kevinhart4real',
      x: 0.5,
      y: 0.8
    },
    {
      username:'therock',
      x: 0.3,
      y: 0.2
    }
  ]

Sample Response

{
  "id": "17889455560051444"
}

Reading

GET /<YOUR_APP_USERS_INSTAGRAM_USER_ID>/media

Get all IG Media on an IG User.

Limitations

Requirements

TypeDescription

Access Tokens

User

Permissions

instagram_basic
pages_read_engagement or pages_show_list

If the app user was granted a role on the Page via the Business Manager, you will also need one of:

ads_management
business_management

Time-based Pagination

This endpoint supports time-based pagination. Include since and until query-string parameters with Unix timestamp or strtotime data values to define a time range.

Sample Request

GET graph.facebook.com/v21.0/17841405822304914/media

Sample Response

{
  "data": [
    {
      "id": "17895695668004550"
    },
    {
      "id": "17899305451014820"
    },
    {
      "id": "17896450804038745"
    },
    {
      "id": "17881042411086627"
    },
    {
      "id": "17869102915168123"
    }
  ]
}

Updating

This operation is not supported.

Deleting

This operation is not supported.

See Also