Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

If you have issues connecting Instagram, please see the troubleshooting guide.
If your media is hosted on a server or CDN you control, make sure Meta’s publishing crawler can fetch it. See Meta Media Crawler Blocked if you see Ayrshare error code 440 (“social network could not download media from this URL”) or error code 138 with “Restricted by robots.txt” in the details.
The Instagram API 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 5 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 Reel 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: "".
  • See Instagram Media Guidelines and Instagram Authorization for more information.

Posting to Instagram

JSON for a basic post with an image and hashtags to Instagram:
Instagram Post
{
  "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.
The aspect ratio of images & videos and the duration of video are very important to successfully post to Instagram. If they do not meet the requirements, the post will be rejected.Please see the Instagram section of Image and Video Guidelines.

Instagram Business or Creator Account

Your Instagram account must be a Business or Creator Account and connected with a Facebook Page. The set up is free and easy. See here for detailed instructions:

Instagram Linking

You can post multiple images or Reel videos to Instagram as a carousel; up to a combined total of 10 images or videos may be used in a carousel. Just add your additional images or videos to the mediaUrls array, and the carousel will automatically be created.
Instagram Carousel Post
{
  // Max 10 images or videos
  "mediaUrls": ["https://url.com/image.jpg", "https://url.com/video.mp4"]
}
Video URLs must end in a known extension such as mp4. The isVideo parameter is not supported for Instagram carousels.

Instagram Reels

In Instagram a video post is called a Reel. You can post a video to Instagram Reels API with the following optional instagramOptions options.
Instagram Reels Options
{
  "instagramOptions": {
    "shareReelsFeed": true,
    "audioName": "The Weeknd - Blinding Lights",
    "thumbNail": "https://img.ayrshare.com/012/gb.jpg", // if used, thumbNailOffset will be ignored.
    "thumbNailOffset": 30000
  }
}
  • Please see the Reels API video requirements for details on the video requirements.
  • shareReelsFeed: Boolean 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: String 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. For example, "The Weeknd - Blinding Lights".
  • thumbNail: String URL of the Reel cover image (thumbnail). Please see here for details on thumbNail.
  • thumbNailOffset: Integer offset in milliseconds of the thumbnail frame. 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.

Trial Reels

A trial reel is a Reel that is published only to non-followers when it is first posted, allowing you to test how a Reel performs with a fresh audience before it reaches your existing followers. Set trialParams.graduationStrategy in instagramOptions to publish a Reel as a trial.
Instagram Trial Reel
{
  "post": "Testing this with a fresh audience first",
  "mediaUrls": ["https://img.ayrshare.com/random/portrait1.mp4"],
  "platforms": ["instagram"],
  "instagramOptions": {
    "trialParams": {
      "graduationStrategy": "MANUAL"
    }
  }
}
graduationStrategy controls how a trial reel later “graduates” — i.e. becomes visible to your followers as well. It is required when trialParams is provided and must be one of:
  • “MANUAL” — the post stays a trial reel until you manually graduate it from inside the Instagram app.
  • “SS_PERFORMANCE” — Meta auto-graduates the Reel based on early performance against non-followers.
Graduation itself (promoting a published trial reel to followers) is not currently exposed by Meta’s API and must be performed manually in the Instagram app. Ayrshare will add a graduation endpoint once Meta exposes one.

Trial reel restrictions

The trial reel request is rejected at the Ayrshare edge — before any Meta call — when any of these conditions are not met:
  • Exactly one media URL ending in .mp4 or .mov (case-insensitive). Carousels are not supported.
  • instagramOptions.stories must not be true. Stories cannot be trial reels.
  • graduationStrategy must be present and exactly “MANUAL” or “SS_PERFORMANCE” (case-sensitive).
Failures return one of three Ayrshare error codes — see Instagram Trial Reel Errors (447, 448, 449) for the full payloads.

Instagram Stories

You can post a single image or video as an Instagram Story with the following instagramOptions. Instagram stories disappear after 24 hours.
Stories Post
{
  "post": "The description of the video",
  "mediaUrls": ["https://img.ayrshare.com/random/portrait1.mp4"],
  "instagramOptions": {
    "stories": true
  }
}
Please see the Stories API requirements.
  • Instagram Stories do not support post text - any text provided in the post field, including mentions, will be ignored.
  • Stories expire after 24 hours.
  • Instagram currently only supports Story publishing on Instagram Business Accounts and not Creator Accounts.
  • Instagram Stories do not support collaborators.
  • Publishing stickers (i.e., link, poll, location) is not supported by Instagram.

Reels Thumbnails

You may select a frame the Reel as the thumbnail image or your own cover image (thumbnail) from an external URL.
Instagram Thumbnail
{
  "instagramOptions": {
    // milliseconds
    "thumbNailOffset": 30000,
    // If both thumbNail and thumbNailOffset includes, thumbNail will be used.
    "thumbNail": "https://img.ayrshare.com/012/gb.jpg"
  }
}
The offset is the location in milliseconds of the thumbnail frame of the video Reel. Default value is 0, which is the first frame of the Reel. If you specify both a thumbnail URL and a thumbnail offset, the thumbnail offset will be ignored. The Reel thumbnail must follow the Reels thumbnail 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.

Alternative Text

Add Instagram alternative text, also known as alt text, to an image. Instagram alt text is an accessibility feature used for additional user info and screen readers.
  • Alt text supports up to 1,000 characters per image.
  • Instagram does not support alt text for Reels or Stories.
Use the altText in the instagramOptions object.
Instagram Alt Text
{
  "instagramOptions": {
    // Array of Alt Texts
    "altText": ["This is my best pic", "😃 here is the next one"]
  }
}
Each alt text must correspond to an image or video in the mediaUrls array. The alt text will be applied to each image in order.

User Tags & Locations

The Instagram user will be notified when you use their username in a post. Please be cautious to not spam users or post with their username repeatedly. If you do, Instagram could suspend or deactivate your account.
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.
Instagram 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.
Not supported on images or videos in carousels.

User Tags

Instagram tags allow you to tag other Instagram users in your post. 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.01.0. Single images. Do not include with Reels or an error will occur.
Instagram User Tags
{
  "instagramOptions": {
    "userTags": [
      {
        "username": "ayrshare", // Required: Instagram username
        "x": 0.5, // Required for Images, cannot be used with Reels
        "y": 1.0 // Required for Images, cannot be used with Reels
      },
      {
        "username": "johnboy", // Required: Instagram username
        "x": 0.1, // Required for Images, cannot be used with Reels
        "y": 0.9 // Required for Images, cannot be used with Reels
      }
    ]
  }
}

Instagram Mentions

Mention another Instagram handle by adding @handle in the post text. For example you can mention the @ayrshare handle in the post text:
Instagram Mentions
{
  "post": "The best social media API @Ayrshare ever!", // empty string is allowed
  "mediaUrls": ["https://images.com/image.jpg"],
  "platforms": ["instagram"]
}
The @mentioned user will be notified of the mention. Please review the important rules on mentions.

Collaboration

Instagram collaboration allows you to co-author content with other Instagram accounts 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

The public original author can tag another public account as an Instagram collaborator. The other account will receive a message, which allows them to 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. You may add collaborators to a Reel, image, or carousel. Tagging a private collaborator is not permitted via the Instagram API. While such a functionality exists within the Instagram app, platforms and their APIs are often not at feature parity.
Instagram Stories do not support collaborators.
  • Only invite collaborators you expect to accept your invite.
  • If the collaborator responds with a declined collaboration request, do not re-invite them until you contact them to understand the reason for the decline.
  • Repeated declines from the same or multiple users will put your Instagram and Ayrshare account at risk of cancelation.
  • The original author can add or remove a collaborator at any time.
Invite up to three collaborators by with an array public Instagram usernames.
Instagram Collaborators
{
  "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.
Note about invited collaborators: With a few exceptions, data on or about co-authored media can only be accessed through the API by the user who published the media; collaborators are unable to access this data via the API.

Get Collaborator Request Status

After inviting a Instagram collaborator, you can check the status of the request using the Get Collaborator Request Status API.

Auto Image Resize

Max Pack Required
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.
Instagram Auto Image Resize
{
  "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
      }
    ]
  }
}

