# Publish or schedule an Instagram post

`POST https://app.whatsetter.com/api/v1/instagram/posts`

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`.

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `account_id` | string | no | Required when the workspace has several Instagram accounts. |
| `kind` | image \| carousel \| reel \| story | no |  |
| `caption` | string | no | None on a story. |
| `media` | array | yes |  |
| `cover_url` | string | no | A reel's cover image (JPEG). |
| `thumb_offset_ms` | integer | no | A reel's cover as a frame of the video |
| `publish_at` | string | no |  |
| `automation` | object | no |  |
| `first_comment` | string | no | Posted by the account under its post right after it is live (the same limits as a caption). |
| `trial` | boolean | no | A reel only. A trial reel is shown first to non-followers. |
| `collaborators` | array | no | Instagram usernames invited as collaborators (photo |
| `user_tags` | array | no | People tagged. On a carousel, on its first photo. |
| `audio_name` | string | no | A reel only. Its original audio's name. |
| `share_to_feed` | boolean | no | A reel only. False shows it in Reels only |
| `comments_enabled` | boolean | no | False turns the comments off once the post is live. |
| `facebook` | boolean | no | Also publish it on the Facebook Page linked to the account (mode auto only). |
| `mode` | auto \| remind | no | auto: published by Whatsetter. remind: the person is reminded to publish it from the Instagram app, then it is found and linked. |
| `remind_member_id` | string | no | mode remind: the team member reminded (`GET /team/members`). Default: the member who created the API key. |

```json
{
  "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"
}
```

## Example request

```bash
curl --request POST \
  --url 'https://app.whatsetter.com/api/v1/instagram/posts' \
  --header 'Authorization: Bearer ws_live_…'
  --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"}'
```

## Responses

### 201: Planned

```json
{
  "data": {
    "id": "",
    "account_id": "",
    "account_username": "",
    "kind": "image",
    "caption": "",
    "media": [
      {
        "type": "image",
        "url": ""
      }
    ],
    "status": "scheduled",
    "publish_at": "",
    "published_at": "",
    "permalink": "",
    "instagram_media_id": "",
    "error_code": "",
    "automation": {
      "keyword": "",
      "message": ""
    },
    "first_comment": {
      "message": "",
      "status": "pending",
      "error_code": ""
    },
    "trial": false,
    "collaborators": [
      ""
    ],
    "user_tags": [
      {
        "username": "",
        "x": 0,
        "y": 0
      }
    ],
    "alt_texts": [
      ""
    ],
    "audio_name": "",
    "share_to_feed": false,
    "comments_enabled": false,
    "mode": "auto",
    "reminded_at": "",
    "facebook": {
      "status": "pending",
      "page_name": "",
      "permalink": "",
      "published_at": "",
      "error_code": ""
    },
    "source": "app",
    "created_at": ""
  }
}
```

### 401: Missing, unknown or revoked API key

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 403: 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)

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 404: Resource not found in this workspace

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 409: 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`).

```json
{
  "error": {
    "code": "too_many_planned",
    "message": "This Instagram account already has 50 posts waiting: publish or cancel some first."
  }
}
```

### 422: `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).

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

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


Source: https://docs.whatsetter.com/api-reference/operations/createinstagrampost/
