Instagram Posting API
The Instagram Posting API lets a product publish feed posts, Stories, Reels, and carousels through one endpoint, so a team can add Instagram publishing without implementing the native Instagram Graph API flow itself.
POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
{
"content": "A short example update.",
"platforms": [
{
"platform": "instagram",
"accountId": "ig_456"
}
],
"mediaItems": [
{
"type": "image",
"url": "https://cdn.example.com/photo.jpg"
}
],
"publishNow": true
}POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
Use it to publish now, schedule for later, or include Instagram alongside other platforms in the same request.
Add Instagram publishing through one API
Publish Instagram content through a single endpoint instead of implementing the native Graph API flow yourself. The same endpoint handles feed posts, Stories, Reels, and carousels, and Instagram Login is described as requiring no linked Facebook Page. Publishing can happen immediately, be scheduled for a future date and time, or be combined with other platforms in one request.
Integration follows three steps. First, get an API key through sign-up. Second, connect once and use the API to publish, schedule, analyze, manage comments, and handle messages. Third, support multiple platforms through the same API instead of building and maintaining each integration separately. See the Feed Post Request Example and Feed Post Response Example for the exact contract to implement against.
Exact endpoint and Feed Post worked example
Every format uses POST {{API_BASE_URL}}/v1/posts. In the supplied Feed Post example, content carries the caption text, platforms identifies the Instagram target, and mediaItems carries the image to publish. The platforms entry uses platform set to instagram and accountId set to ig_456. The mediaItems entry uses type set to image and url pointing to the hosted image. Setting publishNow to true requests immediate publishing.
The response uses HTTP status 202 and returns success as true, status as published, and postId as post_def456. Its platforms array returns one entry for instagram with success as true and platformPostUrl pointing to the published post. Check platformPostUrl on the per-platform entry rather than assuming the top-level postId is the Instagram URL. Before sending, confirm the accountId belongs to the connected Instagram account, confirm the media URL is reachable, and confirm whether you intend immediate publishing with publishNow or scheduled publishing with scheduledFor.
Formats, media, and eligibility checks
Use the Format Decision Table to choose the format before building the request. Feed posts publish a single image with captions and hashtags. Reels publish video with captions through an asynchronous Instagram media publishing flow. Carousels use multiple mediaItems, up to 10 images or videos. Stories are listed as a supported format, but no Story-specific fields were supplied, so do not invent Story fields beyond the supported-format statement. Cross-posting publishes the same content to Instagram and other supported platforms in one request by adding platform targets.
Use the Eligibility and Failure Matrix as a pre-publish checklist. A text-only feed post fails the media requirement because Instagram feed publishing requires at least one media item. Feed posts and Reels require a professional Business or Creator account, while Stories require a Business account. Media must meet Instagram's documented format, aspect-ratio, duration, and file-size requirements; only the Reel limits below are specified in the supplied material, so do not assume other format limits. For scheduling, use scheduledFor with an optional IANA timezone, and omit publishNow or set it to false. For immediate publishing, use publishNow as shown in the example.
Reels and carousels
To publish Instagram Reels, supply a video that meets the stated Reel limits: MOV or MP4, 23–60 FPS, 3 seconds to 15 minutes, and no more than 300 MB. Reels can be customized with a custom cover image or thumbnail offset, Reel-only publishing using shareToFeed: false, audio naming, collaborators, and eligible Trial Reels. Because Reel publishing follows an asynchronous media flow, treat the initial response as the start of that flow and verify the per-platform result before reporting the Reel as published.
Instagram carousel posts are created by passing multiple mediaItems, up to 10 images or videos, and letting the publishing workflow handle the carousel. Verify each item meets the applicable media requirements before sending, and check the per-platform response for the Instagram result.
Scheduling and adjacent capabilities
Scheduled Instagram posts use the same posting endpoint. Set scheduledFor to the future date and time and optionally provide an IANA timezone; omit publishNow or set it to false. After scheduling, verify the returned status and postId, and keep the scheduled time and timezone together in your own records so the intended delivery time is unambiguous.
Beyond publishing, the same connected Instagram account can support Instagram Scheduling for managing upcoming posts, Instagram Analytics for performance data in dashboards and reporting, Instagram Comments for reading and responding to comments, and Instagram Messaging for reading and replying to direct messages. These are adjacent capabilities, not fields in the Feed Post example, so implement them through their own documented workflows rather than adding invented fields to the posting request.
Stacks, platforms, and capabilities
The same API can be used from a developer stack with typed SDKs and REST calls, from no-code tools such as Zapier, Make, and n8n, or from AI agents through a hosted MCP server, agent skills, and an OpenAI tool-calling schema. The underlying publishing contract does not change with the calling stack: the request still targets POST /v1/posts with the same fields.
Other platforms listed for the same API are Twitter / X, YouTube, Facebook, TikTok, Threads, Pinterest, LinkedIn, Bluesky, and Google Business, alongside Instagram. Additional capabilities listed are scheduling, analytics, comments, messaging, and comment-to-DM automation. Use the platform list to plan cross-posting, but only add a platform target when that platform's own requirements are met.
| Format | Supplied distinction | Key fields or options |
|---|---|---|
| Feed Post | Single-image feed post with captions and hashtags | content, platforms, mediaItems, publishNow |
| Story | Supported format; no Story-specific contract supplied | Use the same endpoint; do not invent fields |
| Reel | Video with captions; asynchronous Instagram media publishing flow | Video mediaItems; cover/thumbnail offset, shareToFeed: false, audio naming, collaborators, Trial Reels |
| Carousel | Up to 10 images or videos | Multiple mediaItems |
| Cross-Post | Same content to Instagram and other supported platforms in one request | Multiple platform targets in platforms |
Only supplied distinctions are used; no Story-specific fields were supplied.
| Check | Rule | Failure action |
|---|---|---|
| Text-only feed post | At least one media item is required | Do not send; add an image or video |
| Feed post or Reel account | Instagram professional Business or Creator account required | Use an eligible connected account |
| Story account | Business account required | Use a Business account |
| Reel media | MOV or MP4, 23–60 FPS, 3 seconds to 15 minutes, maximum 300 MB | Replace or re-encode the video before sending |
| Scheduled post | Use scheduledFor and optional IANA timezone; omit publishNow or set it to false | Set scheduledFor and omit publishNow or set it to false |
| Immediate post | publishNow: true as in the supplied example | Use publishNow: true for immediate publishing |
Reel limits are the only numeric media limits supplied.
| Field | Location | Supplied value or rule |
|---|---|---|
| content | Request | New product launch! #startup #launch |
| platforms[].platform | Request | |
| platforms[].accountId | Request | ig_456 |
| mediaItems[].type | Request | image |
| mediaItems[].url | Request | https://cdn.example.com/photo.jpg |
| publishNow | Request | true for immediate publishing; omit or set false when scheduling |
| scheduledFor | Request | Future date and time for scheduled Instagram posts |
| success | Response | true |
| status | Response | published |
| postId | Response | post_def456 |
| platforms[].success | Response | true |
| platforms[].platformPostUrl | Response | https://www.instagram.com/p/ABC123/ |
Field map is limited to the supplied Feed Post example and named scheduling fields.
Frequently asked questions
What can I publish to Instagram through the Instagram Posting API?
Supported formats are feed posts, Stories, Reels, and carousels.
Can I publish a text-only Instagram post?
Text alone is not enough for a feed post. Include at least one image or video alongside the caption.
What Instagram account type do I need?
For feed posts and Reels, connect a professional account classified as Business or Creator. Stories call for a Business account.
What are the Instagram Reel limits?
Use MOV or MP4 at 23–60 FPS, keep length between 3 seconds and 15 minutes, and stay at or below 300 MB.
Can I customize an Instagram Reel?
Yes. Available Reel choices cover a custom cover or thumbnail offset, keeping the Reel off the feed with shareToFeed: false, naming audio, adding collaborators, and Trial Reels where eligible.
Can I schedule Instagram posts?
Yes. Send the request to /v1/posts with scheduledFor and, if needed, an IANA timezone. Leave publishNow out or set it to false.
What can I build with the Instagram Posting API?
Social media management tools, SaaS products, automated workflows, and AI agents can add Instagram publishing through this endpoint.
202
{
"success": true,
"status": "published",
"postId": "post_def456",
"platforms": [
{
"platform": "instagram",
"success": true,
"platformPostUrl": "https://www.instagram.com/p/ABC123/"
}
]
}