FB-Dev-Open Source
Last updated
Was this helpful?
Web-Dev-Hub-Docs
Last updated
Was this helpful?
You can use the Instagram Graph API to publish objects on Instagram Business . Publishing media objects is a two step process — first create a media object container, then use the container to publish the media.
Can only be used to publish to business accounts; Creator IG User accounts are not supported.
Accounts are limited to 25 API-published posts within a 24 hour period.
JPEG is the only image format supported. Extended JPEG formats such as MPO and JPS are not supported.
Stories are not supported.
Shopping tags are not supported.
Branded content tags are not supported.
Filters are not supported.
Multi-image posts are not supported.
If the caption contains a hashtag, it should be HTML URL-encoded as %23 in the request.
Publishing to IGTV is not supported.
For additional limitations, please refer to the endpoint reference.
We will cURL your media object using the passed in URL so the object must be on a public server.
The API consists of the following endpoints. Refer to each endpoint's reference document for usage requirements.
Publishing photos is a two-step process:
For example, let's say you have a photo at...
... that you want to publish with the hashtag "#BronzFonz" as its caption. You could use the POST /{ig-user-id}/media endpoint to create the container like this, using HTML URL-encoding for the hashtag (#) character in the caption.
Sample Request
This would return a container ID (let's say 17889455560051444), which you would then publish using the POST /{ig-user-id}/media_publish endpoint, like this:
Sample Request
You can tag public Instagram users in a photo and they will receive a notification when it is published.
For example, let's say you want to publish a photo that depicts two of your Instagram friends who you want to tag. You could use the POST /{ig-user-id}/media endpoint to create the container like this:
Sample Request
This would return a container ID which you would then use with the POST /{ig-user-id}/media_publish endpoint to publish the photo.
Notes
The user_tags value must be an array of objects formatted with JSON.
You can only tag users with public Instagram accounts.
The object must contain all three properties (username, x, and y) for each user.
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.
The hashtag character (#) is HTML URL-encoded in the request (%23).
For example:
This would return an array of Pages with "guggenheim" in their name, one of which is for the Guggenheim in New York City:
Be sure to include the location field in your query and verify that the Page you want to use has location data that include latitude and longitude. Attempting to create a container using a Page that has no location data will fail with coded exception INSTAGRAM_PLATFORM_API__INVALID_LOCATION_ID.
To be eligible for tagging, a Page must have latitude and longitude location data.
Sample Request
This would return a container ID which you would then use with the POST /{ig-user-id}/media_publish endpoint to publish the photo.
Publishing videos is a two-step process:
For example, let's say you have a video at...
... that you want to publish with the hashtag "#Heyyyyyyyy!" as its caption. You could use the POST /{ig-user-id}/media edge, applying HTML URL-encoding to the hashtag character in the caption to create the container like this:
Sample Request
This would return a container ID (let's say 17889455560051447), which you would then use with the POST /{ig-user-id}/media_publish endpoint to publish the video, like this:
Sample Request
Sample Request
Sample Response
EXPIRED — The container was not published within 24 hours and has expired.
ERROR — The container failed to complete the publishing process.
FINISHED — The container and its media object are ready to be published.
IN_PROGRESS — The container is still in the publishing process.
PUBLISHED — The container's media object has been published.
We recommend querying a container's status once per minute, for no more than 5 minutes.
All requests must include the app user's access token.
Publishing relies on a combination of the following permissions. The exact combination depends on which your app will be using. Refer to our references to determine which permissions they require.
If your app will be used by app users who do not have a on your app or a role in a that claimed your app, you must request approval for each permission via before non-role app users can grant them to your app.
Instagram Business accounts connected to a that requires (PPA) cannot be published to until PPA has been completed.
It's possible that an app user may be able to perform on a Page that initially does not require PPA but later requires it. In this scenario, the app user would not be able to publish content to their Instagram Business account until completing PPA. Since there's no way for you to determine if an app user's Page requires PPA, we recommend that you advise app users to preemptively complete PPA.
Instagram accounts are limited to 25 API-published posts within a 24 hour moving period. This limit is enforced on the endpoint when attempting to publish a media container. We recommend that your app also enforce the publishing rate limit, especially if your app allows app users to schedule posts to be published in the future.
To check an IG Business acccount's current rate limit usage, query the endpoint.
— upload media and create media containers.
— publish uploaded media using their media containers.
— check media container publishing eligibility and status.
— check app user's current publishing rate limit usage.
Use the endpoint to upload a photo and create an .
Use the endpoint to publish the photo using its container.
To do this, follow the steps above, but when creating the media container, include the user_tags parameter and an array of objects indicating the Instagram users in the photo as well as their x/y coordinates within the photo itself.
You can use the to search for whose names match a search string, then parse the results to identify any Pages that have been created for a physical location. If you include a Page's ID when publishing a photo, the photo will be tagged with the location associated with that Page.
Once you have the Page ID, follow the steps above and use the location_id parameter to pass us the Page ID when creating your media object container.
Use the endpoint to create an .
Use the endpoint to publish the video using its container.
Instagram accounts are limited to 25 API-published posts within a 24 hour moving period. You can query the endpoint to check your app user's current rate limit usage.
If you are able to create a container for a video but the endpoint does not return the published media ID, you can get the container's publishing status by querying the GET /{ig-container-id}?fields=status_code endpoint. This endpoint will return one of the following:
See the reference.