Platforms

Instagram

Schedule feed posts, Reels, Stories, and carousels to Instagram

Mutation

Use the scheduleInstagramPost mutation to schedule content to Instagram:

Mutation

mutation ScheduleInstagramPost($input: ScheduleInstagramPostInput!) {
  scheduleInstagramPost(input: $input) {
    success
    errors {
      field
      message
    }
    post {
      id
      socialAccount {
        id
        username
      }
      publishingStatus
      caption
      firstComment
      collaborators
      gallery {
        id
        galleryMediaSet {
          id
          media {
            url
            mimeType
          }
        }
      }
      submissions {
        id
        mediaType
        shareToFeed
        postAt
        publishingMethod
      }
    }
  }
}

Input Parameters

ScheduleInstagramPostInput

username

String! required

The username of the connected Instagram account to post from

schedulingMode

SchedulingModeType

How the post date is decided. Options: SPECIFIC_TIME, QUEUE_NEXT (default: SPECIFIC_TIME). Only accepted when scheduling a new post. See Scheduling at the Next Open Slot.

caption

String

The main caption for the post (max 2,200 characters, 3-5 hashtags recommended)

firstComment

String

The first comment to be posted automatically with the post

collaborators

[String!]

Array of Instagram usernames to tag as collaborators (max 3 collaborators)

media

[SimpleMediaInput]

Media files to attach to the post. Each item references a file by id, name, or url. See Attaching Media. Only supported when scheduling new posts, not when updating existing ones.

submissions

[InstagramPostSubmissionInputType!]! required

Array of submissions defining when and how to post (minimum 1 submission)

publishingStatus

PublishingStatusType

Publishing status. Options: READY_TO_PUBLISH, DRAFT (default: READY_TO_PUBLISH)

postTags

[ID!]

Array of post tag IDs to organize your content. See Post Tags.

ID of existing post when updating (only for updates)

InstagramPostSubmissionInputType

Each submission defines a specific posting schedule and format:

postAt

DateTime

When to publish the content (must be in the future). Required unless you pass schedulingMode: QUEUE_NEXT on the post when scheduling a new one, or the post is a draft. See Drafts without a date.

mediaType

InstagramMediaType! required

Type of Instagram content. Options: FEED_POST, CAROUSEL, REEL, STORY

shareToFeed

Boolean

Whether to share a Reel to the main feed as well (only applies to Reels, default: false)

publishingMethod

PublishingMethodType

How to publish the content. Options: AUTOMATIC, MANUAL (default: AUTOMATIC)

ID of existing submission when updating (only for updates)

Media Types

Instagram supports four different content types, each with specific requirements:

Feed Post

Single image or video posted to the main Instagram feed
Supports square (1:1), portrait (4:5), or landscape (1.91:1) aspect ratios
Maximum file size: 30MB for videos, 8MB for images

Carousel

Multiple images and/or videos in a single post (2-10 items)
All media items appear in a swipeable gallery
Mixed media types supported (images and videos together)

Reel

Short-form vertical video content (9:16 aspect ratio recommended)
Minimum duration: 3 seconds
Can optionally be shared to the main feed using shareToFeed: true

Story

Temporary content that disappears after 24 hours
Single image or video only
Vertical format (9:16) recommended

Examples

Feed Post with Single Image

Schedule a basic Instagram feed post with an image from URL.

{
  "input": {
    "username": "myhandle",
    "caption": "Beautiful sunset from our latest adventure! 🌅 #photography #sunset #travel",
    "media": [{ "url": "https://example.com/sunset.jpg" }],
    "submissions": [
      {
        "postAt": "2025-12-01T18:00:00Z",
        "mediaType": "FEED_POST"
      }
    ]
  }
}

Scheduling at the Next Open Slot

Instead of picking a time yourself, pass schedulingMode: QUEUE_NEXT and leave postAt out. Postpone puts the post in the next open slot on the account's Account Schedule, skipping any slot that already has a post on it.

{
  "input": {
    "username": "myhandle",
    "schedulingMode": "QUEUE_NEXT",
    "caption": "This one goes out at my next open slot.",
    "media": [{ "url": "https://example.com/sunset.jpg" }],
    "submissions": [
      {
        "mediaType": "FEED_POST"
      }
    ]
  }
}

Leave postAt off the submissions — the resolved slot becomes the date for all of them.

The account needs a schedule set up for this to work, postAt and QUEUE_NEXT can't be combined, and updateScheduledInstagramPost rejects schedulingMode. See Scheduling at the Next Open Slot for the full rules.

Carousel Post with Multiple Images

Schedule a carousel post with multiple images from your Content Library.

