API - Corsair

Every instagram.api.* operation is listed below with parameter shapes and return types from the plugin Zod schemas.

New to Corsair? See API access, authentication, and error handling.

Carousel

post

carousel.post create a carousel container for publishing on instagram. Risk: write

await corsair.instagram.api.carousel.post({});

Input

Name	Type	Required	Description
`ig_id`	`string`	Yes	The Instagram User ID (IG User ID) of the Instagram professional account that will publish the carousel post.
`children`	`string[]`	Yes	An array of media container IDs that will be included in the carousel. A carousel must contain at least two media items.
`media_type`	`string`	Yes	The type of media container to create. For carousel posts, this is typically set to CAROUSEL.
`caption`	`string`	No	Optional caption text that will be displayed with the carousel post.
`share_to_feed`	`boolean`	No	Whether the carousel post should be shared to the Instagram profile feed.
`collaborators`	`string[]`	No	Optional list of Instagram User IDs to invite as collaborators on the carousel post.
`location_id`	`string`	No	Optional Facebook Location ID to associate a location with the carousel post.
`product_tags`	`object[]`	No	Optional list of Instagram Shopping products to tag in the carousel.

product_tags full type

{
  product_id: string
}[]

Output

Name	Type	Required	Description
`id`	`string`	Yes	The media container ID that can be used to check processing status or publish the media.

Comments

get

comments.get get details about a specific comment on an instagram media object. Risk: read

await corsair.instagram.api.comments.get({});

Input

Name	Type	Required	Description
`comment_id`	`string`	Yes	The Instagram Comment ID of the comment whose details should be retrieved.
`q`	`string`	No	Optional search query or filter used when retrieving comment details.

Output

Name	Type	Required	Description
`id`	`string`	Yes	The unique Instagram Comment ID.
`text`	`string`	No	The text content of the comment.
`hidden`	`boolean`	No	Indicates whether the comment is hidden from public view.
`like_count`	`number`	No	The total number of likes received by the comment.
`legacy_instagram_comment_id`	`string`	No	The legacy Instagram comment identifier, if available.
`timestamp`	`string`	No	The ISO 8601 timestamp indicating when the comment was created.
`parent_id`	`string`	No	The ID of the parent comment if this comment is a reply.
`from`	`object`	No	Information about the user who created the comment.
`media`	`object`	No	Information about the media on which the comment was posted.
`user`	`string`	No	The ID of the Instagram user associated with the comment.
`username`	`string`	No	The Instagram username of the comment author.
`replies`	`object[]`	No	The list of replies associated with this comment.

from full type

{
  id: string,
  username: string
}

media full type

{
  id: string,
  media_product_type?: string
}

replies full type

{
  id: string,
  text?: string,
  timestamp?: string
}[]

list

comments.list list comments on an instagram media object. Risk: read

await corsair.instagram.api.comments.list({});

Input

Name	Type	Required	Description
`media_id`	`string`	Yes	The Instagram Media ID of the post, Reel, video, or carousel whose comments should be retrieved.
`q`	`string`	No	Optional search query used to filter comments by text, username, or other supported criteria.

Output

Name	Type	Required	Description
`data`	`object[]`	No	The list of comments associated with the requested Instagram media.

data full type

{
  id: string,
  text?: string,
  timestamp?: string,
  username?: string
}[]

remove

comments.remove delete a comment on an instagram media object. Risk: write

await corsair.instagram.api.comments.remove({});

Input

Name	Type	Required	Description
`comment_id`	`string`	Yes	The Instagram Comment ID of the comment that should be permanently deleted.

Output

Name	Type	Required	Description
`success`	`boolean`	Yes	Indicates whether the comment update operation completed successfully.

reply

comments.reply reply to a comment on an instagram media object. Risk: write

await corsair.instagram.api.comments.reply({});

Input

Name	Type	Required	Description
`comment_id`	`string`	Yes	The Instagram Comment ID of the comment that should receive a reply.
`message`	`string`	Yes	The text content of the reply to post in response to the specified comment.

Output

Name	Type	Required	Description
`id`	`string`	Yes	The unique ID of the newly created reply comment.

send

comments.send send a comment on an instagram media object. Risk: write

await corsair.instagram.api.comments.send({});

Input

