Skip to content
Dashboard

List planned Instagram posts

GET
/instagram/posts
curl --request GET \
--url 'https://app.whatsetter.com/api/v1/instagram/posts?status=scheduled&limit=25' \
--header 'Authorization: Bearer <token>'

The posts planned on the workspace’s Instagram accounts, newest planned time first: scheduled (waiting for publish_at), publishing (sent to Instagram, being processed), reminded (mode remind: the person was reminded and the post is looked for on the account), published (with its permalink) and failed (with error_code, the reason in a word: aspect_ratio, video_format, quota, needs_reconnect, remind_missed…). Requires scope instagram:read.

account_id
string

One Instagram account of the workspace (all of them by default).

status
string
Allowed values: scheduled publishing reminded published failed
limit
integer
default: 25 >= 1 <= 100
cursor
string

Opaque cursor from the previous page’s pagination.next_cursor.

A page of planned posts

Media typeapplication/json
object
data
Array<object>
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
pagination
object
has_more
boolean
next_cursor
string | null
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"
}
}

Invalid parameter or body (also an invalid or expired cursor)

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