The Content Publishing API is in closed beta with Facebook Marketing Partners and Instagram Partners only. We are not accepting new applicants at this time.

Content Publishing

The Content Publishing API is a subset of Instagram Graph API endpoints that allow you to publish IG Media objects on Instagram Business IG Users.

Publishing media objects with this API is a two step process — you first create a media object container, then publish the container.

Limitations

  • Can only be used by Instagram Business IG Users
  • Cannot be used to publish content on Instagram Creator IG Users.
  • JPEG is the only image format supported

Endpoints

The API consists of the following endpoints:

Refer to each endpoint's reference documentation for parameter and permission requirements.

Examples

Publishing Photos

Publishing photos is a two-step process:

  1. Use the POST /{ig-user-id}/media endpoint to create a media object container, then
  2. Use the POST /{ig-user-id}/media_publish#creating endpoint to publish that container

For example, let's say you have a photo at...

https://www.example.com/images/bronz-fonz.jpg

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

Sample Request

POST graph.facebook.com/17841400008460056/media
  ?image_url=https//www.example.com/images/bronz-fonz.jpg
  &caption=#BronzFonz

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

POST graph.facebook.com/17841405822304914/media_publish
  ?creation_id=17889455560051444

Publishing Photos w/ Tagged Users

You can tag public Instagram users in a photo and they will receive a notification when you publish the media container.

To do this, follow the Publishing Photos 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.

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

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

This would return a container ID which you would then publish using the POST /{ig-user-id}/media_publish edge.

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

Publishing Photos w/ Locations

You can use our Places Search API to get the ID of the Page associated with any Place that has been entered into our Places Graph. If you include the Page's ID when publishing a photo, the photo will be tagged with the Place's location.

To do this, first query the Places Graph API and include the page field to get the ID of the Page associated with the Place. For example, let's say you took a photo just outside New York City's Guggenheim Museum. You could get the Guggenheim's Page ID like this:

GET https://graph.facebook.com/search?
  type=place
  &fields=page
  &q=guggenheim

This would return an array of objects with "guggenheim" in their name, one of which is for the Guggenheim in New Your City:

... 
{
 "page": {
  "name": "Solomon R. Guggenheim Museum",
  "id": "7640348500"  // This is the page ID, which you can use for location tagging
 },
 "id": "10150113890778501"
},
...

Once you have the ID of the Page associated with the Place, follow the Publishing Photos steps above and use the location_id parameter to pass us the page ID when creating your media object container.

Note that there are different ways to query the Places Graph. We won't cover that here, so please refer to the Places Search API developer documents to learn the various ways to use it.

Sample Request

POST graph.facebook.com/17841400008460056/media
  ?image_url=https://www.example.com/images/gugges.jpg
  &caption=Exhibiting!
  &location_id=7640348500

This would return a container ID which you would then publish using the POST /{ig-user-id}/media_publish endpoint.

Publishing Videos

Publishing videos is a two-step process:

  1. Use the POST /{ig-user-id}/media endpoint to create a media object container, then
  2. Use the POST /{ig-user-id}/media_publish endpoint to publish that container

For example, let's say you have a video at...

https://www.example.com/videos/hungry-fonzes.mov

... that you want to publish with the hashtag "#Heyyyyyyyy!" as its caption. You could use the POST /{ig-user-id}/media edge to create the container like this:

Sample Request

POST graph.facebook.com/17841400008460056/media
  ?media_type=VIDEO
  &video_url=https//www.example.com/videos/hungry-fonzes.mov
  &caption=#Heyyyyyyyy!

This would return a container ID (let's say 17889455560051447), which you would then publish using the POST /{ig-user-id}/media_publish edge, like this:

Sample Request

POST graph.facebook.com/17841405822304914/media_publish
  ?creation_id=17889455560051447

Limitations

We will cURL your media object using the passed in URL, so the object must be on a public server.

We do not support:

  • Extended JPEG formats such as MPO and JPS
  • Stories
  • Shopping tags
  • Branded content tags
  • Filters
  • Multi-image posts

For additional limitations, please refer to the /{ig-user-id}/media endpoint reference.

Troubleshooting

If you are able to create a container for a video but the POST /{ig-user-id}/media_publish endpoint does not return the published media ID, you can get the container's publishing status by querying the GET /{container-id}?fields=status endpoint. This endpoint will return one of the following:

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

Error Codes

CodeSubcodeStringDescriptionSolution

400

2207006

INSTAGRAM_PLATFORM_ API__MEDIA_NOT_FOUND

Possible permission error due to missing permission or expired token.

Generate a new container and use it to try again.

400

2207031

INSTAGRAM_PLATFORM_ API__TEMPORARY_ERROR

Temporary error publishing a container.

Try again 1-2 times in the next 30 seconds to 2 minutes. If unsuccessful, generate a new container ID and use it to try again.