Name	Type	Required	Description
`media_id`	`string`	Yes	The Instagram Media ID of the post, Reel, video, Story, or carousel on which the comment will be created.
`message`	`string`	Yes	The text content of the comment to post on the specified Instagram media.

Output

Name	Type	Required	Description
`id`	`string`	Yes	The unique ID of the newly created Instagram comment.

update

comments.update update a comment on an instagram media object. Risk: write

await corsair.instagram.api.comments.update({});

Input

Name	Type	Required	Description
`comment_id`	`string`	Yes	The Instagram Comment ID of the comment to update.
`hide`	`boolean`	Yes	Whether the comment should be hidden. Set to true to hide the comment or false to unhide it.

Output

Name	Type	Required	Description
`success`	`boolean`	Yes	Indicates whether the comment update operation completed successfully.

Conversations

get

conversations.get get messages in a conversation on instagram messaging. Risk: read

await corsair.instagram.api.conversations.get({});

Input

Name	Type	Required	Description
`conversation_id`	`string`	Yes	The Instagram conversation or message thread ID whose messages should be retrieved.
`page_id`	`string`	Yes	The Facebook Page ID connected to the Instagram professional account that owns the conversation.
`q`	`string`	No	Optional search query used to filter messages within the conversation.

Output

Name	Type	Required	Description
`data`	`object[]`	Yes	The list of messages contained within the specified conversation.

data full type

{
  id: string,
  message?: string,
  created_time?: string,
  from?: {
    id?: string,
    username?: string
  },
  attachments?: {
    data?: {
      id?: string,
      mime_type?: string,
      name?: string,
      image_data?: {
      },
      video_data?: {
      },
      file_url?: string
    }[]
  }
}[]

list

conversations.list list conversations on instagram messaging. Risk: read

await corsair.instagram.api.conversations.list({});

Input

Name	Type	Required	Description
`page_id`	`string`	Yes	The Facebook Page ID connected to the Instagram professional account whose conversations should be retrieved.
`q`	`string`	No	Optional search query used to filter conversations by participant, message content, or other supported criteria.

Output

Name	Type	Required	Description
`data`	`object[]`	Yes	The list of Instagram conversations associated with the connected account.

data full type

{
  id: string
}[]

Image

post

image.post create an image container for publishing on instagram. Risk: write

await corsair.instagram.api.image.post({});

Input

Name	Type	Required	Description
`ig_id`	`string`	Yes	The Instagram User ID (IG User ID) of the Instagram professional account that will publish the image.
`image_url`	`string`	Yes	A publicly accessible URL of the image to be uploaded to Instagram.
`caption`	`string`	No	Optional caption text that will be displayed with the Instagram post.
`alt_text`	`string`	No	Optional accessibility description of the image for screen readers.
`is_carousel_item`	`boolean`	No	Set to true if this image will be added as an item in a carousel post rather than published as a standalone post.
`location_id`	`string`	No	Optional Facebook Location ID to associate a location with the Instagram post.
`user_tags`	`object[]`	No	Optional list of Instagram users to tag in the image along with their positions.
`product_tags`	`object[]`	No	Optional list of products to tag in the image for Instagram Shopping.

user_tags full type

{
  username: string,
  x: number,
  y: number
}[]

product_tags full type

{
  product_id: string,
  x: number,
  y: number
}[]

Output

Name	Type	Required	Description
`id`	`string`	Yes	The media container ID that can be used to check processing status or publish the media.

story

image.story create an image story container for publishing on instagram. Risk: write

await corsair.instagram.api.image.story({});

Input

Name	Type	Required	Description
`ig_id`	`string`	Yes	The Instagram User ID (IG User ID) of the Instagram professional account that will publish the Story.
`image_url`	`string`	Yes	A publicly accessible URL of the image to be uploaded as an Instagram Story.
`user_tags`	`string[]`	No	Optional list of Instagram usernames or user IDs to mention or tag in the Story.

Output

Name	Type	Required	Description
`id`	`string`	Yes	The media container ID that can be used to check processing status or publish the media.

Media

get

media.get get details about a specific media object. Risk: read

await corsair.instagram.api.media.get({});

Input

Name	Type	Required	Description
`media_id`	`string`	Yes	The Instagram Media ID of the post, reel, story, carousel, or video to retrieve.
`q`	`string`	No	Optional search query or filter used when retrieving media-related information.

