Instagram API

Schedule and automate Instagram posts with RelayAPI — feed posts, carousels, stories, reels, collaborators, and user tags.

Quick Reference

Before You Start

Quick Start

Post a photo to your Instagram feed:

import Relay from '@relayapi/sdk';
const client = new Relay();

const post = await client.posts.create({
  content: 'Beautiful sunset today #photography',
  targets: ['instagram'],
  media: [
    { url: 'https://cdn.example.com/sunset.jpg', type: 'image' },
  ],
  scheduled_at: 'now',
});

console.log(post.id); // post_abc123

Content Types

Feed Post (Single Image)

A single image post on the Instagram feed. Only the first 125 characters are visible before the "more" fold.

const post = await client.posts.create({
  content: 'Beautiful sunset today #photography',
  targets: ['instagram'],
  media: [
    { url: 'https://cdn.example.com/sunset.jpg', type: 'image' },
  ],
  scheduled_at: 'now',
});

Carousel (Up to 10 Images/Videos)

Mix images and videos in a swipeable carousel. The first item determines the aspect ratio for all items.

const post = await client.posts.create({
  content: 'Trip highlights from last weekend',
  targets: ['instagram'],
  media: [
    { url: 'https://cdn.example.com/photo1.jpg', type: 'image' },
    { url: 'https://cdn.example.com/photo2.jpg', type: 'image' },
    { url: 'https://cdn.example.com/clip.mp4', type: 'video' },
    { url: 'https://cdn.example.com/photo3.jpg', type: 'image' },
  ],
  scheduled_at: 'now',
});

Story

Stories are ephemeral (24 hours). Text captions are not displayed on stories. Link stickers are not available via the API.

const post = await client.posts.create({
  targets: ['instagram'],
  media: [
    { url: 'https://cdn.example.com/story.jpg', type: 'image' },
  ],
  scheduled_at: 'now',
  target_options: {
    instagram: {
      content_type: 'story',
    },
  },
});

Reel

Vertical video (9:16), max 90 seconds. Reels appear on the Reels tab and optionally on your profile feed.

const post = await client.posts.create({
  content: 'New tutorial!',
  targets: ['instagram'],
  media: [
    { url: 'https://cdn.example.com/reel.mp4', type: 'video' },
  ],
  scheduled_at: 'now',
  target_options: {
    instagram: {
      content_type: 'reels',
      share_to_feed: true,
      first_comment: 'Link in bio!',
    },
  },
});

Trial Reel with a custom cover

Trial Reels and cover selectors apply only when content_type is reels. trial_params.graduation_strategy is either MANUAL or SS_PERFORMANCE. Choose exactly one cover source: a public cover_url, a ready Relay cover_media_id, a ready generated cover_variant_id, or thumb_offset.

const post = await client.posts.create({
  content: 'Testing this Reel with non-followers first',
  targets: ['instagram'],
  scheduled_at: 'now',
  media: [{ url: reelURL, type: 'video' }],
  target_options: {
    instagram: {
      content_type: 'reels',
      share_to_feed: false,
      cover_variant_id: 'mder_ready_cover',
      trial_params: { graduation_strategy: 'SS_PERFORMANCE' },
    },
  },
});

Relay IDs remain stable in a scheduled post. At publish time, RelayAPI verifies that the media/variant belongs to the same organization and authorized workspace, is ready and unexpired, and then generates the short-lived provider URL in memory. See Media Uploads for creating a cover variant from a video.

Post with Collaborators and User Tags

Tag collaborators (up to 3) and users in images. Collaborators receive an invite to co-author the post.

const post = await client.posts.create({
  content: 'Collab post with our partners!',
  targets: ['instagram'],
  media: [
    { url: 'https://cdn.example.com/photo.jpg', type: 'image' },
  ],
  scheduled_at: 'now',
  target_options: {
    instagram: {
      collaborators: ['brandpartner', 'creator123'],
      user_tags: [
        { username: 'friend', x: 0.5, y: 0.5 },
      ],
    },
  },
});

Post with First Comment

Automatically post a first comment after publishing. Useful for hashtag blocks or calls to action.

