Instagram requirements

Account requirements

• The Instagram account must be a professional account — Business or Creator. Personal accounts cannot publish through the API, and Relay rejects them during the connect flow rather than letting you discover it at publish time.
• Relay connects through Instagram Login (the direct Instagram business login), so you don't need a linked Facebook Page.
• Two permissions are requested: instagram_business_basic (read the profile) and instagram_business_content_publish (create and publish media).
• Accounts in some regions or with certain restrictions may be excluded by Meta from API publishing entirely — that surfaces as a Graph error on the first publish.

Connecting an account

Start the flow from Accounts → Connect Instagram. Relay exchanges the authorization code for a long-lived token, reads the profile, and stores:

Token lifecycle

Long-lived Instagram tokens last 60 days and can be refreshed — but only while they're still alive. Relay runs a weekly refresh for every token expiring within 14 days, which in normal operation means a connection never lapses.

Post types

Omit the type and Relay infers it: one image is a feed post, one video is a reel, two or more items is a carousel. Stories are the exception — ask for them by name.

Media specifications

The left column is Instagram's published specification. The right is what Relay enforces before accepting an upload, so a file that passes here will not be rejected later for format reasons.

Images

Video (reels and stories)

Captions

• 1–2,200 characters. Relay rejects longer captions before they reach Instagram.
• Hashtags and @mentions work inline; there is no markdown or rich text.
• Stories ignore the caption entirely.
• Carousel slides can each carry their own caption, 1–2,200 characters, shown on that slide. It is sent on that slide's child container, while the post's own caption goes on the parent — so a carousel can have both. Feed posts, reels, and stories have a single container and nowhere to put a per-item caption; Relay rejects one rather than dropping it silently.

First comment

first_comment is posted as a comment on the post the moment it goes live — the usual home for a hashtag block you would rather keep out of the caption. It is posted once per target account, on that account's own copy of the post, 1–2,200 characters. Stories take none: Instagram has no comments there, and Relay rejects one rather than dropping it.

It is attempted after the post is published, so it can never hold up or fail a publish. If Instagram refuses the comment, the post stays published with its permalink and the target carries a breadcrumb saying why; transient refusals are retried with a backoff for up to five attempts. Poll first_comment_status on the target (pending, posted, or failed) to see how it went.

Publishing quota

Instagram allows 100 API-published posts per account per rolling 24 hours. A carousel counts as one post regardless of how many items it holds. Relay checks the remaining quota before creating a media container.

At the ceiling, the post is not failed. The target keeps a quota_exceeded breadcrumb, the post stays in publishing, and the scheduler retries until a slot frees up — which happens automatically as older posts age out of the 24-hour window.

"error": {
  "code": "quota_exceeded",
  "message": "Instagram allows 100 API-published posts per 24h and this account is at the limit — Relay will keep retrying until a slot frees up"
}

Timing & retries

Publishing is a two-step handshake with Instagram: create a media container, wait for it to finish processing, then publish it. Relay drives that from a scheduler tick.

• Images normally publish within the tick that claims them — a few seconds after schedule_at.
• Video is transcoded by Instagram asynchronously. Expect a minute or several; the target sits in processing until it's ready.
• Carousels create one child container per item, wait for all of them to finish, then create the parent. Each slide's own caption rides on its child container; the post caption goes on the parent. A single bad item fails the whole carousel.
• Retries never duplicate a post: container IDs are persisted as they're created, so a reclaimed post resumes rather than starting over.

Failure reference

When a target fails, error.code tells you whose fault it was and whether to retry. Codes beginning graph_ are Instagram's own error codes, passed through with Instagram's message.

Not supported

• PNG and other image formats. Instagram's publishing API takes JPEG only.
• Text-only posts. Every Instagram post needs at least one media item.
• Filters, shopping tags, and product tagging — not exposed by the publishing API.
• Editing or deleting a published post. Once it's live, use the Instagram app. Relay can only cancel posts that haven't published yet.
• Changing media, per-slide captions, or targets on an existing post. Cancel it and create a new one; only the post's own caption, its first comment, and its schedule are editable.
• TikTok here. TikTok has its own rules — see TikTok requirements. A post can target both.

For the request and response shapes behind all of this, see the REST API reference or the MCP tool reference.