Docs/API Reference/Instagram

Instagram API

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

Post Types

Reel · Photo · Carousel

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. Your Instagram account ID from /social-accounts.

caption✓ AppliesRequired. Supports hashtags, emojis, and @mentions.

title✗ IgnoredNot used for Instagram — ignored.

is_aigc✗ IgnoredTikTok only — ignored for Instagram.

boardId✗ IgnoredPinterest only — ignored for Instagram.

link✗ IgnoredPinterest only — ignored for Instagram.

facebookFirstComment✗ IgnoredFacebook only — ignored for Instagram.

textFormatPresetId✗ IgnoredFacebook only — ignored for Instagram.

Supported Endpoints

Instagram supports the following Crosspostify API endpoints:

Text-only and Stories not supported

Instagram does not support text-only posts or Stories via the Crosspostify API. All posts require a media file (image or video).

POST/post/video

Publish a video to Instagram as a Reel. Instagram automatically processes uploaded videos as Reels in the 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
All datetime values must be in UTC timezone (ISO 8601 format with Z suffix)
Omit scheduledDate to post immediately (queued)

Request Body

mediaIdstringrequired

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

scheduledDatestringoptional

Schedule the post for a future time (ISO 8601 with 'Z' suffix). Omit to post immediately.

postsarrayrequired

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

posts[].accountIdstringrequired

The Instagram account ID. Retrieve from GET /social-accounts.

posts[].captionstringrequired

The Reel caption. Supports hashtags, emojis, and @mentions. Max 2,200 characters.

Response

{ "success": true, "data": { "postId": "post_ghi789", "status": "PROCESSING", "scheduledDate": "2025-06-01T14:00:00Z", "videoDuration": 30, "accounts": [ { "accountId": "acc_instagram_789", "platform": "instagram", "status": "PROCESSING" } ] } }

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": "2025-06-01T14:00:00Z",
    "posts": [
      {
        "accountId": "acc_instagram_789",
        "caption": "New Reel just dropped 🎬✨ #reels #instagram #fyp"
      }
    ]
  }'

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)
Images outside these ratios will be cropped by Instagram
caption supports hashtags, emojis, and @mentions
All datetime values must be in UTC timezone (ISO 8601 format with Z suffix)

Request Body

mediaIdstringrequired

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

scheduledDatestringoptional

Schedule the post for a future time (ISO 8601 with 'Z' suffix). Omit to post immediately.

postsarrayrequired

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

posts[].accountIdstringrequired

The Instagram account ID. Retrieve from GET /social-accounts.

posts[].captionstringrequired

The photo caption. Supports hashtags, emojis, and @mentions. Max 2,200 characters.

Response

{ "success": true, "data": { "postId": "post_abc123", "status": "SCHEDULED", "scheduledDate": "2025-06-01T14:00:00Z", "accounts": [ { "accountId": "acc_instagram_789", "platform": "instagram", "status": "SCHEDULED" } ] } }

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": "2025-06-01T14: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.

Instagram Carousel Notes

Maximum 10 images per carousel post, minimum 2
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)
caption applies to the whole carousel post, not individual slides
All datetime values must be in UTC timezone (ISO 8601 format with Z suffix)

Request Body

mediaIdsarrayrequired

Ordered array of image media IDs (min 2, max 10 for Instagram). Images appear in this order in the carousel.

scheduledDatestringoptional

Schedule the post for a future time (ISO 8601 with 'Z' suffix). Omit to post immediately.

postsarrayrequired

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

posts[].accountIdstringrequired

The Instagram account ID. Retrieve from GET /social-accounts.

posts[].captionstringrequired

The carousel caption. Supports hashtags, emojis, and @mentions. Max 2,200 characters.

Response

{ "success": true, "data": { "postId": "post_def456", "status": "SCHEDULED", "scheduledDate": "2025-06-01T14:00:00Z", "mediaCount": 5, "accounts": [ { "accountId": "acc_instagram_789", "platform": "instagram", "status": "SCHEDULED" } ] } }

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": "2025-06-01T14:00:00Z",
    "posts": [
      {
        "accountId": "acc_instagram_789",
        "caption": "Swipe to see the full collection 👉 #fashion #ootd"
      }
    ]
  }'

Content Guidelines

Instagram enforces strict media requirements. Posts that don't meet these specs may be rejected by Instagram's API or auto-cropped in unexpected ways.

Reel (Video) Requirements

Format: MP4 (H.264 codec recommended)
Max file size: 100MB via Crosspostify
Aspect ratio: 9:16 recommended
Min resolution: 720×1280px
Duration: 3 seconds – 15 minutes

Photo Requirements

Format: JPG or PNG
Max file size: 20MB via Crosspostify
Supported ratios: 1:1, 4:5, 1.91:1
Min resolution: 320px on shortest side
Max resolution: 1440px on longest side

Caption Best Practices

Max 2,200 characters
Up to 30 hashtags per post
@mentions are fully supported
Line breaks are preserved
First 125 chars shown before "more"

Scheduling

Minimum lead time: ~10 minutes ahead
All times must be UTC (ISO 8601 + Z)
Omit scheduledDate to post immediately
Max scheduling window: 75 days ahead

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, go to Settings → Account → Switch to Professional Account and follow the prompts. This is free and takes under a minute.