Used Quota

The Instagram response will include the current usedQuota for the number of Instagram posts done over a rolling 24 hours period. Only 50 Instagram posts are permitted by Instagram in a 24-rolling-hour period.
Instagram Used Quota
{
    "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.

Content Issues

Ayrshare includes built-in media protection that can detect and resolve certain media delivery issues during posting. When a post succeeds but a content issue was detected and resolved, the response includes an optional contentIssues object. This allows you to identify and fix issues with your media hosting proactively. The contentIssues object is only present when an issue was detected and resolved — normal successful posts do not include it.
FieldTypeDescription
originMediaHostFailedbooleanThe social network could not retrieve the media from the provided URL. Ayrshare’s automated media protection resolved the issue and completed the post successfully. Consider reviewing your media hosting configuration — see Meta Media Crawler Blocked for common causes.
detailsarray of stringsHuman-readable descriptions of each detected issue.
Content Issues Response Example
{
    "status": "success",
    "errors": [],
    "postIds": [
        {
            "status": "success",
            "id": "17878176260289172",
            "postUrl": "https://www.instagram.com/p/CP1dI9Hp_WO/",
            "usedQuota": 12,
            "platform": "instagram",
            "contentIssues": {
                "originMediaHostFailed": true,
                "details": [
                    "Media URL could not be retrieved by the social network. Successfully posted using Ayrshare automated media protection."
                ]
            }
        }
    ],
    "id": "abc123",
    "refId": "65806e8d9efd78a58c05566a887043329dcdc76b",
    "post": "Your post text here"
}
If you see originMediaHostFailed in your responses, there may be an issue with your media hosting that prevents social networks from accessing your media. See Meta Media Crawler Blocked for detailed troubleshooting steps.

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.

Character Limits

Please see Instagram Character Limits for more information.

Additional endpoints

Get Collaborator Request Status