Instagram API: Posting Reference
Instagram is supported via the Instagram Graph API. Connected accounts must be Instagram Business or Creator accounts linked to a Facebook Page. Personal Instagram accounts are not supported by Meta's API and cannot be connected.
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) |
| Reel | ✅ | Requires a vertical video |
Minimal example
Code
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 | Reel only. from-video or from-library. |
instagram.thumb_offset | number | Reel only. Timestamp in milliseconds, used when thumbnail_type is from-video. |
instagram.cover_url | string | Reel only. 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. |
Media requirements
| Media | Requirement |
|---|---|
| Feed image | JPEG or PNG, 320 to 1440 px wide, aspect ratio between 9:16 (portrait) and 1.91:1 (landscape) |
| 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, max 300 MB |
| Reel video | MP4, vertical 9:16, up to 15 minutes, max 300 MB |
| Carousel | 2 to 10 items, all images or all videos |
Content that violates aspect ratio or duration is rejected at publish time with a 400 error referencing the Instagram Graph API response.
Limitations
- Personal (non-business) Instagram accounts cannot be connected
- Tagging users in media requires each tagged user to be a public account
- Instagram does not allow scheduling posts further than 75 days in advance
Testing
In test mode (omsk_test_* keys), Instagram posts are validated but never sent to Meta. The response shape matches production so your integration can be built and tested without risking real posts.