Instagram Post API: Publish Posts, Reels, Carousels and Stories
The Instagram post API gives developers a programmatic route to feed posts, Reels, carousels and Stories. Compared with driving the Instagram Graph API directly, where you must create a media container, wait for readiness and then publish, this guide uses one unified endpoint that performs those steps behind a single request. You will connect an Instagram Business account, send exact POST /v1/posts payloads for each format, schedule with scheduledFor, verify status, and fetch analytics.
What you need
Prepare three things before writing code: an API access key, a qualifying Instagram account, and media hosted at a public URL. Personal profiles are excluded from this publishing path, so use an Instagram Business account or a Creator account. Send the key on every call through the x-access-key header and keep it out of repositories. As a pre-flight check, open the media URL in a private browser window to confirm anonymous access, verify the caption stays within the format limit, and match the file type to the format you plan to publish.
Get your API key and connect Instagram
Retrieve your key from the Access Keys page in the dashboard, then attach it as -H "x-access-key: YOUR_API_KEY" on each request. Connection starts with a call to the connect endpoint, which returns an authorization URL. Open that URL, approve the app, and the Instagram Business account becomes linked. Next, list integrations and note the id attached to each linked account; that value becomes accountId inside the platforms array when you post. The integrations dashboard offers the same linking flow through its interface if you prefer clicking.
Post a single image feed post
Text alone is not a valid feed post on Instagram: each one must carry exactly one image or one video, and captions may run to 2,200 characters at most. Build the request with content for the caption, a platforms entry naming instagram plus your accountId, a single mediaItems entry of type image pointing at a public url, and publishNow set to true. Behind the scenes, a media container is created at /{ig-user-id}/media, readiness is polled, and /{ig-user-id}/media_publish is invoked once Instagram signals completion. Expect the published media ID and permalink in the reply. The worked request is shown under the title Publish a single-image feed post.
Post a Reel
Reels reuse the identical POST /v1/posts structure, changing only the mediaItems type from image to video. Short vertical clips are recognised as Reels automatically. Aim for a 9:16 frame in MP4 or MOV. Lightweight spec validation runs before upload begins, protecting your credit balance from media Instagram would reject. The worked request appears under the title Publish a Reel with a vertical video. Duration limits are documented in the media requirements table below, where two differing values from the underlying material are both shown.
Post a carousel
A carousel needs between 2 and 10 entries inside mediaItems. Each entry gets its own child container, the service waits for every child to finish, then builds a parent CAROUSEL container and publishes it, all within one call. Images and videos may be mixed freely. Clips placed inside a carousel count as ordinary videos rather than Reels, because Instagram forbids embedding Reels there; consequently Reel-specific cover, thumbnail and share-to-feed options have no effect in this context. The worked request appears under the title Publish a carousel with mixed mediaItems.
Post an Instagram Story
Stories travel through the same POST /v1/posts endpoint. Inside platforms, set platformSpecificData.contentType to story and supply a single image or video through mediaItems. Only an Instagram Business account qualifies for Story publishing. Because Instagram shows no caption on Stories, content should be an empty string. The media URL must be publicly reachable, and the finished Story expires after 24 hours. The worked request appears under the title Publish an Instagram Story.
Schedule an Instagram post
Deferred delivery replaces the immediate flag: drop publishNow and instead provide scheduledFor together with timezone. The job then waits in a queue until the chosen moment arrives. Both queued and completed items are visible in the Posts dashboard, filterable by status, platform and date. The worked request appears under the title Schedule an Instagram post with scheduledFor and timezone. Double-check that the timezone string expresses the local time you intend, then confirm the status once that time has passed.
Cross-post to Reels, TikTok, and YouTube Shorts
A single vertical clip can reach Instagram, TikTok and YouTube Shorts together by adding tiktok and youtube_shorts entries beside instagram inside platforms. The TikTok entry in the worked request carries platformSpecificData with privacyLevel PUBLIC_TO_EVERYONE and draft false. Each destination still runs its own upload mechanics underneath: Instagram follows container plus publish, TikTok follows Content Posting init and poll, and Shorts follows YouTube resumable upload. The worked request appears under the title Cross-post one vertical video to Instagram, TikTok, and YouTube Shorts.
Check status, handle errors, and pull analytics
Every creation returns a postId for later lookups. Fast jobs may already report published with a platformPostUrl, while slower ones report publishing until Instagram finishes. Poll GET /v1/posts/{postId} or list posts to obtain the newest state, including the Instagram URL and any error detail. On failure, read the platform-level error in the reply and the errorMessage on the fetched post, fix the underlying cause, then retry solely the platform that failed so successful destinations are not duplicated. Analytics come from GET /v1/analytics using source platform, platform instagram, accountId and limit; each such call costs 1 credit regardless of item count and returns likes and comments per media item. The worked request appears under the title Pull Instagram analytics for an account.
| Field | Location | Type / value | Requiredness |
|---|---|---|---|
| content | Request body | string; caption, capped at 2,200 characters for feed posts; empty for Stories | Required in examples |
| platforms[].platform | Request body | string enum including instagram, tiktok, youtube_shorts | Required in examples |
| platforms[].accountId | Request body | string, connected account id | Required in examples |
| platforms[].platformSpecificData.contentType | Request body | string; story for Stories | Required for Story example |
| platforms[].platformSpecificData.privacyLevel | Request body | string; PUBLIC_TO_EVERYONE for TikTok example | TikTok example only |
| platforms[].platformSpecificData.draft | Request body | boolean; false for TikTok example | TikTok example only |
| mediaItems[].type | Request body | string enum: image, video | Required in examples |
| mediaItems[].url | Request body | string, public media URL | Required in examples |
| publishNow | Request body | boolean; true for immediate publishing | Alternative to scheduledFor |
| scheduledFor | Request body | string datetime, e.g. 2026-06-15T09:00:00 | Alternative to publishNow |
| timezone | Request body | string, e.g. America/New_York | With scheduledFor |
Field map derived from worked POST /v1/posts examples in source; exact response schemas beyond named fields were not specified.
| Format | Media types | Aspect ratio / duration / size | Account requirement |
|---|---|---|---|
| Feed image | JPG, PNG | Aspect ratio 4:5 to 1.91:1 | Instagram Business or Creator account |
| Reel | MP4, MOV | 9:16 recommended; 23-60 FPS; max 300 MB; duration hold: 3-90 seconds vs 3 seconds-15 minutes | Instagram Business or Creator account |
| Carousel | JPG, PNG, MP4, MOV; 2-10 items | Consistent aspect ratio recommended | Instagram Business or Creator account |
| Story | Image or video, one item | Publicly accessible media URL; disappears after 24 hours | Instagram Business account |
FACTUAL HOLD: source states Reels duration as 3 to 90 seconds in Step 4 and 3 seconds to 15 minutes in FAQ; both preserved, not resolved. Media must be publicly accessible via URL.
| Failure check | What to inspect | Action |
|---|---|---|
| Media URL not publicly accessible | Platform-level error, then errorMessage on retrieved post | Fix URL accessibility, then retry only the failed platform |
| Media does not meet format requirements | Platform-level error, errorMessage | Correct format, aspect ratio, duration, or size, then retry only the failed platform |
| Account type does not meet format requirement | Platform-level error, errorMessage | Use Business or Creator account as required for the format, then retry only the failed platform |
| Post still processing | Status publishing via GET /v1/posts/{postId} | Wait and re-check status; do not resubmit a duplicate |
Error codes beyond named error and errorMessage fields were not specified in source and are not invented.
| Status | Meaning |
|---|---|
| pending | Post created and waiting |
| scheduled | Post queued for scheduledFor time |
| publishing | Instagram is still processing the post |
| published | Post is live; platformPostUrl available |
| failed | Publishing failed; inspect errorMessage |
| partial | Some platforms published and others did not |
Statuses as named in source; HTTP status codes were not specified and are not invented.
Frequently asked questions
What are Instagram API media requirements?
Requirements vary by format. Single feed images accept JPG or PNG and should sit between 4:5 and 1.91:1. A carousel can hold up to ten items in JPG, PNG, MP4 or MOV, ideally sharing one aspect ratio. Reels accept MOV or MP4 at 23 to 60 frames per second, capped at 300 MB, with 9:16 preferred; duration guidance in the underlying material is inconsistent, so check the media requirements table below before encoding. Every asset needs a publicly reachable URL.
How does a unified Instagram post API handle the Instagram Content Publishing API?
One unified POST /v1/posts request covers feed posts, Reels, Stories and carousels. Supply the linked Instagram account, caption text, media URL and publishing choices; the service then runs the platform-specific asynchronous container and publish steps on your behalf, so separate integrations per format are unnecessary.
What are common Instagram API posting errors and how do I solve them?
Look first at the platform-level error returned with the request, then fetch the post and read its errorMessage. Typical triggers are a media URL that cannot be fetched publicly, an asset outside supported formats or dimensions, or an account category that does not qualify for that format. Once corrected, invoke the retry endpoint aimed only at the platform that failed; anything already live stays untouched.
How can I check my Instagram post status after publishing?
Creation hands back a postId you can reuse for follow-up checks. Quick completions may already report published together with platformPostUrl, whereas slower jobs report publishing while Instagram works. Poll GET /v1/posts/{postId} or list posts for the freshest state. Recognised states are pending, scheduled, publishing, published, failed and partial, and fetched records may carry the Instagram URL plus error detail.
What are the Instagram API rate limits?
Instagram enforces its own native limits, and queued submission helps you stay clear of throttling. A separate plan-based ceiling also applies. Since the practical ceiling blends both layers, no single requests-per-minute figure fits every account.
curl {{API_BASE_URL}}/v1/connect/instagram \
-H "x-access-key: YOUR_API_KEY"curl {{API_BASE_URL}}/v1/connect/integrations \
-H "x-access-key: YOUR_API_KEY"curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{ "platform": "instagram", "accountId": "your-ig-id" }
],
"mediaItems": [
{ "type": "image", "url": "https://your-cdn.com/photo.jpg" }
],
"publishNow": true
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{ "platform": "instagram", "accountId": "your-ig-id" }
],
"mediaItems": [
{ "type": "video", "url": "https://your-cdn.com/reel.mp4" }
],
"publishNow": true
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{ "platform": "instagram", "accountId": "your-ig-id" }
],
"mediaItems": [
{ "type": "image", "url": "https://your-cdn.com/1.jpg" },
{ "type": "image", "url": "https://your-cdn.com/2.jpg" },
{ "type": "video", "url": "https://your-cdn.com/3.mp4" }
],
"publishNow": true
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "",
"platforms": [
{
"platform": "instagram",
"accountId": "your-ig-id",
"platformSpecificData": {
"contentType": "story"
}
}
],
"mediaItems": [
{
"type": "image",
"url": "https://your-cdn.com/story.jpg"
}
],
"publishNow": true
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{ "platform": "instagram", "accountId": "your-ig-id" }
],
"mediaItems": [
{ "type": "image", "url": "https://your-cdn.com/weekly.jpg" }
],
"scheduledFor": "2026-06-15T09:00:00",
"timezone": "America/New_York"
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{ "platform": "instagram", "accountId": "your-ig-id" },
{
"platform": "tiktok",
"accountId": "your-tt-id",
"platformSpecificData": { "privacyLevel": "PUBLIC_TO_EVERYONE", "draft": false }
},
{
"platform": "youtube_shorts",
"accountId": "your-yt-id"
}
],
"mediaItems": [
{ "type": "video", "url": "https://your-cdn.com/vertical.mp4" }
],
"publishNow": true
}'curl "{{API_BASE_URL}}/v1/analytics?source=platform&platform=instagram&accountId=your-ig-id&limit=20" \
-H "x-access-key: YOUR_API_KEY"