Instagram

Instagram professional (Business and Creator) accounts through your Meta app, discovered and connected through the Facebook Page each account is linked to.

The permissions each capability needs are in App Review: Instagram.

feed and reel are publish variants of instagram.media.items; stories are their own surface because Instagram serves them from their own edge.
A DM reply is addressed to a person, not to a message: set recipientExternalId to the sender's id.
Instagram's comment webhook reports new comments only — no edits, deletions, or hides — so instagram.media.comments emits created alone.

Content type	Operations	Events	Backfill
`instagram.media.items`	`list`, `get`, `publish`	`created`	yes
`instagram.media.comments`	`list`, `get`, `publish`, `moderate`	`created`	no
`instagram.media.mentions`	none	`created`	no
`instagram.stories.items`	`list`, `get`, `publish`	`created`	yes
`instagram.dm.threads`	`list`	none	no
`instagram.dm.messages`	`list`, `publish`	`created`	no

`instagram.media.items`

The account's feed posts and reels.

`list`

List Instagram profile media items.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`cursor`	`string`	no	Opaque cursor for fetching the next result page.
`limit`	`number`	no	Maximum number of items to return.
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "cursor": {
      "description": "Opaque cursor for fetching the next result page.",
      "minLength": 1,
      "type": "string"
    },
    "limit": {
      "description": "Maximum number of items to return.",
      "minimum": 1,
      "type": "number"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId"
  ]
}

`get`

Get one Instagram media item by provider id.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`externalId`	`string`	yes
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "externalId": {
      "minLength": 1,
      "type": "string"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId",
    "externalId"
  ]
}

`publish`

Publish Instagram feed or reel media.

Submit through POST /v1/publish-requests with contentType: "instagram.media.items". These fields go in the item's args; connectedProfileId and variant are item fields.

variant: "feed"

Field	Type	Required	Description
`text`	`string`	no	Caption/body text for content.
`media`	`object \| object[]`	yes
`scheduling`	`object`	no	Future operation time and optional wall-clock timezone.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "text": {
      "description": "Caption/body text for content.",
      "type": "string"
    },
    "media": {
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "anyOf": [
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "mediaId": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "mediaId"
            ]
          },
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "sourceUrl": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "sourceUrl"
            ]
          }
        ]
      }
    },
    "scheduling": {
      "additionalProperties": false,
      "description": "Future operation time and optional wall-clock timezone.",
      "type": "object",
      "properties": {
        "at": {
          "format": "date-time",
          "description": "Future execution time as an ISO-8601 string.",
          "type": "string"
        },
        "timezone": {
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "at"
      ]
    }
  },
  "required": [
    "media"
  ]
}

variant: "reel"

Field	Type	Required	Description
`text`	`string`	no	Caption/body text for content.
`media`	`object \| object[]`	yes
`scheduling`	`object`	no	Future operation time and optional wall-clock timezone.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "text": {
      "description": "Caption/body text for content.",
      "type": "string"
    },
    "media": {
      "minItems": 1,
      "maxItems": 1,
      "type": "array",
      "items": {
        "anyOf": [
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "mediaId": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "pattern": "^video/",
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "mediaId"
            ]
          },
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "sourceUrl": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "pattern": "^video/",
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "sourceUrl"
            ]
          }
        ]
      }
    },
    "scheduling": {
      "additionalProperties": false,
      "description": "Future operation time and optional wall-clock timezone.",
      "type": "object",
      "properties": {
        "at": {
          "format": "date-time",
          "description": "Future execution time as an ISO-8601 string.",
          "type": "string"
        },
        "timezone": {
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "at"
      ]
    }
  },
  "required": [
    "media"
  ]
}

Not offered

update: provider not supported
moderate: provider not supported
delete: provider not supported

Events

content.instagram.media.items.created

Backfill: supported (bounded coverage); see Backfill history.

Item schema

What list and get return and what events carry as data.

