Instagram API for Scheduling Posts: The 2026 Guide
Master the Instagram API for scheduling posts in 2026. Explore Meta Graph API container flows, image ratios, video limits, and clean REST solutions.
If you want to schedule Instagram posts from your own backend or script, working directly with the official instagram api is tricky. You have to submit business registration documents to Meta, write video container polling scripts, and refresh short-lived tokens before they expire. I built Foxli to fix this exact headache. In this walkthrough, I will show you how Meta handles media containers behind the scenes, how to format images and Reels correctly, and how you can schedule single posts or multi-slide carousels using simple HTTP requests.
When I started testing Instagram publishing for my own brand, I was surprised by how many moving parts Meta requires. A single photo post needs two separate API requests. A Reel needs a polling loop that checks transcoding status every few seconds. If an audio track has the wrong sample rate, the container fails with a generic error code. Understanding these quirks helps you build reliable publishing scripts that do not break in production.
How the Native Instagram API Handles Content Publishing
To publish content programmatically, you need to understand Meta's container model. Unlike simpler services where you send caption text and an image in one multipart request, the native Meta Content Publishing API uses a three-step asynchronous pipeline:
Step 1: Media Container Creation
You send a POST request to /{ig-user-id}/media containing your image or video URL, caption text, and post type. Meta downloads your media file from your server, validates the aspect ratio, and returns a container ID called creation_id.
Step 2: Container Status Polling
For video clips and Reels, Meta transcodes the file into its own internal format. Your server must send periodic GET requests to /{creation_id}?fields=status_code. You have to poll this endpoint until Meta returns FINISHED. If the video file has unsupported audio codecs or corrupt frames, the status changes to ERROR and your script must abort.
Step 3: Publishing Dispatch
Once the container status is finished, you send a final POST request to /{ig-user-id}/media_publish with the creation_id. Meta then places the post onto the user's Instagram profile grid.
Why Direct Meta Integration Takes Weeks
This three-step flow protects Meta's infrastructure, but it creates huge hurdles for developers:
- Business verification and app review: To get access to the
instagram_content_publishpermission, you must provide registered business documents, utility bills, and screencasts showing how your software works. Meta review teams often take two to four weeks to respond. - Short token life: User tokens expire after 60 days. If your backend background worker misses a refresh window, all your scheduled posts stop publishing without warning.
- Strict account rules: The API works only with Instagram Professional accounts (Business or Creator) that are linked to an active Facebook Page. Personal profiles cannot use the API.
A Cleaner Alternative: The Foxli REST Gateway
To avoid building container polling loops and managing OAuth refreshes, you can use Foxli as your publishing proxy. You connect your Instagram account once in the Foxli dashboard using standard OAuth. From that point on, your code sends clean JSON requests to https://api.foxli.app/v1:
Your server sends a request with an API key to Foxli. Foxli handles the media container, polls Meta until transcoding completes, and publishes the post.
Through the Foxli Developers Portal, you get several direct advantages:
- No app review required: You can start scheduling immediately with your workspace API key.
- Automatic media checks: Foxli takes care of container creation, video polling, and retry loops in background queues.
- Idempotency support: You pass an
Idempotency-Keyheader with your requests so network retries never produce duplicate posts. - Multi-network publishing: You can send one request that publishes to Instagram, LinkedIn, X, Threads, Facebook, YouTube, and Pinterest at the same time.
Media Guidelines and Formatting Rules for 2026
Before you dispatch any post, check that your files meet the official Instagram Media Specifications:
| Specification | Single Image Post | Instagram Reel (Video) | Multi-Slide Carousel |
|---|---|---|---|
| Supported Formats | JPEG, PNG | MP4, MOV (H.264 / AAC) | JPEG, PNG, MP4 |
| Max File Size | 10 MB | 100 MB | 10 MB per image, 100 MB per video |
| Aspect Ratios | 1:1, 4:5, 1.91:1 | 9:16 (1080x1920 recommended) | All carousel items must share identical aspect ratios |
| Maximum Slides | 1 | Not applicable | Up to 10 media items |
| Caption Limit | 2,200 characters | 2,200 characters | 2,200 characters |
| Maximum Hashtags | 30 | 30 | 30 |
In my testing with carousels, the most common error is mixed aspect ratios. Meta requires every slide in a carousel to match the aspect ratio of the first slide. If your first image is a 1:1 square, every other slide must also be 1:1. If you include a 4:5 portrait slide later in the array, the container creation request fails immediately.
Connecting Your Account and Finding Channel IDs
First, log into Foxli and link your Instagram Creator or Business account. Then open Settings → API & webhooks to create an API key with posts:write and channels:read permissions.
You can inspect your connected accounts using curl:
curl -X GET https://api.foxli.app/v1/channels \
-H "Authorization: Bearer fx_live_your_actual_key_here" \
-H "Foxli-Workspace: ws_prod_marketing"
The response gives you the channel ID to use in your post payloads:
{
"channels": [
{
"id": "ch_ig_9921ab",
"platform": "instagram",
"account_name": "acmecrafts",
"status": "connected",
"profile_url": "https://instagram.com/acmecrafts"
}
]
}
Scheduling a Post With cURL
Foxli takes an ISO-8601 UTC timestamp in the scheduled_at field. For example, if you want an update to go live at 7:00 PM Indian Standard Time (IST), subtract 5 hours and 30 minutes to get the UTC time: 13:30:00Z.
Here is a curl request to schedule a single photo post:
curl -X POST https://api.foxli.app/v1/posts \
-H "Authorization: Bearer fx_live_your_actual_key_here" \
-H "Foxli-Workspace: ws_prod_marketing" \
-H "Idempotency-Key: drop-sku-7781-nov16" \
-H "Content-Type: application/json" \
-d '{
"mode": "schedule",
"channel_ids": ["ch_ig_9921ab"],
"content": "Handcrafted brass decor pieces, sculpted with care by traditional artisans. Which piece speaks to your living space?\n\nComment BRASS to receive our catalogue in your DMs.",
"media_urls": ["https://cdn.example.com/products/brass-lamp-portrait.jpg"],
"scheduled_at": "2026-11-20T13:30:00Z"
}'
If you do not want to calculate exact timestamps for each post, you can set "mode": "queue". Foxli will automatically assign your post to the next available slot defined in your workspace's Instagram scheduler settings.
Scheduling an Instagram Carousel With Node.js
Carousels work well for tutorials, portfolio displays, and product collections. Here is a complete TypeScript script that schedules a 3-slide carousel using Node.js:
import fetch from 'node-fetch';
interface SchedulePostPayload {
mode: 'schedule' | 'queue' | 'now';
channel_ids: string[];
content: string;
media_urls: string[];
scheduled_at?: string;
}
async function scheduleInstagramCarousel() {
const apiKey = process.env.FOXLI_API_KEY!;
const workspaceId = process.env.FOXLI_WORKSPACE_ID!;
const instagramChannelId = 'ch_ig_9921ab';
const payload: SchedulePostPayload = {
mode: 'schedule',
scheduled_at: '2026-11-22T14:00:00Z',
channel_ids: [instagramChannelId],
content: `5 interior ideas for compact apartments in Bangalore 🌿
Swipe through to see before-and-after photos from our latest home makeover.
Comment DESIGN below and we will send the full shopping list straight to your DMs!
#homedecor #interiorstyling #bangalorehomes`,
media_urls: [
'https://assets.example.com/slides/slide-1-living-room.jpg',
'https://assets.example.com/slides/slide-2-lighting.jpg',
'https://assets.example.com/slides/slide-3-materials.jpg',
],
};
const response = await fetch('https://api.foxli.app/v1/posts', {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Foxli-Workspace': workspaceId,
'Idempotency-Key': `carousel-design-${Date.now()}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
if (!response.ok) {
const errorDetails = await response.text();
throw new Error(`API returned HTTP ${response.status}: ${errorDetails}`);
}
const result = await response.json();
console.log('Post successfully scheduled:', result);
}
scheduleInstagramCarousel().catch(console.error);
Automating Inbound Leads With Comment-to-DM Rules
Notice the call-to-action in the caption above: "Comment DESIGN below and we will send the full shopping list straight to your DMs!"
When you pair scheduled posts with Foxli Instagram Auto DM, your post turns into an automatic lead magnet. When someone leaves a comment matching your keyword, Foxli detects the comment, posts a public reply to improve reach, and sends a private message with your download link or catalogue. You do not have to copy and paste replies manually.
Video Requirements for Instagram Reels
Short vertical videos get strong organic reach on Instagram, but publishing Reels through code has strict technical requirements:
First, video container and codec choices matter. Meta accepts MP4 or MOV files encoded with H.264 video and AAC audio. If a video has no audio track, or uses HEVC compression, Meta rejects the container during the processing stage.
Second, audio sample rates must be 44.1 kHz or 48 kHz. Variable audio bitrates can cause sound and picture to drift apart after publishing.
Third, duration limits apply. Reels published through the API can run between 3 seconds and 90 seconds. While you can post longer videos up to 15 minutes as standard feed videos, keeping clips under 90 seconds with a 9:16 vertical ratio ensures they land in the Reels tab.
Fourth, cover images help your feed grid look neat. By default, Meta picks the first video frame as the thumbnail. You can pass a clean graphic URL in the cover_url field to show an intentional thumbnail on your profile.
Common Instagram API Errors and Solutions
When you run automated publishing scripts, you will occasionally see errors returned by Meta's servers. Here is how to handle the most frequent ones:
Subcode 2207001 means Meta could not download your image or video within its 30-second timeout. Make sure your media files are hosted on a fast CDN with direct HTTPS access. Avoid URLs that redirect through multiple links or require login cookies.
Subcode 2207006 indicates an invalid aspect ratio. Instagram supports ratios between 4:5 portrait and 1.91:1 landscape. Crop your images before making the API call so they fall safely within these boundaries.
Subcode 2207003 occurs when slides in a carousel do not match. Remember that all slides must match the aspect ratio of the very first slide.
When an account holder updates their Instagram password, the active access token becomes invalid and the API returns a 401 Unauthorized status. Foxli monitors account connection health and sends webhook alerts so you can reconnect the profile before any scheduled post fails.
Why Indian Creators and Agencies Choose Foxli
Running an agency or content business in India comes with specific operational needs:
- Indian Standard Time (IST) schedules: Engagement on Indian Instagram accounts peaks around lunch (12:00 PM to 1:30 PM IST) and again in the evening (8:00 PM to 10:00 PM IST). Scheduling via UTC timestamps ensures your posts go live right when followers are active.
- Flat per-channel pricing: Traditional tools like Buffer or Hootsuite charge in USD per user seat. If you are comparing Buffer alternatives or Hootsuite alternatives, Foxli costs a flat ₹99 per channel per month. You can add team members without paying per seat.
- Client workspaces: If you manage multiple brands, you can set up separate workspaces to keep tokens and media separate. You can monitor performance across clients using social media analytics.
- Direct domestic payments: Pay in Indian Rupees using UPI, NetBanking, or domestic cards through Razorpay. You avoid currency conversion fees and card authorization failures.
Simple Pricing With Zero Hidden Fees
Many developer tools charge per API call or add steep surcharges for scheduling features. On the Foxli Pricing page, you can see our clear model:
- The Free plan includes scheduling and Auto DM for up to 3 channels.
- The Creator plan costs ₹99 per channel per month (or $0.99 USD). It gives you full REST API access, unlimited scheduled posts, and 120 requests per minute.
- The Team plan costs ₹119 per channel per month (or $1.19 USD), adding team member permissions and post approvals.
If you are ready to automate your Instagram workflow, you can test Foxli for free with up to 3 channels. Connect your account in the dashboard, generate an API key, and send your first scheduled post today.




