Skip to content
Dashboard

Publish or schedule an Instagram post

POST
/instagram/posts
curl --request POST \
--url https://app.whatsetter.com/api/v1/instagram/posts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "kind": "image", "caption": "New listing in Lyon. Comment GUIDE for the buyer'\''s guide.", "media": [ { "type": "image", "url": "https://cdn.example.com/listing.jpg" } ], "publish_at": "2027-01-12T17:00:00Z", "automation": { "keyword": "GUIDE", "message": "Here is the guide 👇" }, "first_comment": "#lyon #realestate #buyersguide" }'

Plans a photo, a carousel (2 to 20 items), a reel or a story, now (publish_at absent or null) or at publish_at. Media are public https URLs Instagram downloads when the post goes out: JPEG photos (4:5 to 1.91:1, 8 MB), MP4 or MOV videos (3 s to 15 min, 300 MB). A story is one photo or one video of 3 to 60 s (100 MB), takes no caption, no automation and no first comment, and stays 24 h. The caption follows Instagram’s limits (2,200 characters, 30 hashtags, 20 mentions). With automation, a comment automation is created on the post as soon as it is live. With first_comment, the account comments under its post one step after it is live (if the comment fails, the post stays published: its first_comment.status says failed with an error_code). With trial: true, a reel is a trial reel: shown first to people who do not follow the account, then shared to the followers by Instagram if it performs well. collaborators (up to 3 usernames: photo, carousel, reel), user_tags (people tagged: x and y from 0 to 1 on a photo, the centre when absent; no place on a reel; optional on a story), media[].alt_text (a photo’s alternative text, 1,000 characters), audio_name (a reel’s original audio, renamed once), share_to_feed (a reel on the profile grid too, default true) and comments_enabled: false (comments turned off once it is live; not with an automation or a first comment) are Instagram’s own options. The account must have been reconnected to allow publishing (409 instagram_reconnect_required otherwise). Instagram allows 50 published posts per account per 24 h: past it, the post waits. With facebook: true, the same post also goes to the Facebook Page linked to the account, at the same time, through the Pages API (a photo, a carousel of photos, a reel of 3 to 90 s, a story); its outcome is its own, in facebook, and never fails the Instagram post. The Page must allow publishing (409 facebook_permission_required, facebook_page_required, facebook_reconnect_required); Facebook allows 30 reels published through the API per Page per 24 h: past it, the copy waits. With mode: remind, nothing is published: at publish_at the person who planned it is reminded (e-mail and the dashboard) to publish it from the Instagram app (so « Share to Facebook » keeps the app’s combined counter), the post reads reminded, then it is found on the account (kind, caption, time) and linked: published, its automation and first comment as usual; failed with remind_missed after 48 h. No publish permission is needed in that mode, and facebook and trial are ignored. The person reminded is a member of the workspace who sees Instagram: remind_member_id (GET /team/members), else the member who created the API key; nobody is 422 no_reminder_recipient. An account holds 50 posts waiting (planned or reminded) at most through the API: past it, 409 too_many_planned. Requires scope instagram:write.

Media typeapplication/json
object
account_id

Required when the workspace has several Instagram accounts.

string
kind
string
default: image
Allowed values: image carousel reel story
caption

None on a story.

string
<= 2200 characters
media
required
Array<object>
>= 1 items <= 20 items
object
type
string
default: image
Allowed values: image video
url
required
string format: uri
alt_text