Field	Type	Required	Description
`externalId`	`string`	yes	Provider-owned content identifier.
`variant`	`"feed" \| "reel"`	yes
`text`	`string`	no	Caption/body text for content.
`media`	`object[]`	no
`providerPermalink`	`string (uri)`	no	Canonical provider URL for content.
`publishedAt`	`string (date-time)`	no	Provider publish timestamp as an ISO-8601 string.
`providerRaw`	`unknown`	no	Optional provider-native payload included only for transient delivery/debug use.
`contentType`	`"instagram.media.items"`	yes

`instagram.media.comments`

Comments on the account's media, and replies to them.

`list`

List Instagram comments on one media item.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`mediaExternalId`	`string`	yes
`cursor`	`string`	no	Opaque cursor for fetching the next result page.
`limit`	`number`	no	Maximum number of items to return.
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "mediaExternalId": {
      "minLength": 1,
      "type": "string"
    },
    "cursor": {
      "description": "Opaque cursor for fetching the next result page.",
      "minLength": 1,
      "type": "string"
    },
    "limit": {
      "description": "Maximum number of items to return.",
      "minimum": 1,
      "type": "number"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId",
    "mediaExternalId"
  ]
}

`get`

Get one Instagram media comment by provider id.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`externalId`	`string`	yes
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "externalId": {
      "minLength": 1,
      "type": "string"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId",
    "externalId"
  ]
}

`publish`

Publish an Instagram comment: a reply to a comment or a top-level comment on a media item.

Submit through POST /v1/publish-requests with contentType: "instagram.media.comments". These fields go in the item's args; connectedProfileId and variant are item fields.

Field	Type	Required	Description
`target`	`object`	yes	The provider content this publish targets, identified as events identify it.
`text`	`string`	yes	Caption/body text for content.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "target": {
      "additionalProperties": false,
      "description": "The provider content this publish targets, identified as events identify it.",
      "type": "object",
      "properties": {
        "contentType": {
          "anyOf": [
            {
              "const": "instagram.media.comments",
              "type": "string"
            },
            {
              "const": "instagram.media.items",
              "type": "string"
            }
          ]
        },
        "externalId": {
          "description": "Provider-owned content identifier.",
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "contentType",
        "externalId"
      ]
    },
    "text": {
      "description": "Caption/body text for content.",
      "type": "string"
    }
  },
  "required": [
    "target",
    "text"
  ]
}

`moderate`

Hide or unhide an Instagram media comment.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`externalId`	`string`	yes
`hidden`	`boolean`	yes

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "externalId": {
      "minLength": 1,
      "type": "string"
    },
    "hidden": {
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId",
    "externalId",
    "hidden"
  ]
}

Not offered

update: provider not supported
delete: provider not supported

Events

content.instagram.media.comments.created

Backfill: not offered — provider no endpoint.

Item schema

What list and get return and what events carry as data.

Field	Type	Required	Description
`externalId`	`string`	yes	Provider-owned content identifier.
`mediaExternalId`	`string`	yes
`text`	`string`	yes	Caption/body text for content.
`author`	`object`	no	Provider actor reference for observed content.
`thread`	`object`	no	Parent/root identifiers for threaded contexts.
`publishedAt`	`string (date-time)`	no	Provider publish timestamp as an ISO-8601 string.
`providerRaw`	`unknown`	no	Optional provider-native payload included only for transient delivery/debug use.
`contentType`	`"instagram.media.comments"`	yes

`instagram.media.mentions`

Mentions of the account in other users' posts and comments. Delivered as events only: Meta offers no endpoint that lists them.

Not offered

list: provider no endpoint
get: not applicable
publish: provider not supported
update: provider not supported
moderate: provider not supported
delete: provider not supported

Events

content.instagram.media.mentions.created

Backfill: not offered — provider no endpoint.

Item schema

What list and get return and what events carry as data.

