Skip to content

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

POST /v1/posts request field map
FieldLocationType / valueRequiredness
contentRequest bodystring; caption, capped at 2,200 characters for feed posts; empty for StoriesRequired in examples
platforms[].platformRequest bodystring enum including instagram, tiktok, youtube_shortsRequired in examples
platforms[].accountIdRequest bodystring, connected account idRequired in examples
platforms[].platformSpecificData.contentTypeRequest bodystring; story for StoriesRequired for Story example
platforms[].platformSpecificData.privacyLevelRequest bodystring; PUBLIC_TO_EVERYONE for TikTok exampleTikTok example only
platforms[].platformSpecificData.draftRequest bodyboolean; false for TikTok exampleTikTok example only
mediaItems[].typeRequest bodystring enum: image, videoRequired in examples
mediaItems[].urlRequest bodystring, public media URLRequired in examples
publishNowRequest bodyboolean; true for immediate publishingAlternative to scheduledFor
scheduledForRequest bodystring datetime, e.g. 2026-06-15T09:00:00Alternative to publishNow
timezoneRequest bodystring, e.g. America/New_YorkWith scheduledFor

Field map derived from worked POST /v1/posts examples in source; exact response schemas beyond named fields were not specified.

Instagram media requirements by format
FormatMedia typesAspect ratio / duration / sizeAccount requirement
Feed imageJPG, PNGAspect ratio 4:5 to 1.91:1Instagram Business or Creator account
ReelMP4, MOV9:16 recommended; 23-60 FPS; max 300 MB; duration hold: 3-90 seconds vs 3 seconds-15 minutesInstagram Business or Creator account
CarouselJPG, PNG, MP4, MOV; 2-10 itemsConsistent aspect ratio recommendedInstagram Business or Creator account
StoryImage or video, one itemPublicly accessible media URL; disappears after 24 hoursInstagram 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 matrix for Instagram publishing
Failure checkWhat to inspectAction
Media URL not publicly accessiblePlatform-level error, then errorMessage on retrieved postFix URL accessibility, then retry only the failed platform
Media does not meet format requirementsPlatform-level error, errorMessageCorrect format, aspect ratio, duration, or size, then retry only the failed platform
Account type does not meet format requirementPlatform-level error, errorMessageUse Business or Creator account as required for the format, then retry only the failed platform
Post still processingStatus 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.

Post status values
StatusMeaning
pendingPost created and waiting
scheduledPost queued for scheduledFor time
publishingInstagram is still processing the post
publishedPost is live; platformPostUrl available
failedPublishing failed; inspect errorMessage
partialSome 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.

Connect Instagram and get an authorization URL
curl {{API_BASE_URL}}/v1/connect/instagram \
  -H "x-access-key: YOUR_API_KEY"
List connected integrations to retrieve accountId
curl {{API_BASE_URL}}/v1/connect/integrations \
  -H "x-access-key: YOUR_API_KEY"
Publish a single-image feed post
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
  }'
Publish a Reel with a vertical video
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
  }'
Publish a carousel with mixed mediaItems
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
  }'
Publish an Instagram Story
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
  }'
Schedule an Instagram post with scheduledFor and timezone
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"
  }'
Cross-post one vertical video to Instagram, TikTok, and YouTube Shorts
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
  }'
Pull Instagram analytics for an account
curl "{{API_BASE_URL}}/v1/analytics?source=platform&platform=instagram&accountId=your-ig-id&limit=20" \
  -H "x-access-key: YOUR_API_KEY"