A photo’s alternative text (not a video

string
<= 1000 characters
cover_url

A reel’s cover image (JPEG).

string format: uri
thumb_offset_ms

A reel’s cover as a frame of the video

integer
publish_at
string format: date-time
nullable
automation
object
keyword
string
<= 40 characters
message
string
<= 1000 characters
first_comment

Posted by the account under its post right after it is live (the same limits as a caption).

string
<= 2200 characters
trial

A reel only. A trial reel is shown first to non-followers.

boolean
collaborators

Instagram usernames invited as collaborators (photo

Array<string>
<= 3 items
user_tags

People tagged. On a carousel, on its first photo.

Array<object>
<= 20 items
object
username
required
string
x
number
<= 1
y
number
<= 1
audio_name

A reel only. Its original audio’s name.

string
<= 100 characters
share_to_feed

A reel only. False shows it in Reels only

boolean
default: true
comments_enabled

False turns the comments off once the post is live.

boolean
default: true
facebook

Also publish it on the Facebook Page linked to the account (mode auto only).

boolean
mode

Auto: published by Whatsetter. remind: the person is reminded to publish it from the Instagram app, then it is found and linked.

string
default: auto
Allowed values: auto remind
remind_member_id

Mode remind: the team member reminded (GET /team/members). Default: the member who created the API key.

string
Example
{
"kind": "image",
"caption": "New listing in Lyon. Comment GUIDE for the buyer's guide.",
"media": [
{
"type": "image",
"url": "https://cdn.example.com/listing.jpg"
}
],
"publish_at": "2027-01-12T17:00:00Z",
"automation": {
"keyword": "GUIDE",
"message": "Here is the guide 👇"
},
"first_comment": "#lyon #realestate #buyersguide"
}

Planned

Media typeapplication/json
object
data
object
id
string
account_id
string
nullable
account_username
string
nullable
kind
string
Allowed values: image carousel reel story
caption
string
media
Array<object>
object
type
string
Allowed values: image video
url

The URL given through the API; null for a file uploaded from the dashboard.

string
nullable
status
string
Allowed values: scheduled publishing reminded published failed
publish_at
string format: date-time
published_at
string format: date-time
nullable
permalink
string
nullable
instagram_media_id
string
nullable
error_code
string
nullable
automation

The comment automation made on the post once it is live. A post planned in the dashboard may carry a whole automation built in its editor (link, follow ask, who continues…): it is summed up here as its first word (empty when it answers every comment) and its private message. Sending automation replaces it with this simple shape.

object
keyword
string
message
string
first_comment

Posted one step after the post is live; a failure never takes the post back.

object
message
string
status
string
Allowed values: pending posted failed
error_code

Comment_needs_reconnect, account_restricted, comment_refused, comment_gave_up, comment_no_media

string
nullable
trial

A trial reel (shown first to non-followers).

boolean
collaborators
Array<string>
user_tags
Array<object>
object
username
string
x
number
y
number
alt_texts

Each media’s alternative text

Array<string>
audio_name
string
nullable
share_to_feed
boolean
comments_enabled

False when the comments are turned off once it is live.

boolean
mode
string
Allowed values: auto remind
reminded_at

When the person was reminded (mode remind).

string format: date-time
nullable
facebook

The copy on the linked Facebook Page; its outcome never touches the Instagram post’s.

object
status
string
Allowed values: pending publishing published failed cancelled
page_name
string
permalink
string
nullable
published_at
string format: date-time
nullable
error_code

Fb_permission, fb_reconnect, fb_reel_limit, fb_reel_duration, fb_reel_ratio, fb_photo_refused, fb_carousel_video, fb_processing_timeout, fb_unconfirmed…

string
nullable
source
string
Allowed values: app api
created_at
string format: date-time
nullable
Example
{
"data": {
"kind": "image",
"media": [
{
"type": "image"
}
],
"status": "scheduled",
"first_comment": {
"status": "pending"
},
"mode": "auto",
"facebook": {
"status": "pending"
},
"source": "app"
}
}

Missing, unknown or revoked API key

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

The key lacks the required scope (insufficient_scope), the plan does not have this part of the API (not_in_plan), or Instagram is not enabled on the workspace (instagram_not_enabled, Instagram routes)

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

Resource not found in this workspace

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

The account must be reconnected from the dashboard to allow publishing (instagram_reconnect_required), the Facebook Page is missing or does not allow publishing (facebook_page_required, facebook_reconnect_required, facebook_permission_required), or the account already has 50 posts waiting (too_many_planned).

Media typeapplication/json
object
error
object
code
string
message
string
Example
{
"error": {
"code": "too_many_planned",
"message": "This Instagram account already has 50 posts waiting: publish or cancel some first."
}
}

validation_error (the problems are listed in the message), invalid_media_url (a media URL that is not public https, or a file Instagram does not take) or no_reminder_recipient (mode remind and nobody of the workspace to remind).

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

Publishing (or facebook, or the remind mode) is not available on this workspace yet (instagram_publishing_unavailable).