IG User Media

IGTV media is now supported in v10.0+. This applies to all endpoints except those used for content publishing and webhooks. To support this change, new media_product_type and video_title fields have been added to the IG Media node. IGTV media must have been shared to Instagram at the time of publish (Post a Preview or Share Preview to Feed enabled) in order to be accessible via the API.

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

Creating

Creating Photo Containers

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

Uploads an image and creates an IG Container which can be used to publish the image.

If successful, this edge will respond with the newly created container's id. You can then use the container to publish the image. Containers expire after 24 hours.

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

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}

Uploads a video and creates an IG Container which can be used to publish the video.

If successful, this edge will respond with the newly created container's id. You can then use the container to publish the video. Containers expire after 24 hours.

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

Limitations

Publishing to IGTV is not supported.

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.

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.

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.