Instagram Platform

IG Media

Represents an Instagram album, photo, or video (uploaded video, live video, video created with the Instagram TV app, reel, or story).

Beginning June 3, 2024, you can use the boost_eligibility_info field as a convenient and efficient way to determine whether media is eligible to be boosted as an ad and boost_ads_list to trace past boost Instagram ad information related to the ad. See the blog for more information. Available for the Instagram Graph API only.

Creating

This operation is not supported.

Reading

GET /<IG_MEDIA_ID>

Gets fields and edges on IG media.

Limitations

  • Fields that return aggregated values don't include ads-driven data. For example, comments_count counts comments on a photo, but not comments on ads that contain that photo.
  • Captions don't include the @ symbol unless the app user is also able to perform Admin-equivalent tasks on the app.
  • Some fields, such as permalink, cannot be used on photos within albums (children).
  • Live video IG Media can only be read while they are being broadcast.
  • This API returns only data for media owned by Instagram professional accounts. It can not be used to get data for media owned by personal Instagram accounts.

Request Syntax

GET https://graph.facebook.com/<API_VERSION>/<IG_MEDIA_ID>
  ?fields=<LIST_OF_FIELDS>
  &access_token=<ACCESS_TOKEN>

Path Parameters

PlaceholderValue

<API_VERSION>

API version.

<IG_MEDIA_ID>

Required. ID for the media to be published.

Query String Parameters

KeyPlaceholderValue

access_token

<ACCESS_TOKEN>

Required. App user's user access token

fields

<LIST_OF_FIELDS>

Comma-separated list of fields you want returned.

Fields

Public fields can be read via field expansion.

FieldDescription

boost_ads_list

Offers an overview of all Instagram ad information associated with the organic media. It includes relative ad ID and ad delivery status. Available for Instagram Graph API only.

boost_eligibility_info

The field provides information about boosting eligibility of a IG instagram media as an ad and additional details if not eligible. Available for Instagram Graph API only.

caption
Public

Caption. Excludes album children. The @ symbol is excluded, unless the app user can perform admin-equivalent tasks on the Facebook Page connected to the Instagram account used to create the caption (Instagram Graph API only.).

comments_count
Public

Count of comments on the media. Excludes comments on album child media and the media's caption. Includes replies on comments.

copyright_check_information.status

Returns status and matches_found objects

status objectsDescription

status

  • completed – the detection process has finished
  • error – an error occurred during the detection process
  • in_progress – the detection process is ongoing
  • not_started – the detection process has not started

matches_found

Set to one of the following:

  • false if the video does not violate copyright,
  • true if the video does violate copyright

If a video is violating copyright, the copyright_matches is returned with an array of objects about the copyrighted material, when the violation is occurring in the video, and the actions take to mitigate the violation.

copyright_matches objectsDescription

author

the author of the copyrighted video

content_title

the name of the copyrighted video

matched_segments

An array of objects with the following key-value pairs: * duration_in_seconds – the number of seconds the content violates copyright * segment_type – either AUDIO or VIDEO * start_time_in_seconds – set to the start time of the video

owner_copyright_policy

Objects returned include:

  • name – The name for the copyright owners' policy

  • actions – An array of action objects with the mitigations steps taken defined by the copyright owner's policy. May include different mitigations steps for different locations.

    • action – The mitigation action taken against the video violating copyright. Different mitigation steps can be taken for different countries. Can be one of the following values:
      • BLOCK – The video is blocked from the audiences listed in the geos array
      • MUTE - The video is muted for audiences listed in the geos array

id
Public

Media ID.

is_comment_enabled

Indicates if comments are enabled or disabled. Excludes album children.

is_shared_to_feed
Public

For Reels only. When true, indicates that the reel can appear in both the Feed and Reels tabs. When false, indicates that 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.

like_count

Count of likes on the media, including replies on comments. Excludes likes on album child media and likes on promoted posts created from the media.


If queried indirectly through another endpoint or field expansion the like_count field is omitted if the media owner has hidden like counts.

media_product_type
Public

Surface where the media is published. Can be AD, FEED, STORY or REELS. Available for Instagram Graph API only.

media_type
Public

Media type. Can be CAROUSEL_ALBUM, IMAGE, or VIDEO.

media_url
Public

The URL for the media.

The media_url field is omitted from responses if the media contains copyrighted material or has been flagged for a copyright violation. Examples of copyrighted material can include audio on reels.

owner
Public

Instagram user ID who created the media. Only returned if the app user making the query also created the media; otherwise, username field is returned instead.

permalink
Public

Permanent URL to the media.

shortcode
Public

Shortcode to the media.

thumbnail_url
Public

Media thumbnail URL. Only available on VIDEO media.

timestamp
Public

ISO 8601-formatted creation date in UTC (default is UTC ±00:00).

username
Public

Username of user who created the media.

Edges

Public edges can be returned through field expansion.

EdgeDescription

children
Public.

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

collaborators

Represents a list of users who are added as collaborators on an IG Media object. Available for Instagram Graph API only.

comments

Represents a collection of IG Comments on an IG Media object.

insights

Represents social interaction metrics on an IG Media object. Available for Instagram Graph API only.

cURL Example

Example request

curl -X GET \
  'https://graph.instagram.com/v21.0/17895695668004550?fields=id,media_type,media_url,owner,timestamp&access_token=IGQVJ...'

Example response

{
  "id": "17918920912340654",
  "media_type": "IMAGE",
  "media_url": "https://sconten...",
  "owner": {
    "id": "17841405309211844"
  },
  "timestamp": "2019-09-26T22:36:43+0000"
}

Updating

POST /<IG_MEDIA_ID>

Enable or disable comments on an IG Media.

Limitations

Live video IG Media not supported.

Requirements

Instagram API with Instagram LoginInstagram API with Facebook Login

Access Tokens

  • Instagram User access token

Host URL

graph.instagram.com

graph.facebook.com

Login Type

Business Login for Instagram

Facebook Login for Business

Permissions
  • instagram_business_basic
  • instagram_business_manage_comments
  • instagram_basic
  • instagram_manage_comments
  • pages_read_engagement
  • pages_show_list

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

  • ads_management
  • business_management

Request Syntax

POST https://graph.facebook.com/<API_VERSION>/<IG_MEDIA_ID>
  ?comment_enabled=<BOOL>
  &access_token=<ACCESS_TOKEN>

Path Parameters

PlaceholderValue

<API_VERSION>

API version.

<IG_MEDIA_ID>

Required. IG Media ID.

Query String Parameters

KeyPlaceholderValue

access_token

<ACCESS_TOKEN>

Required. App user's user access token.

comment_enabled

<BOOL>

Required. Set to true to enable comments or false to disable comments.

cURL Example

Example request

curl -i -X POST \
 "https://graph.instagram.com/v21.0/17918920912340654?comment_enabled=true&access_token=EAAOc..."

Example response

{
  "success": true
}

Deleting

This operation is not supported.