Instagram API

Instagram has the following requirements and restrictions:

• Business or Creator Instagram Account connected with a Facebook Page - see here.

• Only 50 Instagram posts are allowed over a 24 hour period. See below for usedQuota

• The post text may contain up to 30 hashtags (e.g. #wildtimes) and 3 username mentions (e.g. @natgeo).

• @mention Instagram users will receive a notification.
• Maximum 2,200 post characters.

• Multi-image/videos posts are supported and sent as a carousel. You may send up to 10 videos and images.

• Instagram does not support deletes via an API. Deletes must occur manually using the Instagram app.

• If your video doesn’t end in a known video extension such as mp4, please use the isVideo parameter. See the /post endpoint for details.

• Instagram also supports sending media without post text. If you do not want post text included send an empty String post: ""

JSON for a basic post with an image and hashtags to Instagram:

{
  "post": "The best IG ever #best #awesome https://www.instagram.com",
  "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"],
  "platforms": ["instagram"]
}

Hashtags are clickable in Instagram posts, but links are not.

​

Instagram Business or Creator Account

Your Instagram account must be a Business or Creator Account and connected with a Facebook Page. The setup is free and easy.

See here for detailed instructions:

​

Carousel of Images and Videos

You can post multiple images or videos to Instagram as a carousel; up to a combined total of 10 images or videos may be use in a carousel. Just add your additional images or videos to the mediaUrls array and the carousel will automatically be created.

"mediaUrls": ["https://url.com/image.jpg", "https://url.com/video.mp4" ...];  // Max 10 images or videos

​

Instagram Reels

You can post a video to Instagram Reels API with the following instagramOptions.

• reels: set to true to post the video to Reels.

• shareReelsFeed: set to true to indicate that the Reel can appear in both the Feed and Reels tabs or false to indicate the Reel can only appear in the Reels tab. This value is a hint to Instagram where you would like the Reel to appear, but neither value determines whether the Reel actually appears in the Reels or Feed tab because the Reel may not meet eligibility requirements or may not be selected by Instagram’s algorithm.

• audioName: Name of the audio music of your Reels media. You can only rename once, either while creating a reel or after from the audio page.

• coverUrl: Please see here for details on coverUrl.

• thumbNailOffset: Please see here for details on thumbNailOffset.

Please see the Reels API video requirements or an example of using the Instagram Reels API.

You may also set a Reels cover url and location & user tags.

​

Instagram Stories

You can post a single image or video as an Instagram Story with the following instagramOptions. Instagram stories disappear after 24 hours.

{
  "post": "The description of the video",
  "mediaUrls": ["https://img.ayrshare.com/random/portrait1.mp4"],
  "instagramOptions": {
    "stories": true
  }
}

Please see the Stories API requirements.

​

Video Thumbnail and Reels Cover URL

You may select a frame in the video or Reel as the thumbnail image. Also, Reels support a cover image from an external URL. Instagram does not support external cover images for regular videos.

{
    ...
    "instagramOptions": {
        "thumbNailOffset": 30000,    // milliseconds
        "coverUrl": "https://img.ayrshare.com/012/gb.jpg" // Reels only. If both coverUrl and thumbNailOffset includes, coverUrl will be used.
    }
}

The offset is the location in milliseconds of the thumbnail frame. Default value is 0, which is the first frame of the video or Reel.

If you specify both a cover image URL and a thumbnail offset, the thumbnail offset will be ignored.

The Reel cover url must follow the Reels cover url requirements. Signed URLs with redirects are not guaranteed to be compatible with cover URLs. We recommend a non-signed URL or use the /media endpoint.

​

User Tags & Locations

An image or a Reel can be tagged with Instagram users and an image, video, or a Reel can be tagged with a location using the instagramOptions parameter.

​

Location

A location is specified by a locationId, which is a Facebook Page ID or Facebook Page name. For example, Facebook page Id of the Guggenheim Museum is 7640348500 or Facebook page name "@guggenheimmuseum". Pages must be associated with a physical location.

// Using the Facebook Page Id - must be associated with a location
{
    ...
    "instagramOptions": {
        "locationId": 7640348500 // Guggenheim Museum Page Id
    }
}