Field	Type	Required	Description
`externalId`	`string`	yes	Provider-owned content identifier.
`variant`	`"comment" \| "caption"`	yes
`mediaExternalId`	`string`	no
`commentExternalId`	`string`	no
`text`	`string`	no	Caption/body text for content.
`author`	`object`	no	Provider actor reference for observed content.
`thread`	`object`	no	Parent/root identifiers for threaded contexts.
`providerPermalink`	`string (uri)`	no	Canonical provider URL for content.
`publishedAt`	`string (date-time)`	no	Provider publish timestamp as an ISO-8601 string.
`providerRaw`	`unknown`	no	Optional provider-native payload included only for transient delivery/debug use.
`contentType`	`"instagram.media.mentions"`	yes

`instagram.stories.items`

The account's live stories.

`list`

List the Instagram profile's live stories.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`cursor`	`string`	no	Opaque cursor for fetching the next result page.
`limit`	`number`	no	Maximum number of items to return.
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "cursor": {
      "description": "Opaque cursor for fetching the next result page.",
      "minLength": 1,
      "type": "string"
    },
    "limit": {
      "description": "Maximum number of items to return.",
      "minimum": 1,
      "type": "number"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId"
  ]
}

`get`

Get one Instagram story by provider id.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`externalId`	`string`	yes
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "externalId": {
      "minLength": 1,
      "type": "string"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId",
    "externalId"
  ]
}

`publish`

Publish an Instagram story from one image or video.

Submit through POST /v1/publish-requests with contentType: "instagram.stories.items". These fields go in the item's args; connectedProfileId and variant are item fields.

Field	Type	Required	Description
`media`	`object \| object[]`	yes
`scheduling`	`object`	no	Future operation time and optional wall-clock timezone.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "media": {
      "minItems": 1,
      "maxItems": 1,
      "type": "array",
      "items": {
        "anyOf": [
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "mediaId": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "mediaId"
            ]
          },
          {
            "additionalProperties": false,
            "type": "object",
            "properties": {
              "sourceUrl": {
                "minLength": 1,
                "type": "string"
              },
              "contentType": {
                "minLength": 1,
                "type": "string"
              },
              "altText": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "sourceUrl"
            ]
          }
        ]
      }
    },
    "scheduling": {
      "additionalProperties": false,
      "description": "Future operation time and optional wall-clock timezone.",
      "type": "object",
      "properties": {
        "at": {
          "format": "date-time",
          "description": "Future execution time as an ISO-8601 string.",
          "type": "string"
        },
        "timezone": {
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "at"
      ]
    }
  },
  "required": [
    "media"
  ]
}

Not offered

update: provider not supported
moderate: provider not supported
delete: provider not supported

Events

content.instagram.stories.items.created

Backfill: supported (bounded coverage); see Backfill history.

Item schema

What list and get return and what events carry as data.

Field	Type	Required	Description
`externalId`	`string`	yes	Provider-owned content identifier.
`text`	`string`	no	Caption/body text for content.
`media`	`object[]`	no
`providerPermalink`	`string (uri)`	no	Canonical provider URL for content.
`publishedAt`	`string (date-time)`	no	Provider publish timestamp as an ISO-8601 string.
`providerRaw`	`unknown`	no	Optional provider-native payload included only for transient delivery/debug use.
`contentType`	`"instagram.stories.items"`	yes

`instagram.dm.threads`

The account's Instagram DM conversations.

`list`

List Instagram DM threads.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`cursor`	`string`	no	Opaque cursor for fetching the next result page.
`limit`	`number`	no	Maximum number of items to return.
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "cursor": {
      "description": "Opaque cursor for fetching the next result page.",
      "minLength": 1,
      "type": "string"
    },
    "limit": {
      "description": "Maximum number of items to return.",
      "minimum": 1,
      "type": "number"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId"
  ]
}

Not offered

get: provider not supported
publish: provider not supported
update: provider not supported
moderate: provider not supported
delete: provider not supported

Events

None: this content type is read-only.

Backfill: not offered — not implemented.

Item schema

