Skip to content

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.

Feed Post Request Example
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
}
Illustrative request
Example line 1

POST {{API_BASE_URL}}/v1/posts

Illustrative request
Example line 2

x-access-key: YOUR_API_KEY

Illustrative request
Example line 3

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 Decision Table
FormatSupplied distinctionKey fields or options
Feed PostSingle-image feed post with captions and hashtagscontent, platforms, mediaItems, publishNow
StorySupported format; no Story-specific contract suppliedUse the same endpoint; do not invent fields
ReelVideo with captions; asynchronous Instagram media publishing flowVideo mediaItems; cover/thumbnail offset, shareToFeed: false, audio naming, collaborators, Trial Reels
CarouselUp to 10 images or videosMultiple mediaItems
Cross-PostSame content to Instagram and other supported platforms in one requestMultiple platform targets in platforms

Only supplied distinctions are used; no Story-specific fields were supplied.

Eligibility and Failure Matrix
CheckRuleFailure action
Text-only feed postAt least one media item is requiredDo not send; add an image or video
Feed post or Reel accountInstagram professional Business or Creator account requiredUse an eligible connected account
Story accountBusiness account requiredUse a Business account
Reel mediaMOV or MP4, 23–60 FPS, 3 seconds to 15 minutes, maximum 300 MBReplace or re-encode the video before sending
Scheduled postUse scheduledFor and optional IANA timezone; omit publishNow or set it to falseSet scheduledFor and omit publishNow or set it to false
Immediate postpublishNow: true as in the supplied exampleUse publishNow: true for immediate publishing

Reel limits are the only numeric media limits supplied.

Feed Post Field Map
FieldLocationSupplied value or rule
contentRequestNew product launch! #startup #launch
platforms[].platformRequestinstagram
platforms[].accountIdRequestig_456
mediaItems[].typeRequestimage
mediaItems[].urlRequesthttps://cdn.example.com/photo.jpg
publishNowRequesttrue for immediate publishing; omit or set false when scheduling
scheduledForRequestFuture date and time for scheduled Instagram posts
successResponsetrue
statusResponsepublished
postIdResponsepost_def456
platforms[].successResponsetrue
platforms[].platformPostUrlResponsehttps://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.

Feed Post Response Example
202
{
    "success": true,
    "status": "published",
    "postId": "post_def456",
    "platforms": [
      {
        "platform": "instagram",
        "success": true,
        "platformPostUrl": "https://www.instagram.com/p/ABC123/"
      }
    ]
}