const post = await client.posts.create({
  content: 'New product launch!',
  targets: ['instagram'],
  media: [
    { url: 'https://cdn.example.com/product.jpg', type: 'image' },
  ],
  scheduled_at: 'now',
  target_options: {
    instagram: {
      first_comment: '#newproduct #launch #startup #tech #innovation',
    },
  },
});

Media Requirements

Images

Aspect Ratios

Feed posts accept aspect ratios between 4:5 (0.8) and 1.91:1. Outside that range, the content must be a Story or Reel.

Videos

target_options Fields

All fields go inside target_options.instagram on your post request.

Common Errors

Known Quirks

• Media is required for all posts — Instagram does not support text-only posts.
• Business or Creator account required — personal accounts cannot post via the API.
• First 125 characters visible before the "more" fold. Front-load your most important message.
• Google Drive, Dropbox, OneDrive URLs do not work — they return HTML download pages, not media bytes. Always use direct CDN URLs.
• Stories do not display text captions — text is ignored. Link stickers are not available via the API.
• Carousel first item determines aspect ratio for all subsequent items in the carousel.
• Images over 8 MiB are rejected by RelayAPI preflight — resize them before publishing.
• 100 posts per 24-hour rolling limit includes feed posts, carousels, stories, and reels combined.
• User tags only work on images — not videos or stories. For carousels, use media_index to target specific slides.

Social actions

RelayAPI can hide/unhide Instagram comments, send a provider read receipt for a persisted inbound Instagram Messaging message, and list normalized story/post mentions already received through signed webhooks. It does not edit a published Instagram media object or comment. Reauthorize an older connection if it lacks instagram_manage_comments or instagram_manage_messages. See Published Edits and Social Actions.

Automations

The automations engine supports Instagram as a Tier 1 channel for inbound conversational events, message flows, live relationship checks, and Meta profile bindings.

Entrypoints

Instagram automations also support channel-independent schedule, field_changed, tag_applied, tag_removed, conversion_event, and webhook_inbound entrypoints. Button, quick-reply, ice-breaker, and menu postbacks resume the exact waiting run or route through the configured binding; they are not separate generic trigger kinds.

Messages and actions

Outbound content uses the channel-neutral message node. Its ordered blocks can contain text, images, videos, cards, galleries, and short in-message delays. Instagram supports branch buttons and up to 13 quick replies; audio and file blocks are rejected by validation or skipped with an explicit delivery result. See the Instagram Messaging API.

Profile bindings

Instagram exposes two provider-synchronized automation bindings:

• main_menu — one or more postback or URL items.
• ice_breaker — up to four starter questions with postback payloads.

Creating or updating either binding records desired state and queues provider synchronization. The dashboard reports pending, synced, or failed; deleting waits for Meta's delete acknowledgement before removing the local row. Runtime-only default_reply and welcome_message bindings are also available and do not modify the Instagram profile.

Quick example: comment → DM

await client.automations.create({
  name: 'Spring launch comment → DM',
  channel: 'instagram',
  template: {
    kind: 'comment_to_dm',
    config: {
      social_account_id: 'acc_instagram_xyz',
      post_ids: ['17895...'],
      keyword_filter: ['LINK', 'INFO'],
      dm_message: {
        blocks: [{ id: 'reply', type: 'text', text: 'Hey {{contact.name}}, here is the link you asked for.' }],
      },
      public_reply: 'Check your DMs! 📨',
      once_per_user: true,
      daily_cap: 500,
    },
  },
});

Rate limits + constraints

• Messaging admission: reactive sends require explicit automation consent or a bounded inbound customer-service conversation. A suppression or opt-out veto always wins.
• Daily caps: quick-start presets accept daily_cap; admission is enforced atomically per entrypoint and UTC day.
• Account scope: a preset's social_account_id must be active and match the automation's organization, workspace, and Instagram channel.
• Comment replies: Meta controls private/public reply eligibility and volume. Wire the message node's error port when you need a fallback.
• Provider sync: menus and ice breakers are asynchronous. Treat local pending state as not yet live on Instagram.