Skip to main content

Instagram API Guide

Publish Instagram Feed Posts, Reels, Stories, and Trial Reels through a single API call. PostEverywhere handles media uploads, aspect ratio validation, and Instagram's content publishing API so you can focus on your content. For a general overview of all supported platforms, see the Introduction.

Supported Content Types​

Content TypeMedia RequiredDescription
PostImage(s)Standard feed post. Default when an image is attached. Supports up to 10 images for carousels.
ReelsVideoShort-form video (up to 90 seconds). Default when a video is attached.
StoryImage or videoDisappears after 24 hours. Must be set explicitly via contentType.
Trial ReelVideoReel shared with a smaller audience first to test engagement.

Platform-Specific Settings​

Use the platform_content.instagram object to customise your Instagram post:

{
  "platform_content": {
    "instagram": {
      "content": "Instagram-specific caption with #hashtags",
      "contentType": "Story",
      "settings": {
        "altText": "Image description for accessibility",
        "firstComment": "First comment posted automatically after publishing"
      }
    }
  }
}

Settings Reference​

SettingTypeDescription
contentstringOverride the default caption with an Instagram-specific version.
contentTypestringOne of "Post", "Reels", "Story", or "Trial Reel". If omitted, images default to "Post" and videos default to "Reels".
settings.altTextstringAccessibility description for the image. Max 100 characters.
settings.firstCommentstringText posted as the first comment after publishing. Useful for hashtag stacking.
settings.coverPhotoTimestampnumberTimestamp in seconds to use as the video cover photo.

Example: Create a Post​

Schedule an Instagram Reel​

curl -X POST https://app.posteverywhere.ai/api/v1/posts \
  -H "Authorization: Bearer $POSTEVERYWHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Check out our latest product walkthrough!",
    "account_ids": [2280],
    "media_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
    "scheduled_for": "2026-04-15T14:00:00Z",
    "timezone": "America/New_York",
    "platform_content": {
      "instagram": {
        "content": "New product walkthrough is live! Watch to the end for a surprise 🎁\n\n#productlaunch #tutorial #newfeature",
        "contentType": "Reels",
        "settings": {
          "firstComment": "#socialmedia #marketing #contentcreator #smallbusiness #growthhacking",
          "coverPhotoTimestamp": 3.5
        }
      }
    }
  }'

Schedule an Instagram Story​

curl -X POST https://app.posteverywhere.ai/api/v1/posts \
  -H "Authorization: Bearer $POSTEVERYWHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Behind the scenes today!",
    "account_ids": [2280],
    "media_ids": ["b2c3d4e5-f6a7-8901-bcde-f12345678901"],
    "platform_content": {
      "instagram": {
        "contentType": "Story"
      }
    }
  }'

Schedule an Instagram Trial Reel​

Trial Reels let you test a Reel with non-followers first. Instagram only shows it to your existing followers if it performs well — useful for A/B testing or de-risking new content directions.

curl -X POST https://app.posteverywhere.ai/api/v1/posts \
  -H "Authorization: Bearer $POSTEVERYWHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Testing a new content angle 🎬",
    "account_ids": [2280],
    "media_ids": ["c3d4e5f6-a7b8-9012-cdef-123456789012"],
    "platform_content": {
      "instagram": {
        "contentType": "Trial Reel"
      }
    }
  }'

Under the hood, PostEverywhere passes Instagram's documented trial_params (graduation_strategy: SS_PERFORMANCE) to the Graph API. The Reel is shown only to non-followers initially and graduates to your follower feed automatically if engagement metrics clear Instagram's thresholds.

Requirements & Limits​

RequirementLimit
Caption length2,200 characters
Hashtags per post30 maximum
Alt text length100 characters
Image formatsJPEG, PNG, WebP, HEIC
Image max file size20 MB
Video formatMP4 (H.264)
Video max file size500 MB
Video duration (Reels)3 - 90 seconds
Video duration (Story)Up to 60 seconds
Carousel images2 - 10 images
Recommended image ratio1:1 (square), 4:5 (portrait), 1.91:1 (landscape)
Recommended Reels ratio9:16 (vertical)

Tips​

  • Use firstComment for hashtags. Moving hashtags to the first comment keeps your caption clean while maintaining discoverability. The comment is posted automatically within seconds of publishing.
  • Set contentType explicitly for Stories. Without it, images default to Feed Post and videos default to Reels. Stories must be requested via "contentType": "Story".
  • Test with Trial Reels first. Use "contentType": "Trial Reel" to share a Reel with a smaller audience before committing to a full publish. This is useful for A/B testing content.

Frequently Asked Questions​

Can I schedule Instagram Reels via the API?​

Yes. Set contentType to "Reels" in the platform_content.instagram object when creating a post. Attach a video file (MP4, up to 90 seconds for Reels) using the Upload Media endpoint.

What image sizes does Instagram support?​

Instagram supports images from 320x320 to 1440x1800 pixels. Square (1:1), landscape (1.91:1), and portrait (4:5) aspect ratios are accepted. Images are automatically resized if they fall outside these dimensions.

Can I post Instagram carousels via the API?​

Yes. Attach multiple images (2 to 10) to your post using the media_ids array. Set contentType to "Post" or omit it -- images default to a feed post, and Instagram automatically creates a carousel when multiple images are attached.

How do I add hashtags without cluttering my caption?​

Use the firstComment setting. PostEverywhere automatically posts your hashtags as the first comment within seconds of publishing, keeping your caption clean while maintaining full discoverability.

How do I publish a Trial Reel via the API?​

Set contentType to "Trial Reel" inside platform_content.instagram. See the Trial Reel example above for the full request shape. Trial Reels require a video (3-90 seconds, MP4) and a Reel-eligible Instagram account.

Do you support share_mode or TRIAL_REELS_DONT_SHARE_TO_FOLLOWERS?​

We support the functionality these names describe (a Reel shown to non-followers first), but not under those names — they aren't part of Instagram's documented Graph API. The Meta-supported way to publish a Trial Reel is via trial_params with graduation_strategy: SS_PERFORMANCE, which is exactly what PostEverywhere sends when you set contentType: "Trial Reel". The TRIAL_REELS_DONT_SHARE_TO_FOLLOWERS identifier you may have seen elsewhere is an internal Meta constant, not a public API parameter.

  • TikTok -- short-form vertical video, similar to Reels
  • Facebook -- cross-post Reels and image content to Facebook Pages
  • Threads -- text-first companion platform by Meta

Further Reading​