Instagram oEmbed

You can query the Instagram oEmbed endpoint to get an Instagram post’s embed HTML and basic metadata in order to display the post in another website or app. Supports photo, video, Reel, and Guide posts.

Common Uses

Rendering posts in messaging apps.
Embedding posts in websites and blogs.
Rendering posts in a content management systems.

Endpoints

Endpoint	Description
`GET /instagram_oembed`	Get an Instagram post's embed HTML and basic metadata.

Requirements

a Facebook developer account
a Facebook app in Live mode
an access token
App Review for the oEmbed Read feature

Limitations

The Instagram oEmbed endpoint is only meant to be used for embedding Instagram content in websites and apps. It is not to be used for any other purpose. Using metadata and page, post, or video content (or their derivations) from the endpoint for any purpose other than providing a front-end view of the page, post, or video is strictly prohibited. This prohibition encompasses consuming, manipulating, extracting, or persisting the metadata and content, including but not limited to deriving information about pages, posts, and videos from the metadata for analytics purposes.
Posts on private, inactive, and age-restricted Instagram accounts are not supported.
Accounts that have disabled Embeds are not supported.
Stories are not supported.
Shadow DOM is not supported.

App Review

In order to use oEmbed your app must undergo App Review for the oEmbed Read feature.

For the provide a URL where we can test Oembed Read form field, use the Instagram oEmbed endpoint to get the embed HTML for any public post on our official Facebook page or Instagram page (or get the embed HTML for either of the pages themselves). Add the returned embed HTML to your own page where you will be displaying oEmbed content and enter that page's URL in the form field.

Once you have been approved for the oEmbed Read feature you may embed your own pages, posts, or videos using their respective URLs.

Access Tokens

The Instagram oEmbed endpoint requires either an App Access Token (recommended) or Client Access Token.

App Access Tokens

If your app relies on a backend server, we recommend that you use an App Access Token when accessing the oEmbed endpoint. Rate limits are dependent on the type of token included in the request, and App Token Rate Limits allow for up to 5 million requests per day.

Instructions for generating App Access Tokens can be found in the App Tokens section of our Access Tokens documentation.

Please note that App Access Tokens should never be used client-side. They should always be kept secure and stored on your server. If your app must use a token client-side, use a Client Access Token instead.

Client Access Tokens

If your app must access the oEmbed endpoint from a user agent such as a mobile device or web browser, your app must use a Client Access Token and will be subject to Client Token Rate Limits.

To get a Client Access Token, sign into your App Dashboard and navigate to Settings > Advanced > Security > Client Token.

Unlike App Access Tokens, Client Access Tokens cannot be used in oEmbed endpoint requests on their own, they must be combined with your App ID. To do this, append your token to the end of your App ID, separated by a pipe symbol (|):

{app-id}|{client-token}

For example:

access_token=1234|5678

Rate Limits

Rate limits are dependent on the type of Access Token your app includes in each request.

App Token Rate Limits

Apps that rely on App Access Tokens can make up to 5 million requests per 24 hours.

Client Token Rate Limits

Client Token Rate Limits are significantly lower than App Token Rate Limits. We do not reveal the actual limit as it will change depending on your app activity. However, you can safely assume that your app will not reach its limit unless it exhibits bot-like behavior, such as batching thousands of requests, or sending thousands of requests per agent or app user.

Getting Embed HTML

To get an Intagram post's embed HTML, send a request to:

GET /instagram_oembed?url={url}&access_token={access-token}

Replace {url} with the URL of the Instagram post that you want to query and {access-token} with your App or Client Access Token (or pass it to us in an HTTP header). If you are using a Client Access Token, remember that you must combine it with your App ID using a pipe symbol otherwise the request will fail.

Upon success, the API will respond with a JSON object containing the post's embed HTML and additional data. The embed HTML will be assigned to the html property.

Refer to the Instagram oEmbed reference for a list of query string parameters you can include to augment the request. You may also include the fields query string parameter to specify which Fields you want returned. If omitted, all default Fields will be included in the response.

Sample Request

curl -X GET \
  "https://graph.facebook.com/v20.0/instagram_oembed?url=https://www.instagram.com/p/fA9uwTtkSN/&access_token=IGQVJ..."

Sample Response

Some values truncated with an ellipsis (...) for readability.

{
  "version": "1.0",
  "author_name": "diegoquinteiro",
  "provider_name": "Instagram",
  "provider_url": "https://www.instagram.com/",
  "type": "rich",
  "width": 658,
  "html": "<blockquote class=\"instagram-media\" data-instgrm-ca...",
  "thumbnail_width": 640,
  "thumbnail_height": 640
}

URL Formats

The url query string parameter accepts the following URL formats:

https://www.instagram.com/p/{media-shortcode}/
https://www.instagram.com/tv/{media-shortcode}/ https://www.instagram.com/{username}/guide/{slug}/{guide_id}

Embed JS

The embed HTML contains a reference to the Instagram embed.js JavaScript library. When the library loads, it scans the page for the post HTML and generates the fully rendered post. If you want to load the library separately, include the omitscript=true query string parameter in your request. To manually initialize the embed HTML, call the instgrm.Embeds.process() function after loading the library.

Post Size

The embedded post is responsive and will adapt to the size of its container. This means that the height will vary depending on the container width and the length of the caption. You can set the maximum width by including the maxwidth query string parameter in your request.

Getting Thumbnails

We recommend that you render all of the post’s embed HTML whenever possible. If you are unable to do this, you can get a post’s thumbnail image URL and render that instead. If you do this, however, you must provide clear attribution next to the image, including attribution to the original author and to Instagram, and a link to the Instagram post that you are querying.

To get a post’s thumbnail URL and attribution information, send a request to:

GET /instagram_oembed
  ?url={url}
  &maxwidth={maxwidth}
  &fields=thumbnail_url,author_name,provider_name,provider_url
  &access_token={access-token}

Replace {url} with the URL of the Instagram post you want to query, {maxwidth} with the maximum size of the thumbnail you want to render, and {access-token} with your App or Client Access Token.

Sample Request

curl -i -X GET \
  "https://graph.facebook.com/v20.0/instagram_oembed?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FfA9uwTtkSN&maxwidth=320&fields=thumbnail_url%2Cauthor_name%2Cprovider_name%2Cprovider_url&access_token=96481..."

Sample Response

Some values truncated with an ellipsis (...) for readability.

{
  "thumbnail_url": "https://scontent.cdninstagram.com/v/t51.288...",
  "author_name": "diegoquinteiro",
  "provider_name": "Instagram",
  "provider_url": "https://www.instagram.com/"
}

Passing Access Tokens in a Header

If you don’t want to include your Access Token in your request’s query string, you can pass it to us through an Authorization HTTP header instead.

Authorization: Bearer {access-token}

For example:

curl -i -X GET \
  "https://graph.facebook.com/v20.0/instagram_oembed?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FfA9uwTtkSN" \
  --header "Authorization: Bearer 96481..."