Scheduling Posts

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
    }
  }
}

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