# Instagram (/docs/platforms/instagram)




What you can post [#what-you-can-post]

| Type       | Supported | Max media | Notes                                                              |
| ---------- | --------- | --------- | ------------------------------------------------------------------ |
| Feed image | ✅         | 1         | JPEG (PNG accepted, converted). Max 8 MB                           |
| Reels      | ✅         | 1         | MP4/MOV. Max 300 MB, 3s–15 min                                     |
| Story      | ✅         | 1         | Image or video. Disappears after 24h                               |
| Carousel   | ✅         | 10        | Mix of images and videos. Min 2 items. Videos up to 300 MB, 60 min |

<Callout title="Limitations" type="warn">
  * **Instagram requires a Business or Creator account.** Personal accounts cannot post via the API.
  * **2200 character caption limit.** Max 30 hashtags and 20 @mentions per caption. First 125 characters are visible before the "more" fold.
  * **100 API-published posts per 24-hour moving period.** Carousels count as 1 post.
  * **The first item in a carousel determines the aspect ratio** for the entire carousel, with a default of 1:1.
  * **GIF files are not supported.** Only JPEG images and MP4/MOV videos.
</Callout>

<Callout title="Content types" type="info">
  Instagram has four content types: **feed image**, **carousel**, **reels**, and **story**. You only need to set `contentType` for stories — everything else is auto-detected. Single videos are automatically published as Reels (Instagram no longer supports standalone video posts). Omit `contentType` for feed images and carousels.
</Callout>

Quick start [#quick-start]

Post an image [#post-an-image]

A regular feed post with a single image. Shows up in your profile grid.

<div className="fd-steps">
  <div className="fd-step">
    Get your media ready [#1-get-your-media-ready]

    <Tabs items="['Upload new media', 'Use existing media']">
      <Tab value="Upload new media">
        ```bash
        curl -X POST https://publishq.com/api/v1/media \
          -H "Authorization: Bearer pq_live_..." \
          -F "file=@photo.jpg"
        ```
      </Tab>

      <Tab value="Use existing media">
        ```bash
        curl https://publishq.com/api/v1/media \
          -H "Authorization: Bearer pq_live_..."
        ```

        Pick the `id` of the media you want to use from the response.
      </Tab>
    </Tabs>
  </div>

  <div className="fd-step">
    Create the post [#2-create-the-post]

    <Tabs items="['cURL']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://publishq.com/api/v1/posts \
          -H "Authorization: Bearer pq_live_..." \
          -H "Content-Type: application/json" \
          -d '{
            "content": "Golden hour 🌅",
            "mediaIds": ["media-id-from-step-1"],
            "accounts": [
              { "accountId": "your-instagram-account-id" }
            ],
            "publishNow": true
          }'
        ```
      </Tab>
    </Tabs>
  </div>
</div>

Post a reel [#post-a-reel]

A short-form video (3s–15 min) that appears in the Reels tab and optionally in your feed. Single videos are automatically detected and published as Reels by PublishQ — you can set `contentType: "reels"` explicitly, but it's optional.

<div className="fd-steps">
  <div className="fd-step">
    Get your media ready [#1-get-your-media-ready-1]

    <Tabs items="['Upload new media', 'Use existing media']">
      <Tab value="Upload new media">
        ```bash
        curl -X POST https://publishq.com/api/v1/media \
          -H "Authorization: Bearer pq_live_..." \
          -F "file=@reel.mp4"
        ```
      </Tab>

      <Tab value="Use existing media">
        ```bash
        curl https://publishq.com/api/v1/media \
          -H "Authorization: Bearer pq_live_..."
        ```

        Pick the `id` of the video you want to use from the response.
      </Tab>
    </Tabs>
  </div>

  <div className="fd-step">
    Create the post [#2-create-the-post-1]

    <Tabs items="['cURL']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://publishq.com/api/v1/posts \
          -H "Authorization: Bearer pq_live_..." \
          -H "Content-Type: application/json" \
          -d '{
            "content": "Behind the scenes 🎬",
            "mediaIds": ["video-id-from-step-1"],
            "thumbnailTimestamp": 3000,
            "accounts": [
              {
                "accountId": "your-instagram-account-id",
                "platformSpecificSettings": {
                  "shareToFeed": true,
                  "audioName": "Original Sound"
                }
              }
            ],
            "publishNow": true
          }'
        ```
      </Tab>
    </Tabs>
  </div>
</div>

Post a carousel [#post-a-carousel]

A swipeable post with 2–10 images, videos, or a mix of both. The first item determines the aspect ratio for the entire carousel (default 1:1).

<div className="fd-steps">
  <div className="fd-step">
    Get your media ready [#1-get-your-media-ready-2]

    <Tabs items="['Upload new media', 'Use existing media']">
      <Tab value="Upload new media">
        ```bash
        curl -X POST https://publishq.com/api/v1/media \
          -H "Authorization: Bearer pq_live_..." \
          -F "file=@photo1.jpg"
        ```

        Repeat for each file. You need at least 2 media IDs.
      </Tab>

      <Tab value="Use existing media">
        ```bash
        curl https://publishq.com/api/v1/media \
          -H "Authorization: Bearer pq_live_..."
        ```

        Pick the `id` of each media item you want to use from the response.
      </Tab>
    </Tabs>
  </div>

  <div className="fd-step">
    Create the post [#2-create-the-post-2]

    <Tabs items="['cURL']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://publishq.com/api/v1/posts \
          -H "Authorization: Bearer pq_live_..." \
          -H "Content-Type: application/json" \
          -d '{
            "content": "Weekend highlights 📸",
            "mediaIds": ["media-id-1", "media-id-2", "media-id-3"],
            "accounts": [
              { "accountId": "your-instagram-account-id" }
            ],
            "publishNow": true
          }'
        ```
      </Tab>
    </Tabs>
  </div>
</div>

Post a story [#post-a-story]

Set `contentType: "story"` to publish to Stories. Stories disappear after 24 hours. Text captions are not displayed on stories. Supports a single image or video.

<div className="fd-steps">
  <div className="fd-step">
    Get your media ready [#1-get-your-media-ready-3]

    <Tabs items="['Upload new media', 'Use existing media']">
      <Tab value="Upload new media">
        ```bash
        curl -X POST https://publishq.com/api/v1/media \
          -H "Authorization: Bearer pq_live_..." \
          -F "file=@story.jpg"
        ```
      </Tab>

      <Tab value="Use existing media">
        ```bash
        curl https://publishq.com/api/v1/media \
          -H "Authorization: Bearer pq_live_..."
        ```

        Pick the `id` of the media you want to use from the response.
      </Tab>
    </Tabs>
  </div>

  <div className="fd-step">
    Create the post [#2-create-the-post-3]

    <Tabs items="['cURL']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://publishq.com/api/v1/posts \
          -H "Authorization: Bearer pq_live_..." \
          -H "Content-Type: application/json" \
          -d '{
            "mediaIds": ["media-id-from-step-1"],
            "accounts": [
              {
                "accountId": "your-instagram-account-id",
                "platformSpecificSettings": {
                  "contentType": "story"
                }
              }
            ],
            "publishNow": true
          }'
        ```
      </Tab>
    </Tabs>
  </div>
</div>

Platform-specific settings [#platform-specific-settings]

Pass these inside `platformSpecificSettings` on the Instagram account entry. All fields are optional — omit the entire object for a regular feed post or carousel.

{/* Fields auto-generated from InstagramPlatformSpecificSettingsSchema */}

<PlatformSettingsTable platform="INSTAGRAM" />

<small>
  Full schema: 

  [InstagramPlatformSpecificSettings](/docs-scalar#model/InstagramPlatformSpecificSettings)
</small>

Trial reels example [#trial-reels-example]

Trial reels are shown only to non-followers first. If the reel performs well, Instagram can automatically promote it to your followers.

```json
{
  "content": "Testing this new format",
  "mediaIds": ["video-media-id"],
  "thumbnailTimestamp": 5000,
  "accounts": [
    {
      "accountId": "instagram-account-id",
      "platformSpecificSettings": {
        "shareToFeed": true,
        "audioName": "Original Sound",
        "trialParams": {
          "graduationStrategy": "SS_PERFORMANCE"
        }
      }
    }
  ],
  "publishNow": true
}
```

Media specs [#media-specs]

Images [#images]

| Spec          | Feed / Carousel                | Story            |
| ------------- | ------------------------------ | ---------------- |
| Formats       | JPEG (PNG accepted, converted) | JPEG             |
| Max file size | 8 MB                           | 8 MB             |
| Aspect ratio  | 4:5 to 1.91:1                  | 9:16 recommended |
| Min width     | 320px (upscaled)               | 320px            |
| Max width     | 1440px (downscaled)            | 1440px           |

Videos [#videos]

| Spec           | Reels                             | Feed / Carousel        | Story                            |
| -------------- | --------------------------------- | ---------------------- | -------------------------------- |
| Formats        | MP4, MOV                          | MP4, MOV               | MP4, MOV                         |
| Max file size  | 300 MB                            | 300 MB                 | 100 MB                           |
| Duration       | 3s – 15 min                       | 3s – 60 min            | 3s – 60s                         |
| Frame rate     | 23–60 FPS                         | 23–60 FPS              | 23–60 FPS                        |
| Max resolution | 1920px wide                       | 1920px wide            | 1920px wide                      |
| Aspect ratio   | 0.01:1 to 10:1 (9:16 recommended) | 4:5 to 1.91:1          | 0.1:1 to 10:1 (9:16 recommended) |
| Video codec    | H.264 or HEVC                     | H.264 or HEVC          | H.264 or HEVC                    |
| Audio codec    | AAC, max 48kHz, stereo            | AAC, max 48kHz, stereo | AAC, max 48kHz, stereo           |

Not yet supported [#not-yet-supported]

* **GIF attachments** — Instagram does not accept GIF files through the API.
* **Location tagging**
* **Stickers on stories** — Link, poll, and location stickers are not supported by the Instagram API.
* **First comment** (coming soon)
* **User tagging** — @mentioning users at specific coordinates in images/stories. (Comsing soon)
* **Cover image for reels** — Custom cover photo via `cover_url`. (Coming soon)