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.

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. 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 or targets on an existing post. Cancel it and create a new one; only caption and schedule are editable.
• TikTok. The data model reserves the platform, but no TikTok publishing path is live.

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