Publish or schedule an Instagram post
const url = 'https://app.whatsetter.com/api/v1/instagram/posts';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"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"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
Required when the workspace has several Instagram accounts.
None on a story.
object
A photo’s alternative text (not a video
A reel’s cover image (JPEG).
A reel’s cover as a frame of the video
object
Posted by the account under its post right after it is live (the same limits as a caption).
A reel only. A trial reel is shown first to non-followers.
Instagram usernames invited as collaborators (photo
People tagged. On a carousel, on its first photo.
object
A reel only. Its original audio’s name.
A reel only. False shows it in Reels only
False turns the comments off once the post is live.
Also publish it on the Facebook Page linked to the account (mode auto only).
Auto: published by Whatsetter. remind: the person is reminded to publish it from the Instagram app, then it is found and linked.
Mode remind: the team member reminded (GET /team/members). Default: the member who created the API key.
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"}Responses
Section titled “Responses”Planned
object
object
object
The URL given through the API; null for a file uploaded from the dashboard.
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
Posted one step after the post is live; a failure never takes the post back.
object
Comment_needs_reconnect, account_restricted, comment_refused, comment_gave_up, comment_no_media
A trial reel (shown first to non-followers).
object
Each media’s alternative text
False when the comments are turned off once it is live.
When the person was reminded (mode remind).
The copy on the linked Facebook Page; its outcome never touches the Instagram post’s.
object
Fb_permission, fb_reconnect, fb_reel_limit, fb_reel_duration, fb_reel_ratio, fb_photo_refused, fb_carousel_video, fb_processing_timeout, fb_unconfirmed…
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
object
object
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)
object
object
Examplegenerated
{ "error": { "code": "example", "message": "example" }}Resource not found in this workspace
object
object
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).
object
object
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).
object
object
Examplegenerated
{ "error": { "code": "example", "message": "example" }}Publishing (or facebook, or the remind mode) is not available on this workspace yet (instagram_publishing_unavailable).