PostEverywhere Instagram API Guide

PostEverywhere API reference for Instagram: request fields, media rules and examples for feed posts, Reels, Stories, Trial Reels and carousels.

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.

Connect your Instagram account to PostEverywhere

Connect Instagram from the dashboard with OAuth, or headlessly from code: mint a connect link and hand it to the account owner - no dashboard session needed. Both flows are covered in Connecting Accounts.

What you can post to Instagram

Content Type	Media Required	Description
Post	Image(s)	Standard feed post. Default when an image is attached. Supports up to 10 images for carousels.
Reels	Video	Short-form video (3 seconds to 15 minutes). Default when a video is attached.
Story	Image or video	Disappears after 24 hours. Must be set explicitly via `contentType`.
Trial Reel	Video	Reel shared with a smaller audience first to test engagement.

Instagram-specific options in the API

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",
        "locationId": "123456789012345"
      }
    }
  }
}

Settings Reference

Setting	Type	Description
`content`	string	Override the default caption with an Instagram-specific version.
`contentType`	string	One of `"Post"`, `"Reels"`, `"Story"`, or `"Trial Reel"`. If omitted, images default to `"Post"` and videos default to `"Reels"`.
`settings.altText`	string	Alt text for a single image post and for each image in a carousel, up to 1,000 characters. Not used on Reels or Stories. In a carousel, an image's own alt text is used first. `alt_text` is also accepted.
`settings.locationId`	string	Instagram location ID (the Facebook Page ID of the place) to tag on a feed post, carousel or Reel. The ID on its own is enough.
`settings.location`	string	Optional name of the place, shown in PostEverywhere only.
`cover_photo` (top-level)	object	`{ "url": "...", "timestamp": 3.5 }`: the frame (in seconds) or custom image to use as the Reel cover. Give `url` (a public https JPG or PNG) or `media_id` (an image you uploaded with the media endpoints) in its place; one of them is required. A `settings.coverPhotoTimestamp` on its own is ignored.

Publish to Instagram: a working request

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"
      }
    }
  }'

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.

Instagram limits: characters, media and video

Requirement	Limit
Caption length	2,200 characters (longer is refused with `400 content_too_long`)
Hashtags per post	30 maximum
Alt text length	1,000 characters (single images and carousel images)
Image formats	JPEG, PNG, WebP, HEIC
Image max file size	20 MB
Video format	MP4 (H.264)
Video max file size	500 MB
Video duration (Reels)	3 seconds to 15 minutes
Video duration (Story)	Up to 60 seconds
Carousel images	2 - 10 images
Recommended image ratio	1:1 (square), 4:5 (portrait), 1.91:1 (landscape)
Recommended Reels ratio	9:16 (vertical)

Getting better results on Instagram

Keep hashtags in the caption. First comments are not available on Instagram through the API yet: a firstComment (or first_comment) sent for Instagram is removed from the post and the response notes say so. More than 30 hashtags returns 400 instagram_hashtag_limit_exceeded.
Add alt text to images. settings.altText goes on a single image and on each carousel image. Reels and Stories do not take alt text.
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.

Common questions about posting to Instagram

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, 3 seconds to 15 minutes for Reels) using the Upload Media endpoint.

What image sizes does Instagram support?

Instagram accepts square (1:1), landscape (1.91:1) and portrait (4:5) images, and the API enforces that aspect-ratio range (0.8 to 1.91). Images outside it are smart-cropped automatically when PostEverywhere hosts them; otherwise the request is rejected with 400 aspect_ratio_unsupported. Minimum size is 320x320 pixels.

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.

Can the API post a first comment on Instagram?

Not yet. A firstComment sent for Instagram is removed before the post is saved, and the response notes say so. Put hashtags in the caption (up to 30). First comments work on X.

What happens if Instagram refuses part of a post?

If the post still goes out, the problem shows as a warning on the post instead of being dropped silently. The warnings array in GET /v1/posts/:id/results carries the same message.

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.

Can I edit an Instagram post after it's published?

No. PATCH /v1/posts/:id rejects edits on published posts with 400 invalid_post_status: only scheduled and draft posts can be modified. Instagram's Graph API also doesn't expose endpoints for editing a published feed post's caption or media. To change a live post, edit the caption directly in the Instagram app, or delete and recreate.

Other platforms you can publish to

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

Building on the API?See plansAPI overviewConnect an AI agent