Instagram API: posting reference
Instagram is supported via the Instagram API with Instagram Login. Connected accounts must be Instagram Business or Creator accounts; no Facebook Page is needed to publish. Personal Instagram accounts are not supported by Meta's API and cannot be connected.
For an overview and use cases, see Instagram API.
Channel ID: instagram
Supported content types
| Type | Supported | Notes |
|---|---|---|
| Feed post | ✅ | Single image, video, or carousel (up to 10 items) |
| Story | ✅ | Requires media (image or video). No caption is sent. Up to 10 slides per post, each published as its own story in order |
| Reel | ✅ | Requires a vertical video |
Minimal example
Terminal
Instagram posts always require media. A post with no media returns 400.
Instagram options
Set these under the instagram key on the post body:
| Field | Type | Description |
|---|---|---|
instagram.first_comment | string | Text auto-posted as the first comment right after the post publishes (max 2200 characters). Common for keeping hashtags out of the caption. Works on feed posts and reels; not posted for stories. |
instagram.share_to_feed | boolean | Reel only. Also display the reel on the profile grid. |
instagram.thumbnail_type | string | Video thumbnail (reels and single-video feed posts): from-video or from-library. The top-level video_cover does the same for every platform at once. |
instagram.thumb_offset | number | Timestamp in milliseconds, used when thumbnail_type is from-video. |
instagram.cover_url | string | URL of a custom cover image, used when thumbnail_type is from-library. |
Instagram-only post options
These are set as top-level fields on the post body (not under the instagram key) and are ignored by other platforms:
| Field | Type | Description |
|---|---|---|
location_id | string | Facebook Place/Page ID to tag the post's location. Single-image and carousel feed posts only. Find a Place ID with GET /locations/search. |
collaborators | array of strings | Up to 3 public Instagram usernames invited as co-authors (the "Collab" feature). Image, carousel, and reel posts; not stories. |
user_tags | array | Tag public accounts at positions on a photo: [{"username": "name", "x": 0.5, "y": 0.8, "image_index": 0}]. x/y are 0–1 from the top-left. Photos only, not video, reels, or stories. |
A fourth top-level field, media_fit, is not Instagram-only: it is keyed by channel ({ "instagram": "crop" | "keep" }) and decides what happens to a feed image outside 4:5 to 1.91:1. See Image fit per channel.
Media requirements
| Media | Requirement |
|---|---|
| Feed image | JPEG, PNG, or WebP, max 8 MB, 320 to 1440 px wide, aspect ratio between 9:16 (portrait) and 1.91:1 (landscape). Instagram shows feed images between 4:5 and 1.91:1 and cuts anything taller to 4:5 itself, so outside 4:5 to 1.91:1 OmniSocials crops the image to 4:5 (tall) or 1.91:1 (wide) around the subject by default and reports it in the response warnings; pass media_fit: { "instagram": "keep" } to send the original. See Image fit per channel |
| Feed video | MP4 or MOV, up to 15 minutes, max 300 MB |
| Story image | JPEG or PNG, aspect ratio 9:16 recommended |
| Story video | MP4, up to 60 seconds per slide, max 300 MB |
| Reel video | MP4, vertical 9:16, up to 15 minutes, max 300 MB |
| Carousel | 2 to 10 items; images and videos can be mixed in one carousel |
Content that violates aspect ratio or duration is rejected at publish time with a 400 error referencing the Instagram Graph API response.
Alt text
Pass an accessibility description per media item by using an object entry instead of a bare string (works in media_urls and media_ids). It is sent as Instagram's alt_text on image posts and on each image slide of a carousel; every slide carries its own description. Reels and Stories don't support alt text (an Instagram limitation), and Instagram caps descriptions at 1,000 characters, so longer values are clamped at publish time:
JSON
The same alt also delivers to Mastodon, Bluesky, X, Pinterest, and LinkedIn (images), so one description covers a cross-platform post.
Character and hashtag limits
Captions cap at 2,200 characters. Instagram also rejects any caption or comment carrying more than 5 hashtags ("Too many hashtags"). OmniSocials checks the cap when a hashtag set is applied to the post. A caption or first_comment you write yourself is sent as it is, so keep it at 5 hashtags or fewer.
Comment-to-DM automations
An Instagram post can send a DM to everyone who comments a keyword on it, once per person, with an optional public reply under the comment. The same automation can also listen to a keyword in a DM or a story reply. Instagram allows one private reply per comment, within 7 days of the comment, and OmniSocials sends at most 180 DMs an hour per account. Attach one at create time with comment_dm_automation, or manage them with the Automations endpoints.
Limitations
- Personal (non-business) Instagram accounts cannot be connected
- Tagging users in media requires each tagged user to be a public account
- Stories carry no caption; text has to be part of the image or video