{
  "input": {
    "username": "myhandle",
    "caption": "Behind the scenes from our latest photoshoot! Swipe to see more 📸✨",
    "media": [{ "id": "1231" }, { "id": "1233" }, { "id": "1235" }],
    "submissions": [
      {
        "postAt": "2025-12-01T15:30:00Z",
        "mediaType": "CAROUSEL"
      }
    ]
  }
}

Schedule a Reel that will also appear in the main feed.

{
  "input": {
    "username": "myhandle",
    "caption": "Quick tutorial on our latest technique! Save this for later 💡 #tutorial #tips #howto",
    "media": [{ "name": "tutorial-video.mp4" }],
    "submissions": [
      {
        "postAt": "2025-12-01T16:00:00Z",
        "mediaType": "REEL",
        "shareToFeed": true
      }
    ]
  }
}

Instagram Story

Schedule a temporary Story post.

{
  "input": {
    "username": "myhandle",
    "media": [{ "url": "https://example.com/story-image.jpg" }],
    "submissions": [
      {
        "postAt": "2025-12-01T14:00:00Z",
        "mediaType": "STORY"
      }
    ]
  }
}

Post with Collaborators and First Comment

Schedule a post with tagged collaborators and an automatic first comment.

{
  "input": {
    "username": "myhandle",
    "caption": "Amazing collaboration with some incredible creators! 🤝",
    "firstComment": "Thanks to everyone who made this possible! Check out their profiles 👆",
    "collaborators": ["collaborator1", "collaborator2", "collaborator3"],
    "media": [{ "url": "https://example.com/collab-photo.jpg" }],
    "submissions": [
      {
        "postAt": "2025-12-01T19:00:00Z",
        "mediaType": "FEED_POST"
      }
    ]
  }
}

Response Types

Success Response

{
  "data": {
    "scheduleInstagramPost": {
      "success": true,
      "errors": [],
      "post": {
        "id": "123",
        "socialAccount": {
          "id": "456",
          "username": "myhandle"
        },
        "publishingStatus": "READY_TO_PUBLISH",
        "caption": "Beautiful sunset from our latest adventure! 🌅 #photography #sunset #travel",
        "firstComment": "",
        "collaborators": [],
        "gallery": {
          "id": "789",
          "media": [
            {
              "id": "101",
              "url": "https://cdn.example.com/sunset.jpg",
              "type": "image"
            }
          ]
        },
        "submissions": [
          {
            "id": "112",
            "mediaType": "FEED_POST",
            "shareToFeed": false,
            "postAt": "2025-12-01T18:00:00Z",
            "publishingMethod": "AUTOMATIC"
          }
        ]
      }
    }
  }
}

Error Response

{
  "data": {
    "scheduleInstagramPost": {
      "success": false,
      "errors": [
        {
          "field": "caption",
          "message": "Instagram captions can have at most 30 hashtags, but yours has 35 (3-5 hashtags recommended)"
        }
      ],
      "post": null
    }
  }
}

Updating a Post

To update an existing scheduled post, use the same input type with the corresponding update mutation and include the post id:

Mutation

mutation UpdateScheduledInstagramPost($input: ScheduleInstagramPostInput!) {
  updateScheduledInstagramPost(input: $input) {
    success
    errors {
      field
      message
    }
    post {
      id
    }
  }
}

Pass the id of the post you want to update in the input, along with the fields you want to change:

{
  "input": {
    "id": "12345",
    "username": "myhandle",
    "caption": "Updated caption!",
    "submissions": [{"postAt": "2025-12-01T15:30:00Z", "mediaType": "FEED"}]
  }
}

The update mutation uses the same input type as the create mutation. Include the id field to specify which post to update. Only scheduled posts that have not been published yet can be updated.

postAt is required on an update, so every update states the date the post goes out on — pass the date it already has to leave it where it is. A draft staying a draft is exempt, and a draft you're promoting to READY_TO_PUBLISH needs a date of your choosing; see Drafts without a date.

schedulingMode is not accepted on an update at all; see Scheduling at the Next Open Slot.

Validation Rules

The API enforces Instagram's content policies and technical limitations:

Caption Length: Maximum 2,200 characters
Hashtags: Maximum 30 hashtags per caption (3-5 recommended for better reach)
Collaborators: Maximum 3 collaborators per post
Carousel Media: 2-10 images/videos per carousel
Reel Duration: Minimum 3 seconds for video content
Aspect Ratios: Images must be between 0.558:1 and 1.92:1 (approximately)
File Sizes: Videos max 30MB, images max 8MB
GIF Support: GIFs are not supported on Instagram
Story Limit: Stories can only contain one image or video
Scheduling: Posts must be scheduled for future dates only
Account Limits: Respects your plan's monthly post limits

Common Errors

X/Twitter

Schedule tweets and threads with media attachments

Facebook

Schedule posts, reels, and stories to Facebook pages