Publish to Instagram

Publish single images, reels, stories, scheduled posts, and carousels to a connected Instagram account.

Single media publish

POST/api/v1/publish/instagram

Parameter	Type	Required	Description
`mediaId`	string	Yes	Media ID to publish.
`instagramAccountId`	string (UUID)	Yes	Connected Instagram account ID from `GET /instagram/accounts`.
`caption`	string	No	Post caption.
`altText`	string	No	Alt text for accessibility.
`product`	string	No	`"IMAGE"`, `"REELS"`, or `"STORIES"`. Images default to IMAGE, videos default to REELS.
`shareToFeed`	boolean	No	Share a Reel to the main feed as well.
`scheduledAt`	string	No	ISO 8601 timestamp with timezone offset. Must be 5 minutes to 29 days in the future.

The operation is asynchronous. The initial response returns an outputJobId and a status. Poll GET /jobs/publish/{outputJobId} until the status reaches succeeded or failed.

Scheduled publishing must be enabled for the account. If it is not enabled, requests with scheduledAt return 403.

{
  "outputJobId": "019e1b76-74d7-8c7e-a927-6bd34bfaa114",
  "status": "queued"
}

When scheduledAt is provided, the response status is scheduled and includes scheduledFor.

{
  "outputJobId": "019e1b76-74d7-8c7e-a927-6bd34bfaa114",
  "status": "scheduled",
  "scheduledFor": "2026-06-20T14:30:00+00:00"
}

Example

{
  "mediaId": "019e1b70-6f9e-80fd-8c49-690bcbdaf8db",
  "instagramAccountId": "550e8400-e29b-41d4-a716-446655440000",
  "caption": "Check out this new video!",
  "product": "REELS",
  "shareToFeed": true
}

Schedule management

GET/api/v1/publish/scheduled

Lists scheduled Instagram and TikTok publish jobs for the account, soonest first.

DELETE/api/v1/publish/scheduled/{outputJobId}

Cancels a scheduled publish before it fires. The endpoint returns 409 if the job has already started or reached a terminal state.

Both schedule-management endpoints return 403 when scheduled publishing is not enabled for the account.

Instagram carousel

POST/api/v1/publish/instagram/carousel

Parameter	Type	Required	Description
`mediaIds`	string[]	Yes	2 to 10 image media IDs. Instagram carousels only accept images.
`instagramAccountId`	string (UUID)	Yes	Connected Instagram account ID from `GET /instagram/accounts`.
`caption`	string	No	Optional caption, up to 2200 characters.

{
  "mediaIds": [
    "019e1b70-6f9e-80fd-8c49-690bcbdaf8db",
    "019e1b72-0742-8bae-bb93-b569036d05af"
  ],
  "instagramAccountId": "550e8400-e29b-41d4-a716-446655440000",
  "caption": "New carousel"
}

{
  "instagramPublishId": "b2d7e2ae-1d3d-4c88-8f01-0d2c8fb2d9b1",
  "igMediaId": "1789...",
  "permalink": "https://instagram.com/p/...",
  "imageCount": 2
}