Output

Name	Type	Required	Description
`id`	`string`	Yes	The unique Instagram Media ID.
`caption`	`string`	No	The caption text associated with the media.
`media_type`	`IMAGE \| VIDEO \| CAROUSEL_ALBUM`	Yes	The type of Instagram media, such as IMAGE, VIDEO, REELS, STORY, or CAROUSEL_ALBUM.
`media_url`	`string`	No	The URL of the media asset. May be null or unavailable for certain media types.
`thumbnail_url`	`string`	No	The URL of the media thumbnail image, typically available for videos and reels.
`permalink`	`string`	Yes	The permanent public URL to view the media on Instagram.
`timestamp`	`string`	Yes	The ISO 8601 timestamp indicating when the media was created.
`username`	`string`	Yes	The Instagram username that published the media.
`like_count`	`number`	Yes	The total number of likes received by the media.
`comments_count`	`number`	Yes	The total number of comments on the media.
`is_comment_enabled`	`boolean`	Yes	Indicates whether commenting is enabled for the media.
`children`	`object`	No	Carousel child media items. Present only for carousel posts.
`createdAt`	`Date`	No	The date and time when this record was created in the local system.
`updatedAt`	`Date`	No	The date and time when this record was last updated in the local system.

children full type

{
  data: {
    id: string,
    media_type: IMAGE | VIDEO,
    media_url: string
  }[]
}

insights

media.insights get insights for a specific media object. Risk: read

await corsair.instagram.api.media.insights({});

Input

Name	Type	Required	Description
`media_id`	`string`	Yes	The Instagram Media ID of the post, Reel, Story, video, or carousel whose insights should be retrieved.
`type`	`IMAGE \| VIDEO \| REELS \| STORY \| CAROUSEL_ALBUM`	Yes	The type of Instagram media for which insights are being requested.
`metric`	`string`	No	Optional insight metric to retrieve, such as impressions, reach, engagement, saved, likes, comments, shares, plays, or other supported Instagram insight metrics.

Output

Name	Type	Required	Description
`data`	`object[]`	Yes	A collection of insight metrics and values returned for the requested Instagram media.

data full type

{
}[]

list

media.list list media objects on the instagram account. Risk: read

await corsair.instagram.api.media.list({});

Input

Name	Type	Required	Description
`ig_id`	`string`	Yes	The Instagram User ID (IG User ID) of the Instagram professional account or createro account whose media should be retrieved.
`q`	`string`	No	Optional search keyword or filter to narrow the media results.

Output

Name	Type	Required	Description
`data`	`object[]`	Yes	The list of Instagram media objects returned by the request.
`paging`	`object`	No	Pagination information used to navigate through additional pages of media results.

data full type

{
  id: string,
  caption?: string,
  media_type: IMAGE | VIDEO | CAROUSEL_ALBUM,
  media_url?: string | null,
  thumbnail_url?: string | null,
  permalink: string,
  timestamp: string,
  username: string,
  like_count: number,
  comments_count: number,
  is_comment_enabled: boolean,
  children?: {
    data: {
      id: string,
      media_type: IMAGE | VIDEO,
      media_url: string
    }[]
  },
  createdAt?: Date | null,
  updatedAt?: Date | null
}[]

paging full type

{
  cursors?: {
    before?: string,
    after?: string
  },
  next?: string
}

status

media.status get the status of a media container. Risk: read

await corsair.instagram.api.media.status({});

Input

Name	Type	Required	Description
`container_id`	`string`	Yes	The Instagram media container ID whose processing status should be retrieved.

Output

Name	Type	Required	Description
`id`	`string`	Yes	The Instagram media container ID whose status was requested.
`status_code`	`IN_PROGRESS \| FINISHED \| ERROR \| EXPIRED`	Yes	The current processing status of the media container. IN_PROGRESS indicates processing is ongoing, FINISHED indicates the media is ready to publish, ERROR indicates processing failed, and EXPIRED indicates the container is no longer valid.

Messages

get

messages.get get details about a specific message on instagram messaging. Risk: read

await corsair.instagram.api.messages.get({});

Input

