IG User Media

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

Creating

Creating Photo Containers

POST /{ig-user-id}/media?image_url={image-url}

Creates a media container for a photo IG Media object.

Photo Requirements

  • Maximum file size: 8MiB
  • 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
  • Formats: JPEG

Page Requirements

If the Page connected to the targeted Instagram Business account requires Page Publishing Authorization (PPA), PPA must be completed or the request will fail.

Color Space

The API supports the sRGB color space. Images that use other color spaces will have their color spaces converted to sRGB.

Query String Parameters

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. Maximum 2200 characters, 30 hashtags, and 20 @ tags.

{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 Page associated with a location that you want to tag the photo 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.

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

An access token of a Facebook User who is able to perform MANAGE or CREATE_CONTENT tasks on the Page connected to the Instagram User account, with the following permissions:

  • instagram_basic
  • instagram_content_publish
  • pages_read_engagement OR pages_show_list

If the Page connected to the Instagram User has enabled two-factor authentication, the Facebook User must also have performed two-factor authentication or the request will fail.

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}

Creates a media container for a video IG Media object.

Video Requirements

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
  • Video bitrate: VBR, 5Mbps maximum
  • Audio bitrate: 128kbps
  • Duration: 60 seconds maximum, 3 seconds minimum
  • File size: 100MB maximum

Query String Parameters

Parameter Description

{caption}

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. Maximum 2200 characters, 30 hashtags, and 20 @ tags.

{location_id}

The ID of a Page associated with a location that you want to tag the 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.

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

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
  • pages_read_engagement OR pages_show_list

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

Errors

See Errors.

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.
  • IGTV objects are not supported.

Permissions

A Facebook User access token with the following permissions:

  • instagram_basic
  • pages_read_engagement
  • 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
  • pages_read_engagement
  • 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.