// Using the Facebook Page name - must be associated with a location
{
    ...
    "instagramOptions": {
        "locationId": "@guggenheimmuseum" // Guggenheim Museum Page name. Must begin with @
    }
}

You can look up the locationId (Page Id) with the brand endpoint. Please note that the Page must have a location listed or the locationId will return an error.

​

User Tags

Users are specified by a userTags containing an Array of objects with an Instagram username and x/y coordinates (image only). User tags can be added for single images or Reels, but not regular videos, multiple images, or Stories.

• Usernames must be public Instagram accounts. Do not include the @ of the user handle.

• 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. Single images. Do not include with Reels or an error will occur.

{
    ...
    "instagramOptions": {
        "userTags": [
        {
            "username": "ayrshare",    // Required: Instagram username
            "x": 0.5,                  // Required for Images, can not be used with Reels
            "y": 1.0                   // Required for Images, can not be used with Reels
        },
        {
            "username": "johnboy",     // Required: Instagram username
            "x": 0.1,                  // Required for Images, can not be used with Reels
            "y": 0.9                   // Required for Images, can not be used with Reels
        }
     ]
    }
}

​

Instagram Mentions

Mention another Instagram handle by adding @handle in the post text. For example:

{
  "post": "The best social media API @Ayrshare ever!",
  "mediaUrls": ["https://images.com"],
  "platforms": ["instagram"]
}

​

Collaboration

Instagram offers a feature that enables users to co-author posts by tagging others as collaborators. This allows you to designate other Instagram users as creators on your post. When tagged, these users receive an invitation to collaborate in the mobile app. If they accept, the post will also appear in their feed and be visible to their followers, extending the post’s reach and engagement potential.

​

Collaborators

Instagram collaboration allows your to co-author content with other accounts. The public original author can tag another private or public account as a collaborator. The other account will receive a message to can either accept or deny the request. If the other account accepts, the post will also show on their profile and be distributed to their followers in Instagram feed. The post’s header will attribute the content to both accounts.

Invite up to three collaborators by with an array public Instagram usernames.

{
  "instagramOptions": {
    "collaborators": ["ayrshare", "therock", "taylorswift"] // Up to three
  }
}

These three collaborators will receive a message invitation in their Instagram mobile app and can accept or decline the invite, and then you may check the invited user request status. Please only invite collaborator who you know will accept your request or you Instagram account may be negatively affected.

​

Get Collaborator Request Status

​

Auto Image Resize

Images are automatically resized to 1080 x 1080 px to work with Instagram with the autoResize parameter. Please note, this will resize the image for all included platforms, so we recommend making one call for Instagram and a different /post call for additional platforms.

{
  "post": "Let it go!",
  "platforms": ["instagram"],
  "mediaUrls": ["https://images.ayrshare.com/imgs/GhostBusters.jpg"],
  "instagramOptions": {
    "autoResize": true, // Max Pack
    "locationId": 7640348500,
    "userTags": [
      {
        "username": "ayrshare",
        "x": 0.5,
        "y": 0.5
      },
      {
        "username": "ayrshare",
        "x": 0.3,
        "y": 0.2
      }
    ]
  }
}

​

Instagram Mentions

Mention other Instagram handles by simply including the handle beginning with the @ symbol in the post text. For example:

{
  "post": "Love the @ayrshare social media api"
}

Please see here for more information on mentions.

​

Used Quota

The Instagram response will include the current usedQuota for the number of Instagram posts done over a rolling 24-hours period. Only 25 Instagram posts are permitted by Instagram in a 24-rolling-hour period.

{
    "status": "success",
    "errors": [],
    "postIds": [
        {
            "status": "success",
            "id": "17823977408036085",
            "postUrl": "https://www.instagram.com/p/CeBrkQuN1Kv/",
            "usedQuota": 15,
            "platform": "instagram"
        }
    ],
    "id": "l4FaPHSXWJNdmMfm3dIE"
    "refId": "65806e8d9efd78a58c05566a887043329dcdc76b",
    "post": "Luckily for Alice, the little magic bottle had now had its full effect."
}

If the quota has been reached, an error message will be returned.

​

Adding line breaks or rich text to an Instagram post

Instagram line breaks can be added to a post with a special new line character.

Rich text, such as bold or italic lettering, can be added to a Instagram post with a few html elements.

​

Additional endpoints