Skip to content
Dashboard

Change a planned Instagram post

PATCH
/instagram/posts/{id}
curl --request PATCH \
--url https://app.whatsetter.com/api/v1/instagram/posts/example \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "publish_at": "2027-01-13T18:00:00Z" }'

Changes the caption, the time (publish_at, an instant; null = now), the first comment (null removes it), the comment automation (null removes it), the trial setting, the options (collaborators, user_tags, audio_name, share_to_feed, comments_enabled; each one sent replaces its value), facebook or mode of a post still waiting for its time. Its media (and their alt texts) stay. A post already on its way to Instagram answers 409 post_already_started, one already published 409 post_already_published; a time already past is refused (422). publish_at: null publishes it within a minute and facebook: true adds a public post on the Page. Switching to mode: remind (or sending remind_member_id) names the member reminded, as on create. Requires scope instagram:write.

id
required
string

A planned post (from listInstagramPosts or createInstagramPost).

Media typeapplication/json
object
caption
string
<= 2200 characters
publish_at
string format: date-time
nullable
first_comment
string
nullable <= 2200 characters
automation
object
keyword
string
<= 40 characters
message
string
<= 1000 characters
trial
boolean
collaborators
Array<string>
<= 3 items
user_tags
Array<object>
<= 20 items
object
username
required
string
x
number
<= 1
y
number
<= 1
audio_name
string
<= 100 characters
share_to_feed
boolean
comments_enabled
boolean
facebook
boolean
mode
string
Allowed values: auto remind
remind_member_id

Mode remind: the team member reminded (GET /team/members).

string
Example
{
"publish_at": "2027-01-13T18:00:00Z"
}

Changed

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 post is already on its way to Instagram (post_already_started) or already published (post_already_published); or, switched back to mode: auto, the account must be reconnected to publish (instagram_reconnect_required); or the Facebook Page is missing or does not allow publishing (facebook_page_required, facebook_reconnect_required, facebook_permission_required).

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

validation_error, 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"
}
}

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

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