What list and get return and what events carry as data.

Field	Type	Required	Description
`externalId`	`string`	yes	Provider-owned content identifier.
`participantExternalIds`	`string[]`	yes
`updatedAt`	`string (date-time)`	no	Provider update timestamp as an ISO-8601 string.
`providerRaw`	`unknown`	no	Optional provider-native payload included only for transient delivery/debug use.
`contentType`	`"instagram.dm.threads"`	yes

`instagram.dm.messages`

Messages in one Instagram DM conversation.

`list`

List Instagram DM messages in one thread.

Field	Type	Required	Description
`connectedProfileId`	`string`	yes	Koil Connected Profile associated with the operation.
`threadExternalId`	`string`	yes
`cursor`	`string`	no	Opaque cursor for fetching the next result page.
`limit`	`number`	no	Maximum number of items to return.
`includeProviderRaw`	`boolean`	no	Whether to include transient provider-native payloads.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "connectedProfileId": {
      "description": "Koil Connected Profile associated with the operation.",
      "minLength": 1,
      "type": "string"
    },
    "threadExternalId": {
      "minLength": 1,
      "type": "string"
    },
    "cursor": {
      "description": "Opaque cursor for fetching the next result page.",
      "minLength": 1,
      "type": "string"
    },
    "limit": {
      "description": "Maximum number of items to return.",
      "minimum": 1,
      "type": "number"
    },
    "includeProviderRaw": {
      "description": "Whether to include transient provider-native payloads.",
      "type": "boolean"
    }
  },
  "required": [
    "connectedProfileId",
    "threadExternalId"
  ]
}

`publish`

Send an Instagram DM to a recipient.

Submit through POST /v1/publish-requests with contentType: "instagram.dm.messages". These fields go in the item's args; connectedProfileId and variant are item fields.

Field	Type	Required	Description
`recipientExternalId`	`string`	yes	Provider actor the message is addressed to, such as a DM event's author.id.
`text`	`string`	yes	Caption/body text for content.

JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "recipientExternalId": {
      "minLength": 1,
      "description": "Provider actor the message is addressed to, such as a DM event's author.id.",
      "type": "string"
    },
    "text": {
      "description": "Caption/body text for content.",
      "type": "string"
    }
  },
  "required": [
    "recipientExternalId",
    "text"
  ]
}

Not offered

get: provider not supported
update: provider not supported
moderate: provider not supported
delete: provider not supported

Events

content.instagram.dm.messages.created

Backfill: not offered — not implemented.

Item schema

What list and get return and what events carry as data.

Field	Type	Required	Description
`externalId`	`string`	yes	Provider-owned content identifier.
`threadExternalId`	`string`	no	Owning conversation id. Present on messages read through instagram.dm.threads; absent on webhook-observed messages because the provider's messaging webhooks do not identify the conversation.
`text`	`string`	no	Caption/body text for content.
`author`	`object`	no	Provider actor reference for observed content.
`thread`	`object`	no	Parent/root identifiers for threaded contexts.
`publishedAt`	`string (date-time)`	no	Provider publish timestamp as an ISO-8601 string.
`providerRaw`	`unknown`	no	Optional provider-native payload included only for transient delivery/debug use.
`contentType`	`"instagram.dm.messages"`	yes

Instagram

instagram.media.items

list

get

publish

Not offered

Events

instagram.media.comments

list

get

publish

moderate

Not offered

Events

instagram.media.mentions

Not offered

Events

instagram.stories.items

list

get

publish

Not offered

Events

instagram.dm.threads

list

Not offered

Events

instagram.dm.messages

list

publish

Not offered

Events

On this page

`instagram.media.items`

`list`

`get`

`publish`

`instagram.media.comments`

`list`

`get`

`publish`

`moderate`

`instagram.media.mentions`

`instagram.stories.items`

`list`

`get`

`publish`

`instagram.dm.threads`

`list`

`instagram.dm.messages`

`list`

`publish`