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

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)

gallery

GalleryInput

Media gallery containing images and/or videos for the post. Cannot be used with mediaName or mediaUrl.

mediaName

String

Name of a file from your Content Library (case-insensitive). Cannot be used with gallery or mediaUrl.

mediaUrl

String

URL of media to upload and attach to the post. Cannot be used with gallery or mediaName.

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

ID of existing post when updating (only for updates)

InstagramPostSubmissionInputType

Each submission defines a specific posting schedule and format:

postAt

DateTime! required

When to publish the content (must be in the future)

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",
    "mediaUrl": "https://picsum.photos/seed/socialmedia/900/1600",
    "submissions": [
      {
        "postAt": "2025-12-01T18:00:00Z",
        "mediaType": "FEED_POST"
      }
    ]
  }
}

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 📸✨",
    "gallery": {
      "galleryMediaSet": [
        {
          "order": 0,
          "media": {
            "id": "MEDIA_ID_1"
          }
        },
        {
          "order": 1,
          "media": {
            "id": "MEDIA_ID_2"
          }
        },
        {
          "order": 2,
          "media": {
            "id": "MEDIA_ID_3"
          }
        }
      ]
    },
    "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",
    "mediaName": "tutorial-video.mp4",
    "submissions": [
      {
        "postAt": "2025-12-01T16:00:00Z",
        "mediaType": "REEL",
        "shareToFeed": true
      }
    ]
  }
}

Instagram Story

Schedule a temporary Story post.

{
  "input": {
    "username": "myhandle",
    "mediaUrl": "https://picsum.photos/seed/socialmedia/900/1600",
    "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"],
    "mediaUrl": "https://picsum.photos/seed/socialmedia/900/1600",
    "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.

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