Instagram Graph API

IG User Media

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

Creating

POST /{ig-user-id}/media

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

Limitations

  • Containers expire after 24 hours.
  • If the Page connected to the targeted Instagram Business account requires Page Publishing Authorization (PPA), PPA must be completed or the request will fail.
  • If the Page connected to the targeted Instagram Business account requires two-factor authentication, the Facebook User must also have performed two-factor authentication or the request will fail.
  • Publishing to Instagram TV is not supported.

Requirements

TypeDescription

Access Tokens

User

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

Tasks

The app user whose token is used in the request must be able to perform MANAGE or CREATE_CONTENT tasks on the Page connected to the targeted Instagram 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.

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
    • Minimum aspect ratio [cols / rows]: 4 / 5
    • Maximum aspect ratio [cols / rows]: 16 / 9
  • Video bitrate: VBR, 5Mbps maximum
  • Audio bitrate: 128kbps
  • Duration: 60 seconds maximum, 3 seconds minimum
  • File size: 100MB maximum

Request Syntax

Images

POST https://graph.facebook.com/{api-version}/{ig-user-id}/media
?image_url={image-url}
&is_carousel_item={is-carousel-item}
&caption={caption}
&location_id={location-id}
&user_tags={user-tags}
&access_token={access-token}

Videos

POST https://graph.facebook.com/{api-version}/{ig-user-id}/media
?media_type=VIDEO
&video_url={video-url}
&is_carousel_item={is-carousel-item}
&caption={caption}
&location_id={location-id}
&thumb_offset={thumb-offset}
&access_token={access-token}

Carousels

POST https://graph.facebook.com/{api-version}/{ig-user-id}/media
?media_type={media-type}
&caption={caption}
&location_id={location-id}
&children={children}
&access_token={access-token}

Path Parameters

PlaceholderValue

{api-version}

API version.

{ig-user-id}
Required

App user's app-scoped user ID.

Query String Parameters

KeyPlaceholderDescription

access_token

{access-token}

Required. App user's User access token.

caption

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

children

{children}

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.

image_url

{image-url}

Required for images. Applies only to images. The path to the image. We will cURL the image using the passed in URL so it must be on a public server.

is_carousel_item

{is-carousel-item}

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

location_id

{location-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 videos and carousels. Applies only to videos and carousels. Set to VIDEO for videos or CAROUSEL for carousels. Indicates container is for a video or carousel.

thumb_offset

{thumb-offset}

Applies only to videos. Location, in milliseconds, of the video frame to be used as the video's cover thumbnail image. Default value is 0, which is the first frame of the video.

user_tags

{user-tags}

Applies only to images and carousels. An array of public usernames and x/y coordinates for any public Instagram users who you want to tag in the image. The array must be formatted in JSON and contain a username, x, and y, property, such as [{username:'natgeo',x:0.5,y:1.0}]. x and y values must be float numbers that originate from the top-left of the image, with a range of 0.0–1.0. Tagged users receive a notification when you publish the media container.

video_url

{video-url}

Required for videos. Applies only to videos. 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=https//www.example.com/images/bronzed-fonzes.jpg
  &caption=#BronzedFonzes!
  &user_tags=[
    {
      username:'kevinhart4real',
      x: 0.5,
      y: 0.8
    },
    {
      username:'therock',
      x: 0.3,
      y: 0.2
    }
  ]

Sample Response

{
  "id": "17889455560051444"
}

Reading

GET /{ig-user-id}/media

Get all IG Media on an IG User.

Limitations

  • Returns a maximum of 10K of the most recently created media.
  • Story IG Media not supported, use the GET /{ig-user-id}/stories endpoint instead.

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 paramaters with Unix timestamp or strtotime data values to define a time range.

Sample Request

GET graph.facebook.com/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.