> ## Documentation Index > Fetch the complete documentation index at: https://kavenio.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Instagram Publishing API Documentation | Kavenio Docs > Publish Instagram feed posts, carousels, Stories, and Reels with Kavenio. Review account setup, request payloads, media limits, scheduling, and errors. Kavenio publishes Instagram content through connected Instagram Business or Creator accounts. Use `instagram` as the platform value and put Instagram-specific fields in `platformSpecificData`. Instagram publishing uses Meta media containers. Kavenio creates the container, waits for provider processing, publishes it, and then creates optional first comments for supported content types. First comments require the `instagram_business_manage_comments` permission. ## Quick Reference | Capability | Support | | --------------------- | -------------------------------------------------------------------- | | Platform key | `instagram` | | Feed post | One image, one video, or 2-10 image/video carousel | | Reel | One video with `contentType: "reels"` | | Story | One image or one video, no caption | | First comment | Feed, carousel, and Reels; requires comment-management permission | | Collaborators | Feed, carousel, and Reels | | User tags | Image feed posts and image carousel items | | Post analytics | `GET /v1/analytics` for views, reach, likes, comments, saves, shares | | Native edit/unpublish | Not supported | ## Create A Feed Post ```json theme={null} { "content": "Launch photo caption.", "mediaItems": [ { "type": "image", "url": "https://cdn.example.com/instagram-launch.jpg", "mimeType": "image/jpeg" } ], "platforms": [ { "platform": "instagram", "accountId": "acc_123", "platformSpecificData": { "contentType": "feed", "firstComment": "Full launch notes: https://example.com/launch", "collaborators": ["partner_brand"], "userTags": [ { "username": "partner_brand", "x": 0.5, "y": 0.5 } ] } } ], "publishNow": true } ``` ```bash theme={null} kavenio posts create \ --content "Launch photo caption." \ --publish-now \ --media-url https://cdn.example.com/instagram-launch.jpg \ --platform instagram:acc_123 \ --content-type feed \ --first-comment "Full launch notes: https://example.com/launch" ``` `contentType` defaults to `feed`, so you can omit it for normal feed posts. First comments require `instagram_business_manage_comments` for direct Instagram Login connections. Older Facebook-linked connections require `instagram_manage_comments` and `pages_read_engagement`. Kavenio checks the stored scopes before creating the main media container. ## Create A Reel Use `contentType: "reels"` for Instagram Reels. ```json theme={null} { "content": "Reel caption.", "mediaItems": [ { "type": "video", "url": "https://cdn.example.com/reel.mp4", "mimeType": "video/mp4", "thumbnail": "https://cdn.example.com/reel-cover.jpg" } ], "platforms": [ { "platform": "instagram", "accountId": "acc_123", "platformSpecificData": { "contentType": "reels", "shareToFeed": true, "thumbOffset": 1000, "firstComment": "Pinned Reel follow-up", "collaborators": ["partner_brand"], "trialParams": { "graduationStrategy": "MANUAL" }, "audioName": "Original audio" } } ], "publishNow": true } ``` `instagramThumbnail` overrides the media item's `thumbnail` when both are present. ## Create A Story Use `contentType: "story"` for Stories. ```json theme={null} { "content": "", "mediaItems": [ { "type": "image", "url": "https://cdn.example.com/story.jpg", "mimeType": "image/jpeg" } ], "platforms": [ { "platform": "instagram", "accountId": "acc_123", "platformSpecificData": { "contentType": "story" } } ], "publishNow": true } ``` Stories require exactly one image or video. Instagram Story publishing does not support captions, first comments, collaborators, user tags, Reel options, or advanced Story options in v1. Stories require an Instagram Business account. ## First Comments And Permissions Kavenio creates `platformSpecificData.firstComment` after the feed post, carousel, or Reel publishes. Instagram connections request `instagram_business_manage_comments` in addition to the basic and content publishing permissions. Accounts connected before the comment-management permission was added must reconnect before publishing a first comment. Kavenio rejects a first-comment request before uploading media when a stored credential is known to lack that permission. If Instagram accepts the media publish and then rejects the comment, the target failure details preserve the published media ID and provider response so the partial result can be reconciled without publishing the media twice. ## Platform-Specific Fields | Field | Type | Behavior | | -------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `contentType` | `"feed"` \| `"story"` \| `"reels"` | Selects the Instagram publish path. Defaults to feed. | | `firstComment` | string | Created after feed, carousel, or Reel publish. Requires `instagram_business_manage_comments`; unsupported for Stories. | | `collaborators` | string\[] | Up to 3 collaborator usernames for feed, carousel, and Reels. | | `userTags` | array | Image feed and image carousel tags with `username`, `x`, `y`, and optional `mediaIndex`. | | `shareToFeed` | boolean | Reel option. | | `thumbOffset` | integer | Reel thumbnail offset. | | `instagramThumbnail` | URL string | Reel cover URL. Overrides media item thumbnail. | | `trialParams.graduationStrategy` | `"MANUAL"` \| `"SS_PERFORMANCE"` | Reel trial parameter. | | `audioName` | string | Reel audio label. | ## Media Limits Kavenio validates supplied media metadata before calling Meta: | Media | Limit | | ------------- | ------------------------------------------------------------------------------------------------------------ | | Feed images | JPEG, 8 MB, aspect ratio 4:5 to 1.91:1 | | Feed videos | MP4/MOV, 3 seconds to 60 minutes, 300 MB, 4:5 to 1.91:1 | | Feed carousel | 2-10 image/video items | | Reels | One MP4/MOV video, 3 seconds to 15 minutes, 300 MB, 23-60 FPS, aspect ratio 0.01:1 to 10:1; 9:16 recommended | | Stories | One JPEG image or MP4/MOV video | | Story videos | 3 to 60 seconds, 100 MB, 23-60 FPS, aspect ratio 0.1:1 to 10:1; 9:16 recommended | Meta can still reject media after fetching the URL if the actual file does not match the metadata or current Instagram API constraints. Media URLs must be public and fetchable by Meta. Before creating a container, Kavenio checks Instagram's `content_publishing_limit`. Instagram allows 100 API-published posts per professional account in a rolling 24-hour window. A full quota is returned as a retryable rate-limit failure without creating a container. ## Scheduling Use Kavenio's normal `scheduledFor` field. Kavenio creates the Meta media container when the scheduled job runs, so media URLs must remain valid until publish time. ## Unsupported Cases Kavenio does not support these Instagram actions through post publishing: * text-only Instagram posts * Story captions * Story first comments * Story stickers, links, mentions, or other advanced Story options * user tags on videos * native edit or unpublish after publication ## Common Errors | Error | Meaning | Fix | | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------- | | `Instagram feed publishing requires one image or a 2-10 item carousel.` | Feed media count is invalid. | Send one image/video or a 2-10 item carousel. | | `Instagram Story publishing does not support captions.` | Story `content` is not empty. | Omit Story caption text. | | `Instagram advanced Story options are not implemented in this slice.` | A Story target included unsupported options. | Remove first comments, collaborators, tags, and Reel-only fields. | | `Instagram Reel publishing requires exactly one video media item.` | Reel media is missing or not a single video. | Send one video media item. | | `Instagram video media must use MP4 or MOV.` | Video MIME metadata is unsupported. | Host an MP4 or MOV file. | | `Connected Instagram credential does not include ... required for first comments.` | The saved connection lacks comment-management permission for its login mode. | Reconnect Instagram or omit `firstComment`. |