Name	Type	Required	Description
`page_id`	`string`	Yes	The Facebook Page ID connected to the Instagram professional account that owns the message.
`message_id`	`string`	Yes	The unique ID of the Instagram Direct Message to retrieve.
`q`	`string`	Yes	A search query or filter string used when retrieving message details.

Output

Name	Type	Required	Description
`id`	`string`	Yes	The unique identifier of the message.
`message`	`string`	No	The text content of the message.
`created_time`	`string`	No	The timestamp indicating when the message was created.
`from`	`object`	No	Information about the user who sent the message.
`attachments`	`object`	No	Attachment data associated with the message, such as images, videos, files, or other media.

from full type

{
  id?: string,
  username?: string
}

attachments full type

{
  data?: {
    id?: string,
    mime_type?: string,
    name?: string,
    image_data?: {
    },
    video_data?: {
    },
    file_url?: string
  }[]
}

send

messages.send send a message in instagram messaging. Risk: write

await corsair.instagram.api.messages.send({});

Input

Name	Type	Required	Description
`page_id`	`string`	Yes	The Facebook Page ID connected to the Instagram professional account that will send the message.
`recipient`	`string`	Yes	The recipient Instagram-scoped user ID (IGSID) or Messenger user ID that will receive the message.
`message`	`object`	Yes	The message content, including text, attachments, and optional quick replies.
`messaging_type`	`RESPONSE \| UPDATE \| MESSAGE_TAG`	No	The type of message being sent. Determines how Meta categorizes and delivers the message.
`tag`	`string`	No	Required for certain MESSAGE_TAG messages. Specifies the approved message tag used for the message.

message full type

{
  text?: string,
  attachment?: {
    type: image | video | audio | file | template,
    payload: {
    }
  },
  attachments?: {
    type: image | video | audio | file | template,
    payload: {
    }
  }[],
  quick_replies?: {
    content_type: text,
    title: string,
    payload: string
  }[]
}

Output

Name	Type	Required	Description
`recipient_id`	`string`	Yes	The ID of the user who received the message.
`message_id`	`string`	Yes	The unique identifier of the message that was sent.
`timestamp`	`number`	No	The Unix timestamp indicating when the message was sent.

Profile

get

profile.get read the user instagram profile. Risk: read

await corsair.instagram.api.profile.get({});

Input

Name	Type	Required	Description
`ig_id`	`string`	Yes	The Instagram User ID (IG User ID) of the Instagram account.
`q`	`string`	No	Optional search query or keyword used to filter related Instagram user data.

Output

Name	Type	Required	Description
`id`	`string`	Yes	—
`ig_id`	`number`	No	—
`username`	`string`	No	—
`name`	`string`	No	—
`biography`	`string`	No	—
`profile_picture_url`	`string`	No	—
`followers_count`	`number`	Yes	—
`follows_count`	`number`	Yes	—
`media_count`	`number`	Yes	—
`website`	`string`	No	—
`createdAt`	`Date`	No	—
`updatedAt`	`Date`	No	—

insights

profile.insights get insights for the instagram business account. Risk: read

await corsair.instagram.api.profile.insights({});

Input

Name	Type	Required	Description
`ig_id`	`string`	Yes	The Instagram User ID (IG User ID) of the Instagram professional account whose insights should be retrieved.
`metric`	`string`	Yes	One or more Instagram insight metrics to retrieve, such as impressions, reach, profile_views, follower_count, accounts_engaged, or other supported account-level metrics.
`period`	`string`	Yes	The aggregation period for the requested metrics, such as day, week, days_28, lifetime, or other supported periods.
`timeframe`	`string`	No	Required for demographics-related metrics. Specifies how far back Instagram should look when calculating the requested data.
`metric_type`	`string`	No	Optional metric category or calculation type used when requesting specific insight metrics.
`breakdown`	`string`	No	Optional dimension by which to break down the results, such as age, gender, country, city, or other supported demographic categories.
`since`	`string`	No	Optional start date or timestamp for the insights query. Results will include data from this point onward.
`until`	`string`	No	Optional end date or timestamp for the insights query. Results will include data up to this point.

Output

Name	Type	Required	Description
`data`	`object[]`	Yes	A collection of insight metrics and values returned for the requested Instagram media.

data full type

{
}[]

Publish

publish_media

publish.publish_media publish media on instagram. Risk: write

