# PostEverywhere Instagram API Guide

> Post to Instagram via API: publish and schedule feed posts, Reels, Stories, Trial Reels, and carousels with one REST call.

**Source:** https://posteverywhere.ai/docs/platforms/instagram
**Section:** Platforms
**API reference:** https://posteverywhere.ai/docs/api/reference

---

Publish Instagram Feed Posts, Reels, Stories, and Trial Reels through a single API call. PostEverywhere handles [media uploads](/docs/api/init-media-upload), 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](/docs).

## Connect your Instagram account to PostEverywhere
Connect Instagram from the dashboard with OAuth, or headlessly from code: mint a [connect link](/docs/api/create-connect-link) and hand it to the account owner - no dashboard session needed. Both flows are covered in [Connecting Accounts](/docs/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 (up to 90 seconds). 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:

```json
{
  "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

| 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 | Accessibility description for the image. Max 100 characters. |
| `settings.firstComment` | string | Text posted as the first comment after publishing. Useful for hashtag stacking. |
| `cover_photo` (top-level) | object | `{ "url": "...", "timestamp": 3.5 }`: the frame (in seconds) or custom image to use as the Reel cover. `url` is required; a `settings.coverPhotoTimestamp` on its own is ignored. |

## Publish to Instagram: a working request
### Schedule an Instagram Reel

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

### Schedule an Instagram Story

```bash
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.

```bash
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 |
| Hashtags per post | 30 maximum |
| Alt text length | 100 characters |
| 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 - 90 seconds |
| 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
- **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.

## 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](/docs/api/create-post). Attach a video file (MP4, up to 90 seconds for Reels) using the [Upload Media endpoint](/docs/api/init-media-upload).

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

### 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](#schedule-an-instagram-trial-reel) 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](/docs/platforms/tiktok)** -- short-form vertical video, similar to Reels
- **[Facebook](/docs/platforms/facebook)** -- cross-post Reels and image content to Facebook Pages
- **[Threads](/docs/platforms/threads)** -- text-first companion platform by Meta

## Related Instagram and API reference pages
- [API Reference -- Create Post](/docs/api/create-post)
- [Upload Media](/docs/api/init-media-upload)
- [Quick Start Guide](/docs/quick-start)
- [Instagram Scheduler on PostEverywhere](https://posteverywhere.ai/instagram-scheduler)

**Related:** [Instagram media requirements](/docs/media-requirements) · [Instagram token health](/docs/account-health) · [scheduling Instagram posts with an API](/blog/schedule-instagram-posts-api) · [what the PostEverywhere API covers](/social-media-api) · [generate captions with AI](/docs/generate-caption)