Instagram Scheduling API
Schedule Instagram posts for a future time via API, with a stable Idempotency-Key so a retry never double-posts.
By André LugInstagram’s Graph API has no native “publish later” field — containers expire unpublished after roughly 24 hours. With PostGate, add an ISO 8601 scheduled_at to the normal POST /api/posts envelope (or scheduled_at: "queue" for the next open slot); PostGate holds the request and builds a fresh container close to the scheduled instant. Use a stable Idempotency-Key derived from your job ID.
Instagram's own Graph API has no native "publish later" field — a container either publishes now or expires unpublished after roughly 24 hours. Scheduling is something a layer above the Graph API has to build: hold the request, wake up at the right instant, build the container fresh, and handle whatever has changed about the account in the meantime. This page covers that layer, plus the one detail that matters most for scheduled posts specifically — safe retries.
How do I schedule a single post?
Add scheduled_at as an ISO 8601 timestamp to the same envelope you would use for an immediate post — see one endpoint, four publishing modes. Nothing else about the request changes.
curl -X POST "https://api.postgate.studio/api/posts" \
-H "Authorization: Bearer $POSTGATE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ig-schedule-launch-01" \
-d '{
"post": { "body": "Launching in the morning." },
"profiles": ["pro_instagram123"],
"media": ["https://cdn.example.com/teaser.jpg"],
"scheduled_at": "2026-09-02T09:00:00-03:00"
}'Can I queue instead of picking a fixed time?
Set scheduled_at: "queue" to drop a post into the next open slot on a recurring schedule rather than picking an exact instant — see schedules & queues for defining daily slots or a cron expression that a template repeats against.
Why does idempotency matter more for scheduled posts?
A scheduled post usually comes from your own job queue or cron-like system, which means it is exactly the kind of request your infrastructure will retry automatically on a timeout — often hours after the original attempt, with no human watching. Without a stable Idempotency-Key, a retried scheduling request creates a second scheduled post that fires at the same time as the first, and a customer's account posts the same thing twice with no one around to catch it. Derive the key from your own job ID, not a fresh UUID per attempt, so PostGate recognizes the retry as the same logical request.
Does the container still expire on a schedule?
PostGate does not build the Instagram media container until close to the scheduled instant, specifically because Instagram containers expire around 24 hours after creation. Scheduling a post a week out does not mean a container sits waiting that whole time — it means PostGate re-validates the media and builds a fresh container right before publish, which is also why a scheduled post can still fail on media validation at the scheduled time even though it validated fine when you created it.
What happens if the account disconnects before the scheduled time?
A scheduled post does not fail silently if the connected account's authorization lapses before its scheduled time. The target enters awaiting_reconnect, and a profile.reauth_required or profile.expired webhook fires so you can prompt the customer before the window closes rather than discovering it after a missed post.
Frequently asked questions
Does Instagram’s API support scheduling posts natively?
No. Instagram’s own Graph API has no native “publish later” field — a container either publishes now or expires unpublished after roughly 24 hours. Scheduling is built by a layer above the Graph API: hold the request, wake up at the right instant, build the container fresh, and handle whatever has changed about the account in the meantime.
Why can a scheduled Instagram post fail media validation at publish time?
PostGate does not build the Instagram media container until close to the scheduled instant, because containers expire around 24 hours after creation. Scheduling a week out means PostGate re-validates the media and builds a fresh container right before publish — so a post can still fail on media validation at the scheduled time even though it validated fine when you created it.
Why does idempotency matter more for scheduled Instagram posts?
A scheduled post usually comes from your own job queue or cron-like system — exactly the kind of request your infrastructure retries automatically on a timeout, often with no human watching. Without a stable Idempotency-Key, a retried scheduling request creates a second scheduled post that fires at the same time as the first. Derive the key from your own job ID, not a fresh UUID per attempt.
What happens if the Instagram account disconnects before the scheduled time?
The post does not fail silently. The target enters awaiting_reconnect, and a profile.reauth_required or profile.expired webhook fires so you can prompt the customer before the window closes rather than discovering it after a missed post.