await corsair.instagram.api.publish.publish_media({});

Input

Name	Type	Required	Description
`ig_id`	`string`	Yes	The Instagram User ID (IG User ID) of the Instagram professional account that will publish the media.
`creation_id`	`string`	Yes	The media container ID returned by a previous media container creation request. This container will be published to Instagram.

Output

Name	Type	Required	Description
`id`	`string`	Yes	The media container ID that can be used to check processing status or publish the media.

Reel

post

reel.post create a reel container for publishing on instagram. Risk: write

await corsair.instagram.api.reel.post({});

Input

Name	Type	Required	Description
`ig_id`	`string`	Yes	The Instagram User ID (IG User ID) of the Instagram professional account that will publish the Reel.
`video_url`	`string`	Yes	A publicly accessible URL of the video file to be uploaded as an Instagram Reel.
`media_type`	`string`	Yes	The type of media container to create. For Reels, this is typically set to REELS.
`caption`	`string`	No	Optional caption text that will accompany the Reel when published.
`share_to_feed`	`boolean`	No	Whether the Reel should also be shared to the Instagram profile feed in addition to the Reels tab.
`collaborators`	`string[]`	No	Optional list of Instagram User IDs to invite as collaborators on the Reel.
`cover_url`	`string`	No	Optional publicly accessible URL of a custom cover image to use as the Reel thumbnail.
`audio_name`	`string`	No	Optional name of the audio track associated with the Reel.
`thumb_offset`	`number`	No	Optional timestamp offset in milliseconds used to generate the Reel thumbnail from the video.
`location_id`	`string`	No	Optional Facebook Location ID to associate a location with the Reel.
`user_tags`	`object[]`	No	Optional list of Instagram users to tag in the Reel.
`trial_params`	`any`	No	Optional experimental or trial parameters supported by the Instagram API.

user_tags full type

{
  username: string,
  x: number,
  y: number
}[]

Output

Name	Type	Required	Description
`id`	`string`	Yes	The media container ID that can be used to check processing status or publish the media.

Video

container

video.container create a video carousel container for publishing on instagram. Risk: write

await corsair.instagram.api.video.container({});

Input

Name	Type	Required	Description
`ig_id`	`string`	Yes	The Instagram User ID (IG User ID) of the Instagram professional account that will publish the video.
`video_url`	`string`	Yes	A publicly accessible URL of the video to be uploaded to Instagram.
`caption`	`string`	No	Optional caption text that will be displayed with the video post.
`alt_text`	`string`	No	Optional accessibility description of the video for screen readers.
`location_id`	`string`	No	Optional Facebook Location ID to associate a location with the video post.
`user_tags`	`object[]`	No	Optional list of Instagram users to tag in the video along with their positions.
`product_tags`	`object[]`	No	Optional list of Instagram Shopping products to tag in the video.

user_tags full type

{
  username: string,
  x: number,
  y: number
}[]

product_tags full type

{
  product_id: string,
  x: number,
  y: number
}[]

Output

Name	Type	Required	Description
`id`	`string`	Yes	The media container ID that can be used to check processing status or publish the media.

story

video.story create a video story container for publishing on instagram. Risk: write

await corsair.instagram.api.video.story({});

Input

Name	Type	Required	Description
`ig_id`	`string`	Yes	The Instagram User ID (IG User ID) of the Instagram professional account that will publish the Story.
`video_url`	`string`	Yes	A publicly accessible URL of the video to be uploaded as an Instagram Story.
`user_tags`	`string[]`	No	Optional list of Instagram usernames or user IDs to mention or tag in the Story.

Output

Name	Type	Required	Description
`id`	`string`	Yes	The media container ID that can be used to check processing status or publish the media.

​Carousel

​post

​Comments

​get

​list

​remove

​reply

​send

​update

​Conversations

​get

​list

​Image

​post

​story

​Media

​get

​insights

​list

​status

​Messages

​get

​send

​Profile

​get

​insights

​Publish

​publish_media

​Reel

​post

​Video

​container

​story

Carousel

post

Comments

get

list

remove

reply

send

update

Conversations

get

list

Image

post

story

Media

get

insights

list

status

Messages

get

send

Profile

get

insights

Publish

publish_media

Reel

post

Video

container

story