Instagram API

Postproxy publishes feed posts, Reels, and Stories to an Instagram professional (Business or Creator) account, and lets you read and reply to comments and read and send direct messages — including private replies to commenters and inbound story mentions.

Every request below uses the base URL https://api.postproxy.dev and an Authorization: Bearer YOUR_API_KEY header. Replace YOUR_API_KEY and the example IDs with your own.

At a glance


Platform ID	`instagram`
Formats	`post` (default), `reel`, `story`
Character limit	2,200 (Stories have no caption)
Media	Required on every format
Placements	None — posts go to the connected account
Comments	List, reply, delete, hide/unhide
Direct messages	Yes — text, media, reactions, private replies
Post chains	No

Publishing

Formats

Format	Description
`post`	Feed post — single image, video, or carousel (default)
`reel`	Instagram Reel
`story`	Instagram Story

Feed post

Parameter	Type	Required	Description
`format`	string	No	`"post"` (default)
`first_comment`	string	No	Comment added after publishing (max 2,196 characters)
`collaborators`	array	No	Collaborator usernames to invite

Media	Max size	Formats	Count	Duration
Image	8 MB	jpg, png	10	—
Video	300 MB	mp4, mov	1	3 s – 60 min

Media is required. Text caption is optional.
Images and a video can be mixed in a carousel.
Minimum image dimensions: 200×200 px.

# Feed carousel with a first comment and collaborators
curl -X POST "https://api.postproxy.dev/api/posts" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post": { "body": "Three takeaways from our launch week 👇" },
       "profiles": ["prof_abc123"],
       "media": [
         "https://example.com/slide1.jpg",
         "https://example.com/slide2.jpg",
         "https://example.com/slide3.jpg"
       ],
       "platforms": {
         "instagram": {
           "format": "post",
           "first_comment": "Follow for more content!",
           "collaborators": ["partnerhandle"]
         }
       }
     }'

Reel

Parameter	Type	Required	Description
`format`	string	Yes	`"reel"`
`first_comment`	string	No	Comment added after publishing (max 2,196 characters)
`cover_url` / `cover_file`	string / file	No	Cover image. Pass `cover_url` (URL) in JSON or `cover_file` (file) in multipart
`audio_name`	string	No	Name of the audio track
`trial_strategy`	string	No	Trial-reel strategy: `"MANUAL"` or `"SS_PERFORMANCE"`
`collaborators`	array	No	Up to 3 collaborator usernames
`thumb_offset`	string	No	Thumbnail offset in milliseconds. Ignored if `cover_url` is set

Media	Max size	Formats	Count	Duration
Video	300 MB	mp4, mov	1	3 s – 90 min

A video is required; images are not accepted on Reels.

# Reel with a cover image and audio name
curl -X POST "https://api.postproxy.dev/api/posts" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post": { "body": "New reel is live! Full tutorial on our channel 🎬" },
       "profiles": ["prof_abc123"],
       "media": ["https://example.com/video.mp4"],
       "platforms": {
         "instagram": {
           "format": "reel",
           "first_comment": "Full tutorial link in bio!",
           "cover_url": "https://example.com/thumbnail.jpg",
           "audio_name": "Trending Audio Track"
         }
       }
     }'

Story

Parameter	Type	Required	Description
`format`	string	Yes	`"story"`

Media	Max size	Formats	Count	Duration
Image	8 MB	jpg, png	1	—
Video	100 MB	mp4, mov	1	1 s – 60 min

Media is required; text captions are not supported.
Minimum dimensions: 200×200 px.

# Story (single image)
curl -X POST "https://api.postproxy.dev/api/posts" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post": {},
       "profiles": ["prof_abc123"],
       "media": ["https://example.com/story.jpg"],
       "platforms": { "instagram": { "format": "story" } }
     }'

Rate limits

100 posts per day per user, on a rolling 24-hour window, across all Instagram formats.
Instagram may also throttle bursts with User is performing too many actions. Slow down and retry later when you hit it.

Comments

Instagram comments are managed through the Comments API. All comment writes are asynchronous. Every call needs the profile_id query parameter.

Action	Supported
List / read	Yes
Reply	Yes
Delete	Yes
Hide / unhide	Yes
Like / unlike	No

Comments are text-only — the attachments array is always empty.
Author metadata is available when Instagram returns it: is_verified_user, is_user_follow_business, is_business_follow_user, and follower_count.
A comment.created webhook fires when a new comment is synced.

