Skip to main content

​
Overview

Postiz integrates with Instagram through the Facebook Graph API, allowing you to schedule posts, reels, stories, and carousel content to Instagram Business accounts.
Requirements:
  • Instagram account must be a Business Account
  • Account must be connected to a Facebook Page
  • Not compatible with personal Instagram accounts

​
Authentication

Instagram authentication is done through Facebook OAuth with specific Instagram permissions.
1

Convert to Business Account

If not already done, convert your Instagram account to a Business Account in Instagram settings
2

Link to Facebook Page

Connect your Instagram Business account to a Facebook Page
3

Connect via Postiz

Click “Connect Instagram” and authorize all requested permissions
4

Select Instagram Account

Choose which Instagram Business account to connect from your linked pages

​
Required Permissions

  • instagram_basic - Basic profile information
  • instagram_content_publish - Post content
  • instagram_manage_comments - Manage comments
  • instagram_manage_insights - Access analytics
  • pages_show_list - List connected pages
  • pages_read_engagement - Read page engagement
  • business_management - Business account management

​
Supported Features

​
Post Types

Single Image/Video:
  • Max caption: 2200 characters
  • Image: Up to 1080px, aspect ratio 4:5 to 1.91:1
  • Video: MP4 format, minimum 720p
Carousel:
  • Multiple images (up to 10)
  • All images must have compatible aspect ratios
  • Cannot mix images and videos in carousel

​
Media Requirements

Instagram requires at least one attachment. Text-only posts are not supported. Stories can have only one picture or video.

​
Image Specifications

  • Formats: JPG, PNG (automatically converted)
  • Resolution: Max 1920x1080px, minimum 320px
  • Aspect Ratio: Between 4:5 and 1.91:1
  • Size: Under 8MB recommended

​
Video Specifications

  • Format: MP4
  • Resolution: Minimum 720p
  • Aspect Ratio: Flexible, but 9:16 for Reels and Stories
  • Duration: Up to 60 seconds for feed, 90 seconds for Reels

​
Advanced Post Settings

Test your reel with a smaller audience before full publication:
{
  is_trial_reel: true,
  graduation_strategy: "MANUAL" // or "AUTO"
}
Tag other Instagram accounts as collaborators:
  • Not available for carousels
  • Not available for stories
  • Collaborators must approve the tag

​
Post Processing

Instagram posts go through several processing stages:
1

Media Upload

Media files are uploaded to Instagram servers
2

Processing

Instagram processes the media (status: IN_PROGRESS)
3

Publication

Once processing completes, the post is published
Processing can take 30+ seconds per media item. Postiz automatically waits for processing to complete.

​
Comments & Engagement

Add comments to your Instagram posts:
  • Comments posted as your Instagram Business account
  • Max 2200 characters per comment
  • Posted immediately after main post publishes

​
Analytics

Track comprehensive Instagram metrics:

​
Account-Level Analytics

  • Followers: Total follower count
  • Reach: Unique accounts reached
  • Likes: Total likes on content
  • Views: Video/Reel views
  • Comments: Comment engagement
  • Shares: Content shares
  • Saves: Content saves
  • Replies: Story replies

​
Post-Level Analytics

  • Views (for videos/reels)
  • Reach
  • Engagement
  • Saves
  • Likes
  • Comments
  • Shares

​
Error Handling

Common Instagram errors and solutions:
Error CodeErrorSolution
2207001Spam detectedChange content to avoid spam filters
2207009Invalid aspect ratioResize to 4:5 - 1.91:1 range
2207042Daily limit reachedMax 25 posts/day - wait until tomorrow
36001Resolution too highMax 1920x1080px
190Missing permissionsReconnect account with all permissions
2207081Trial reels not supportedAccount doesn’t support trial reels
Permission Errors: If you see error 190, you need to reconnect your account and ensure all permissions are granted during the OAuth flow.

​
Rate Limits

Instagram Limits:
  • Maximum 25 posts per day per account
  • Maximum 400 concurrent jobs (generous limit)
  • Page rate limits may apply for high-volume posting

​
Best Practices

Optimal Image Size

Use 1080x1080px for square posts, 1080x1350px for portrait

Hashtag Strategy

Include relevant hashtags in captions (up to 30)

Reel Performance

Vertical 9:16 reels perform best in the algorithm

Posting Schedule

Best times: 11 AM - 1 PM and 7 PM - 9 PM

​
Troubleshooting

If your Instagram account isn’t showing:
  • Verify it’s a Business account
  • Ensure it’s connected to a Facebook Page
  • Check that the connected Page is accessible
  • Try reconnecting both Facebook and Instagram
Common media upload issues:
  • Check aspect ratio is within 4:5 to 1.91:1
  • Verify resolution doesn’t exceed 1920x1080
  • Ensure file format is supported (JPG/PNG/MP4)
  • Try re-uploading or converting the file
Collaborator limitations:
  • Not supported for carousel posts
  • Not supported for story posts
  • Other account must approve the collaboration
  • Only works with Instagram Business accounts
Instagram tokens expire after 60 days:
  • Postiz automatically refreshes tokens
  • If refresh fails, manually reconnect
  • Ensure Facebook permissions are still granted

​
Music Integration

Search and add music to your Reels: 
POST /music/search?q=song+name
Returns available music tracks from Instagram’s library.

Build docs developers (and LLMs) love

Get started for freeTalk to us