Instagram Graph API

Media

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

This edge allow you to:

Creating

Creating Photo Containers

POST /{ig-user-id}/media?image_url={image_url}&caption={caption}&location_id={location_id}&user_tags={user_tags}

Creates a media container for a photo IG Media object. This endpoint is only available to partners in the Content Publishing API beta program.

Photos must meet the following specifications:

  • Maximum file size: 8MB
  • Aspect ratio: Must be within a 4:5 to 1.91:1 range
  • Minimum resolution: 150x150 (lower resolutions will be scaled up to the minimum)
  • Maximum resolution: 1920x1080 (higher resolutions will be scaled down to the maximum)
  • Formats: JPEG, PNG, BMP, and non-animated GIFs

Query String Parameters

Query string parameters are optional unless indicated as required.

Parameter Description

{caption}

A caption for the photo. Like the app, you can include hashtags (e.g., #crazywildebeest) and usernames of Instagram users (e.g., @natgeo). @Mentioned Instagram users will receive a notification when you publish the media object container.

{image_url} (required)

The path to the photo. We will cURL your photo using the passed in URL so it must be on a public server.

{location_id}

The ID of a Places Graph Place location you want to tag the photo with. Use the Places Search API to discover Place IDs.

{user_tags}

An array of public usernames and x/y coordinates for any public Instagram users who you want to tag in the photo. 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 will receive a notification when you publish the media container.

If successful, this edge will respond with the newly created media object container's id. You can then use the id to publish the media object container. If you don't publish the media object container within 24 hours, it will expire.

Permissions

A Facebook User access token with the following permissions:

  • instagram_basic
  • instagram_content_publish
  • manage_pages

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"
}

Creating Video Containers

POST /{ig-user-id}/media?media_type=video&video_url={video_url}&caption={caption}&location_id={location_id}&thumb_offset={thumb_offset}

Creates a media container for a video IG Media object. This endpoint is only available to partners in the Content Publishing API beta program.

Videos must meet the following 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
  • Bitrate: VBR, 5Mbps maximum
  • Duration: 60 seconds maximum, 3 seconds minimum
  • File size: 100MB maximum

Query String Parameters

Query string parameters are optional unless indicated as required.

Parameter Description

{caption}

A caption for the video. Like the app, you can include hashtags (e.g., #crazywildebeest) and usernames of Instagram users (e.g., @natgeo). @Mentioned users will receive a notification when you publish the media object container.

{location_id}

The ID of a Places Graph Place location you want to tag the photo with. Use the Places Search API to discover Place IDs.

{thumb_offset}

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.

{video_url} (required)

The path to the video. We will cURL your video using the passed in URL so it must be on a public server.

If successful, this edge will respond with the newly created media object container's id. You can then use the id to publish the media object container. If you don't publish the media object container within 24 hours, it will expire.

Permissions

A Facebook User access token with the following permissions:

  • instagram_basic
  • instagram_content_publish
  • manage_pages

Sample Request

POST graph.facebook.com/17841400008460056/media
  ?media_type=VIDEO
  &video_url=https//www.example.com/videos/hungry-fonzes.mov
  &caption=#Heyyyyyyyy!

Sample Response

{
  "id": "17889455560051444"
}

Reading

Getting Media Objects

GET /{ig-user-id}/media

Gets all IG Media objects on an IG User.

Limitations

This edge will return a maximum of 10K of the most recently created media objects.

Permissions

A Facebook User access token with the following permissions:

  • instagram_basic
  • manage_pages or pages_show_list

If the token is from a User whose Page role was granted via the Business Manager, one of the following permissions is also required:

  • ads_management
  • manage_pages
  • business_management

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.