# List comments on a post
curl "https://api.postproxy.dev/api/posts/post_abc123/comments?profile_id=prof_abc123" \
     -H "Authorization: Bearer YOUR_API_KEY"

# Reply to a comment (omit parent_id to comment on the post itself)
curl -X POST "https://api.postproxy.dev/api/posts/post_abc123/comments?profile_id=prof_abc123" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "body": "Thanks for the kind words!", "parent_id": "cmt_abc123" }'

# Hide / unhide a comment
curl -X POST "https://api.postproxy.dev/api/posts/post_abc123/comments/cmt_abc123/hide?profile_id=prof_abc123" \
     -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST "https://api.postproxy.dev/api/posts/post_abc123/comments/cmt_abc123/unhide?profile_id=prof_abc123" \
     -H "Authorization: Bearer YOUR_API_KEY"

# Delete a comment
curl -X DELETE "https://api.postproxy.dev/api/posts/post_abc123/comments/cmt_abc123?profile_id=prof_abc123" \
     -H "Authorization: Bearer YOUR_API_KEY"

Direct messages

Instagram Direct is supported through the Direct Messages API. Outbound sends are asynchronous and accept either text or a single attachment per send.

Capability	Supported
Send / receive text	Yes
Attachments	Yes — one per send
Reactions	Yes — Instagram accepts `love` (an `emoji` may accompany it)
Edit outbound message	No
Delivery / read receipts	Yes
Private reply to a comment	Yes
Inbound delivery	Webhook

24-hour window. Free-form messages are only allowed within 24 hours of the participant’s last message. Sending outside the window is not supported.
Private replies DM a commenter directly, bypass the 24-hour window (up to 7 days after the comment), and are allowed once per comment.
Story mentions arrive as inbound messages with a story_mention attachment, mirrored to durable storage. Story replies populate story_reply on the message.
Start a chat with the participant’s Instagram-scoped user ID as participant_external_id.

# List chats for the profile
curl "https://api.postproxy.dev/api/profiles/prof_abc123/chats" \
     -H "Authorization: Bearer YOUR_API_KEY"

# Create or find a chat by participant ID (idempotent)
curl -X POST "https://api.postproxy.dev/api/profiles/prof_abc123/chats" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "participant_external_id": "17841400000000000", "participant_username": "janedoe" }'

# Send a text message
curl -X POST "https://api.postproxy.dev/api/chats/chat_abc123/messages" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "body": "Hi! Thanks for reaching out 👋" }'

# Send a single media attachment
curl -X POST "https://api.postproxy.dev/api/chats/chat_abc123/messages" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "media": ["https://example.com/catalog.jpg"] }'

# React to a message (Instagram accepts "love")
curl -X POST "https://api.postproxy.dev/api/messages/msg_abc123/react" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "reaction": "love" }'

# Private reply to a commenter (bypasses the 24h window, once per comment)
curl -X POST "https://api.postproxy.dev/api/posts/post_abc123/comments/cmt_abc123/private_reply?profile_id=prof_abc123" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "text": "Just sent you a DM with the details!" }'

Webhooks

Subscribe with the Webhooks API. Create a subscription:

curl -X POST "https://api.postproxy.dev/api/webhooks" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://example.com/webhooks/postproxy",
       "events": ["platform_post.published", "comment.created", "message.received"]
     }'

Events relevant to Instagram:

Event	When
`post.processed`	A post is ready to publish
`platform_post.published`	A post was published to the platform
`platform_post.failed`	A post failed to publish (retries exhausted)
`platform_post.failed_waiting_for_retry`	A publish attempt failed; will retry
`platform_post.insights`	New analytics snapshot
`comment.created`	A comment was synced on an Instagram post
`message.received` / `.sent`	Inbound / outbound DM
`message.delivered` / `.read`	Delivery and read receipts
`message.deleted`	A message was unsent (Instagram is the only network that reports this)
`message.edited`	An inbound message was edited
`reaction.received`	A reaction was added or removed on a message
`profile.connected` / `.disconnected`	Connection state changed
`profile.stats`	New profile stats snapshot
`media.failed`	A media attachment failed to process

Notes

Only professional (Business or Creator) Instagram accounts can publish via the API.
Carousels may combine images and a video; Reels and Stories are single-media.
Trial Reels (trial_strategy) publish to non-followers first; use MANUAL or SS_PERFORMANCE.