Docs/API Reference/Instagram

Instagram API

Use the Crosspostify API to publish photos, Reels, carousels and Stories to Instagram — with scheduling support and multi-account publishing in a single API call.

Post Types

Reel · Photo · Carousel · Story

Max Carousel Images

10 images

Account Requirement

Business or Creator

Instagram is one of the world's largest visual platforms. The Crosspostify Instagram API integration lets you automate publishing of photos, videos (Reels), and carousels — scheduled or immediate — across multiple Instagram accounts from a single REST API call.

This page covers everything specific to Instagram when using the Crosspostify API. For general authentication, rate limits, and error handling, see the full API Reference.

Instagram-Specific Parameters

When targeting an Instagram account in your posts[] array, the following parameters apply. Parameters not listed as applicable are silently ignored for Instagram.

accountId✓ AppliesRequired. The id of the connected Instagram account from GET /social-accounts (Crosspostify's account ID, not the Instagram user ID).

caption✓ AppliesOptional. Supports hashtags, emojis and @mentions. Not shown on Stories.

title✗ IgnoredNot used for Instagram — ignored.

is_aigc✓ AppliesOptional. Adds Instagram's AI label to images, carousels and Reels. Not applied to Stories.

instagram✓ AppliesOptional object: Story, trial reel and show-in-feed options. See Instagram Settings below.

boardId✗ IgnoredPinterest only — ignored for Instagram.

link✗ IgnoredPinterest and Tumblr only — ignored for Instagram.

thumbnailTimestamp✗ IgnoredTikTok only — ignored for Instagram.

facebookFirstComment✗ IgnoredFacebook only — ignored for Instagram.

textFormatPresetId✗ IgnoredFacebook only — ignored for Instagram.

tiktok / facebook / youtube✗ IgnoredTikTok / Facebook / YouTube only — ignored for Instagram.

Instagram Settings

Add an optional instagram object to a post to publish it as a Story or to control how a Reel is shared. Every field is optional; without the object, images become feed posts and videos become Reels.

On/off options (as_story, share_to_feed and the top-level is_aigc) accept true/false, the strings "true"/"false" (any case) and 1/0. Any other value is rejected with HTTP 400, for example "Invalid instagram.as_story".

instagram.as_storybooleanoptional

Publish as a Story (visible for 24 hours) instead of a feed post or Reel. Works with /post/image (one image) and /post/video (one video; Instagram's limit is 3–60 seconds). Stories show no caption and get no AI label. Story images are scaled to fit 1080×1920 and keep their aspect ratio (no padding). Default: false.

instagram.trial_reelstringoptional

Reels only: publish as a trial reel, which Instagram shows to non-followers first. MANUAL = you decide later in Instagram whether to share it with your followers; SS_PERFORMANCE = Instagram shares it with your followers if it performs well. Available to professional accounts that Instagram has enabled for trial reels.

instagram.share_to_feedbooleanoptional

Reels only: true shows the Reel in the feed and on the profile grid as well as in the Reels tab; false shows it in the Reels tab only. If omitted, Instagram's default applies (currently: shown in the feed).

Validation (HTTP 400)

trial_reel other than MANUAL or SS_PERFORMANCE: "Invalid instagram.trial_reel"
instagram that is not an object: "Invalid instagram settings"
as_story: true on /post/images with more than one image: "A Story takes exactly one image or one video"
An on/off option that is not true/false, "true"/"false" or 1/0: "Invalid instagram.as_story", "Invalid instagram.share_to_feed" or "Invalid is_aigc"

Example: post an image as a Story

curl -X POST "https://v1.api.crosspostify.com/post/image" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaId": "img_12345",
    "posts": [
      {
        "accountId": "acc_instagram_789",
        "caption": "",
        "instagram": {
          "as_story": true
        }
      }
    ]
  }'

Supported Endpoints

Instagram supports the following Crosspostify API endpoints:

Text-only posts not supported

Instagram does not support text-only posts via the Crosspostify API. All posts require a media file (image or video). To post a Story, use /post/image or /post/video with instagram.as_story: true.

POST/post/video

Publish a video to Instagram as a Reel. Crosspostify always publishes videos as Reels; whether a Reel also appears in the feed is set with instagram.share_to_feed.

Instagram Reel Notes

Videos are published as Reels — Instagram's primary short-form video format
Upload your video first via POST /media and use the returned mediaId
caption supports hashtags, emojis, and @mentions
Recommended aspect ratio: 9:16 (vertical) for Reels; Instagram accepts Reels of 3 seconds to 15 minutes (the 100 MB upload limit usually comes first)
Trial reels, show-in-feed and Stories are set in the instagram object (see Instagram Settings)
scheduledDate takes any ISO 8601 date-time: Z or an offset such as +01:00 (converted to UTC). Without an offset it is read as UTC.
Omit scheduledDate to post immediately (queued)

Request Body

mediaIdstringrequired

The ID of the uploaded video file. Obtain this from POST /media.

scheduledDatestringoptional

Optional. A future ISO 8601 date-time, e.g. 2030-01-15T10:00:00Z. Offsets such as +01:00 are converted to UTC; a value without offset is read as UTC. Omit it (or send null) to post immediately.

postsarrayrequired

Array of post objects. Include one object per Instagram account you want to post to.

posts[].accountIdstringrequired

The id of the connected Instagram account from GET /social-accounts (Crosspostify's account ID, not the Instagram user ID).

posts[].captionstringoptional

Optional (default empty). The Reel caption. Supports hashtags, emojis, and @mentions. Max 2,200 characters: longer text is cut; hashtags after the 30th are removed.

posts[].is_aigcbooleanoptional

Set to true to add Instagram's AI label to the Reel. Default: false.

posts[].instagramobjectoptional

Instagram settings: as_story, trial_reel, share_to_feed. See Instagram Settings.

Response (202 Accepted)

{ "mediaId": "vid_12345", "message": "Video post created successfully", "posts": [ { "id": "7f3c9a2e-1b4d-4c8e-9f60-2a5b7d1e3c48", "platform": "instagram", "socialAccountId": "acc_instagram_789", "status": "SCHEDULED" } ] }

status is SCHEDULED when scheduledDate is set, otherwise QUEUED. Publishing happens afterwards: check the result with GET /posts?id=<id>.

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/video" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaId": "vid_12345",
    "scheduledDate": "2030-01-15T10:00:00Z",
    "posts": [
      {
        "accountId": "acc_instagram_789",
        "caption": "New Reel just dropped 🎬✨ #reels #instagram #fyp",
        "is_aigc": false,
        "instagram": {
          "share_to_feed": true
        }
      }
    ]
  }'

POST/post/image

Publish a single photo to Instagram as a standard feed post.

Instagram Photo Notes

Supported aspect ratios: 1:1 (square), 4:5 (portrait), 1.91:1 (landscape)
Crosspostify scales each image to fit 1080×1920. Images narrower than 4:5 or wider than 1.91:1 are padded with white bars before posting, never cropped. Crop them yourself to avoid bars.
Story images (instagram.as_story: true) are scaled to fit 1080×1920 and keep their aspect ratio (no padding)
caption supports hashtags, emojis, and @mentions
scheduledDate takes any ISO 8601 date-time: Z or an offset such as +01:00 (converted to UTC). Without an offset it is read as UTC.

Request Body

mediaIdstringrequired

The ID of the uploaded image file. Obtain this from POST /media.

scheduledDatestringoptional

Optional. A future ISO 8601 date-time, e.g. 2030-01-15T10:00:00Z. Offsets such as +01:00 are converted to UTC; a value without offset is read as UTC. Omit it (or send null) to post immediately.

postsarrayrequired

Array of post objects. Include one object per Instagram account.

posts[].accountIdstringrequired

The id of the connected Instagram account from GET /social-accounts (Crosspostify's account ID, not the Instagram user ID).

posts[].captionstringoptional

Optional (default empty). The photo caption. Supports hashtags, emojis, and @mentions. Max 2,200 characters: longer text is cut; hashtags after the 30th are removed.

posts[].is_aigcbooleanoptional

Set to true to add Instagram's AI label to the photo. Default: false.

posts[].instagramobjectoptional

Instagram settings: as_story (post the image as a Story). See Instagram Settings.

Response (202 Accepted)

{ "mediaId": "img_12345", "message": "Image post created successfully", "posts": [ { "id": "7f3c9a2e-1b4d-4c8e-9f60-2a5b7d1e3c48", "platform": "instagram", "socialAccountId": "acc_instagram_789", "status": "SCHEDULED" } ] }

status is SCHEDULED when scheduledDate is set, otherwise QUEUED. Publishing happens afterwards: check the result with GET /posts?id=<id>.

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/image" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaId": "img_12345",
    "scheduledDate": "2030-01-15T10:00:00Z",
    "posts": [
      {
        "accountId": "acc_instagram_789",
        "caption": "Golden hour never gets old 🌅 #photography #instagram"
      }
    ]
  }'

POST/post/images

Publish a carousel post to Instagram. Carousels let users swipe through up to 10 images in a single post — ideal for product showcases, step-by-step guides, or photo series. A request with one image is posted as a normal photo.

Instagram Carousel Notes

1 to 10 images per post (one image is posted as a normal photo)
Images are displayed in the order provided in mediaIds
All images in a carousel should share the same aspect ratio
Supported aspect ratios: 1:1 (square), 4:5 (portrait), 1.91:1 (landscape)
Each image is scaled to fit 1080×1920 and padded with white bars if it is narrower than 4:5 or wider than 1.91:1 (never cropped)
caption applies to the whole carousel post, not individual slides
Carousels cannot be posted as a Story
scheduledDate takes any ISO 8601 date-time: Z or an offset such as +01:00 (converted to UTC). Without an offset it is read as UTC.

Request Body

mediaIdsarrayrequired

Ordered array of 1 to 10 image media IDs (one image is posted as a normal photo). Images appear in this order in the carousel.

scheduledDatestringoptional

Optional. A future ISO 8601 date-time, e.g. 2030-01-15T10:00:00Z. Offsets such as +01:00 are converted to UTC; a value without offset is read as UTC. Omit it (or send null) to post immediately.

postsarrayrequired

Array of post objects. Include one object per Instagram account.

posts[].accountIdstringrequired

The id of the connected Instagram account from GET /social-accounts (Crosspostify's account ID, not the Instagram user ID).

posts[].captionstringoptional

Optional (default empty). The carousel caption. Supports hashtags, emojis, and @mentions. Max 2,200 characters: longer text is cut; hashtags after the 30th are removed.

posts[].is_aigcbooleanoptional

Set to true to add Instagram's AI label to the carousel. Default: false.

Response (202 Accepted)

{ "mediaIds": ["img_001", "img_002", "img_003", "img_004", "img_005"], "message": "Multiple images post created successfully", "posts": [ { "id": "7f3c9a2e-1b4d-4c8e-9f60-2a5b7d1e3c48", "platform": "instagram", "socialAccountId": "acc_instagram_789", "status": "SCHEDULED" } ] }

status is SCHEDULED when scheduledDate is set, otherwise QUEUED. Publishing happens afterwards: check the result with GET /posts?id=<id>.

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/images" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaIds": [
      "img_001", "img_002", "img_003",
      "img_004", "img_005"
    ],
    "scheduledDate": "2030-01-15T10:00:00Z",
    "posts": [
      {
        "accountId": "acc_instagram_789",
        "caption": "Swipe to see the full collection 👉 #fashion #ootd"
      }
    ]
  }'

Content Guidelines

Instagram enforces strict media requirements. Images are padded to Instagram's allowed ratios automatically; videos must meet Instagram's specs below.

Instagram allows 50 published posts per account in 24 hours. Crosspostify checks this quota before publishing; when it is used up, the post becomes FAILED with the error "Publishing limit reached for the last 24 hours (usage: N/50)".

Reel (Video) Requirements

Format: MP4 or MOV (H.264 + AAC recommended)
Max file size: 100 MB via Crosspostify
Aspect ratio: 9:16 recommended
Min resolution: 720×1280px recommended
Duration: 3 seconds – 15 minutes (Instagram's limit)

Photo Requirements

Format: JPG, PNG or WEBP (converted to JPEG on upload)
Max file size: 20 MB via Crosspostify
Supported ratios: 1:1, 4:5, 1.91:1 (others are padded with white, not cropped)
Min resolution: 320px on shortest side
Larger images are scaled down to fit 1080×1920 automatically

Caption Best Practices

Max 2,200 characters (longer text is cut)
Max 30 hashtags (extra hashtags are removed automatically)
@mentions are fully supported
Line breaks are preserved (unless the caption has more than 30 hashtags)
Instagram shows only the first lines before "more"; put key text first

Scheduling

Any future time works: no minimum lead time
Published within about a minute of the scheduled time
ISO 8601 with Z or an offset (e.g. +01:00); no offset = UTC
Omit scheduledDate to post immediately
No maximum scheduling window

Account Types

The Instagram API (used by Crosspostify under the hood) only supports Business and Creator accounts. Personal Instagram accounts cannot be connected or posted to via the API.

Business Account✓ SupportedFully supported. Connect via the Crosspostify dashboard.

Creator Account✓ SupportedFully supported. Connect via the Crosspostify dashboard.

Personal Account✗ Not SupportedNot supported by the Instagram API. Must be converted to Business or Creator.

How to switch to a Business or Creator account

In the Instagram app's settings, switch the account to a professional account (Business or Creator) and follow the prompts. This is free.