Skip to main content
Instagram logo
  • Category: social media accounts
  • Auth: OAUTH2
  • Composio-managed OAuth available? Yes
  • Tools: 40
  • Triggers: 0
  • Slug: INSTAGRAM
  • Version: 20261101_00

Frequently Asked Questions

Instagram toolkit support is for Instagram Business/Creator account flows. If a user is using a personal Instagram account, convert or connect a Business/Creator account linked through Meta/Facebook as required by Instagram’s API.
Instagram comment tools can require Meta’s comment-management permission, such as instagram_manage_comments for Facebook Login or instagram_business_manage_comments for Instagram Business Login. Those permissions must be configured on the Meta app and approved by Meta before the OAuth flow can grant them.If a reply-to-comment flow fails because the managed OAuth app does not currently have the required comment permission, use your own Meta OAuth app with that permission configured and approved. Composio is working on managed-app approval for the missing permission, but an owned Meta app is the current unblock path for production usage.

Tools

Slug: INSTAGRAM_CREATE_MEDIA_CONTAINERDEPRECATED: Creates a draft media container for photos, videos or Reels for a Business or Creator account. Returns an ID for subsequent publishing; containers expire after about 24 hours and must finish processing before publication.

Input Parameters

string
Post caption text. Maximum 2,200 characters. Hashtag limit: 30 hashtags maximum per post (Instagram enforces this limit). Mention limit: 20 @mentions maximum.
string
Custom accessibility alt text for a single image or an image carousel child. Maximum 1,000 characters. Not supported for videos, Reels, Stories, or carousel parent containers.
string
Cover image URL for videos/Reels. Query parameters, including signed CDN or object-storage URLs, are supported as long as the complete URL remains accessible while Meta processes the container. Optional - if omitted, Instagram generates a cover from the video (or uses thumb_offset).
string
Public URL of the image. CRITICAL REQUIREMENTS: (1) Must be a DIRECT link to the raw image file - no HTML wrappers or interactive authentication. Query parameters, including signed CDN or object-storage URLs, are supported as long as the complete URL remains accessible while Meta processes the container. (2) Must be accessible by Meta’s crawlers without cookies or additional request headers (Google Drive share pages and generated HTML endpoints will NOT work). (3) Must return proper HTTP 200 status with correct Content-Type header (image/jpeg or image/png). (4) Supported formats: JPG, PNG (WebP not supported). Max 8MB, min 320px width, aspect ratio 4:5 to 1.91:1. RECOMMENDED: Use image hosting services like Imgur, Cloudinary, AWS S3, or similar that provide direct or sufficiently long-lived signed download URLs. For videos, a thumbnail is optional — omit it and Instagram generates a cover, or use cover_url / thumb_offset.
array
Array of user tag objects for tagging public Instagram accounts. For images each tag needs username, x and y (0.0-1.0 from top-left); for Reels only username is allowed.
string
Public URL of the video. CRITICAL REQUIREMENTS: (1) Must be a DIRECT link to the raw video file - no HTML wrappers or interactive authentication. Query parameters, including signed CDN or object-storage URLs, are supported as long as the complete URL remains accessible while Meta processes the container. (2) Must be accessible by Meta’s crawlers without cookies or additional request headers (Google Drive share pages and generated HTML endpoints will NOT work). (3) Must return proper HTTP 200 status with correct Content-Type header (video/mp4 or video/quicktime). (4) Supported formats: MP4, MOV. Max 100MB for feed videos, max 1GB for IGTV, min 3 seconds duration. RECOMMENDED: Use video hosting services or cloud storage like AWS S3, Cloudinary, or similar with a direct or sufficiently long-lived signed URL.
string
Instagram Business Account ID (numeric string like ‘17841400008460056’). Optional - defaults to the current authenticated user. Do NOT pass Composio connection IDs (starting with ‘ca_’) or other auth identifiers.
string ("REELS" | "CAROUSEL" | "STORIES")
Explicit media type override (REELS, CAROUSEL, or STORIES). For plain image containers, leave this unset - image is the default and media_type must NOT be sent. REELS requires video_url. NOTE: VIDEO media_type was deprecated on November 9, 2023 and, if provided, is automatically converted to REELS.
string
Facebook Page ID of a location to tag. The Page must have latitude/longitude data.
string ("photo" | "video" | "reel" | "carousel_item")
What you want to post: ‘photo’, ‘video’, ‘reel’, or ‘carousel_item’ (for carousel drafts)
integer
For videos/Reels - millisecond offset used to capture the cover thumbnail frame.
boolean
For Reels - whether to also show the Reel in the main feed. Only applicable to REELS.
Legacy parameter to mark media as a carousel item. Prefer using content_type=‘carousel_item’ instead, which automatically sets this flag. When creating carousel items, you must provide either image_url or video_url. Carousels support a maximum of 10 items; each item must independently satisfy format, size, and aspect-ratio constraints.
string
The Facebook Graph API version to use for the request.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_CREATE_POSTDEPRECATED: Use INSTAGRAM_POST_IG_USER_MEDIA_PUBLISH instead. Publish a draft media container to Instagram (final publishing step). Posts become immediately and publicly visible upon success — confirm intent before calling. Requires Business or Creator account with publish scopes; missing scopes return Graph error code 10. After creating a media container, Instagram may need time to process media before publishing. If called too early, error code 9007 is returned. This action automatically retries with exponential backoff (up to ~44 seconds total). For large videos, use INSTAGRAM_GET_POST_STATUS to poll until status_code=‘FINISHED’ before calling; for carousels, all child containers must individually reach FINISHED status first. No native scheduling support — use an external scheduler to trigger this call at the desired time.

Input Parameters

string
required
Instagram Business Account ID. Must be a numeric string (e.g., ‘25162441193410545’). Personal accounts and misconfigured IDs are rejected.
string
required
The media container ID returned in the ‘id’ field from INSTAGRAM_CREATE_MEDIA_CONTAINER or INSTAGRAM_CREATE_CAROUSEL_CONTAINER. Typically a long numeric string like ‘17895695668004550’. IMPORTANT: Do NOT use datetime strings (e.g., ‘2024-01-15T10:30:00+0000’) - those are unrelated fields in Instagram responses. The container ID is found in the response like: {‘id’: ‘17895695668004550’}. Containers expire after ~24 hours; recreate via INSTAGRAM_CREATE_MEDIA_CONTAINER if stale.
string
The Facebook Graph API version to use for the request.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_DELETE_COMMENTTool to delete a comment on Instagram media. Use when you need to remove a comment that was created by your Instagram Business or Creator Account. Note: You can only delete comments that your account created - you cannot delete other users’ comments unless they are on your own media.

Input Parameters

string
required
The unique identifier of the Instagram comment to delete. This must be a comment created by your Instagram Business or Creator Account.
string
Instagram Graph API version to use. Defaults to v21.0.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_DELETE_MESSENGER_PROFILEDelete ice breakers or a persistent menu from an Instagram messenger profile.

Input Parameters

array
required
Array of Instagram messenger profile properties to delete. Valid values: ice_breakers, persistent_menu. Only the specified fields will be removed.
string
required
Instagram Business Account ID whose messenger profile settings will be deleted.
string
Instagram Graph API version to use. Defaults to v21.0.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_ENABLE_WEBHOOK_SUBSCRIPTIONSEnable selected Instagram Login webhook fields for delivery to the connected professional account. This enables account delivery only; it does not configure the callback URL or app-level webhook subscriptions. The Meta app must be Live, have its callback configured, and meet Advanced Access and business verification prerequisites before this action is used.

Input Parameters

string
Instagram Graph API version to use. Defaults to v21.0.
array
required
Unique Instagram Login webhook fields to enable for account delivery. Valid values: comments, live_comments, message_echoes, message_reactions, messages, messaging_handover, messaging_optins, messaging_postbacks, messaging_referral, messaging_seen, standby. Mentions are delivered through comments and cannot be subscribed to independently.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_GET_CONVERSATIONGet details about a specific Instagram DM conversation (participants, etc). Requires a Business or Creator account with Instagram messaging permissions; personal accounts will return permission errors. Newly sent/received messages may take a few seconds to appear in results.

Input Parameters

string
required
The unique identifier for the Instagram conversation thread. The thread must already exist; first-contact DMs cannot be initiated via the API — a manual first message must be sent before a conversation_id is available.This is typically a base64-encoded string obtained from the list_conversations or list_all_conversations actions. Must not be empty or contain only whitespace.
string
The Graph API version to use (e.g., ‘v21.0’). Defaults to ‘v21.0’.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_GET_IG_COMMENT_REPLIESGet replies to a specific Instagram comment. Returns a list of comment replies with details like text, username, timestamp, and like count. Use when you need to retrieve child comments (replies) for a specific parent comment.

Input Parameters

string
Cursor for forward pagination - get replies after this cursor
integer
Number of replies to return per page (max 100)
string
Cursor for backward pagination - get replies before this cursor
string
Comma-separated list of fields to return. Available fields: id, text, username, timestamp, like_count, hidden, from, media, parent_id, replies, legacy_instagram_comment_id
string
required
Instagram Comment ID to get replies for
string
Graph API version to use

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_GET_IG_MEDIAGet a published Instagram Media object (photo, video, story, reel, or carousel). Use when you need to retrieve detailed information about a specific Instagram post including engagement metrics, caption, media URLs, and metadata. NOTE: This action is for published media only. For unpublished container IDs (from INSTAGRAM_CREATE_MEDIA_CONTAINER), use INSTAGRAM_GET_POST_STATUS to check status instead.

Input Parameters

string
Comma-separated list of fields to return. Supported: id, caption, comments_count, is_comment_enabled, like_count, media_type, media_url, media_product_type, legacy_instagram_media_id, owner, permalink, shortcode, thumbnail_url, timestamp, username, alt_text, is_ai_generated, is_shared_to_feed, media_audio_type, view_count, reposts_count, saved_count, shares_count, total_like_count, total_comments_count, total_views_count, children, comments. For nested fields use ‘children{media_url,media_type}’. UNSUPPORTED (cause errors): tagged_users, user_tags, location, filter_name, latitude, longitude, text — use ‘caption’ not ‘text’. For insights metrics use INSTAGRAM_GET_IG_MEDIA_INSIGHTS. Tagged-media retrieval is unavailable through this Instagram Login toolkit. A MediaBuilder error means the ID is an unpublished container — use INSTAGRAM_GET_POST_STATUS.
string
required
The numeric ID of the Instagram media object from the Graph API (e.g., ‘17858625294504375’). IMPORTANT: This must be a numeric string, NOT an alphanumeric shortcode from instagram.com/p/<shortcode>/ URLs (e.g., ‘DUTi4n4D9wg’ is NOT valid). Obtain numeric IDs from INSTAGRAM_GET_IG_USER_MEDIA or similar endpoints. For unpublished container IDs, use INSTAGRAM_GET_POST_STATUS instead.
string
Instagram Graph API version to use

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_GET_IG_MEDIA_CHILDRENTool to get media objects (images/videos) that are children of an Instagram carousel/album post. Use when you need to retrieve individual media items from a carousel album post. Note: Carousel children media do not support insights queries - for analytics, query metrics at the parent carousel level.

Input Parameters

string
Comma-separated list of fields to return for each child media item. Available fields: id, caption, media_type, media_url, username, timestamp, permalink, thumbnail_url, ig_id, owner, shortcode, is_comment_enabled, comments_count, like_count
string
required
The ID of a CAROUSEL_ALBUM media post (not a user ID). This must be a media ID from a carousel/album post, typically obtained by calling ‘Get IG User Media’ action first and filtering for media_type=‘CAROUSEL_ALBUM’. Media IDs are numeric strings (17 digits) that identify specific Instagram posts, distinct from user/account IDs.
string
Instagram Graph API version to use

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_GET_IG_MEDIA_COMMENTSList selected comments for an Instagram media object ID using fields, limit, and after cursors.

Input Parameters

string
Cursor for forward pagination. Use the cursor value from previous response’s paging.cursors.after field
integer
Number of comments to return per page (typically 50-100)
string
Cursor for backward pagination. Use the cursor value from previous response’s paging.cursors.before field
string
Comma-separated list of fields to retrieve for each comment. Available fields: id, text, username, timestamp, like_count, legacy_instagram_comment_id, replies, from, hidden, media, parent_id, user
string
required
The ID of the Instagram media object (post/photo/video/album) to retrieve comments from. Must be a Media ID, not a User ID. Media IDs can be obtained from endpoints like GET /ig-user-id/media. Media IDs typically look like ‘17858625294504375’. The media must belong to the connected Business/Creator account; media from other accounts will return empty data or an error.
string
Instagram Graph API version to use

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_GET_IG_MEDIA_INSIGHTSGet performance insights for an Instagram media object, such as views, reach, likes, comments, saves and shares. Requires a Business or Creator account. Some metric names are normalized, and certain invalid or deprecated metrics are removed; the response reports removals and substitutions.

Input Parameters

array
required
List of metrics to retrieve. Must be provided as an array of strings, e.g., [‘reach’, ‘saved’, ‘likes’]. COMMONLY SUPPORTED METRICS: views, reach, saved, likes, comments, shares, total_interactions, reposts. REELS-SPECIFIC METRICS: ig_reels_video_view_total_time, ig_reels_avg_watch_time, reels_skip_rate, facebook_views, crossposted_views. FEED-AND-STORY METRICS: profile_activity. STORIES-SPECIFIC METRICS: link_clicks, replies, navigation, follows, profile_visits. DEPRECATED METRICS (will be filtered out): ‘impressions’, ‘plays’, ‘video_views’, ‘clips_replays_count’, ‘ig_reels_aggregated_all_plays_count’ (use ‘views’ instead); ‘taps_forward’, ‘taps_back’, ‘exits’ (Story navigation metrics deprecated in API v18+, use ‘navigation’ instead). INVALID METRIC NAMES (will be rejected): ‘clicks’, ‘engagement’ are NOT valid metric names.
string
The time period for metric aggregation. Instagram media insights automatically use ‘lifetime’; other period values are not supported.
string ("action_type" | "story_navigation_action_type")
Optional breakdown dimension for supported metrics. Allowed values: ‘action_type’ (e.g. for profile_activity) and ‘story_navigation_action_type’ (for Story navigation). Only applicable to metrics that support breakdowns.
string
required
The ID of the Instagram media object (photo, video, reel, carousel album) for which to retrieve insights
string
Instagram Graph API version to use

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_GET_IG_USER_CONTENT_PUBLISHING_LIMITGet an Instagram Business Account’s current content publishing usage. Use this to monitor quota usage before publishing; exceeding the daily cap blocks new posts until the quota resets (no partial failure — new publish calls are rejected until reset). IMPORTANT: This endpoint requires an IG User ID (Instagram Business Account ID), NOT an IGSID (Instagram Scoped ID). IGSID is only used for messaging-related endpoints. Content publishing endpoints require a proper IG User ID. Excessive polling of this endpoint may trigger Graph error 613 (rate limit); space calls several seconds apart.

Input Parameters

integer
Unix timestamp marking the start of the 24-hour window to measure usage from. Must be within the last 24 hours (older values are rejected by Instagram). If omitted, the window ends at the current time.
string
Comma-separated list of fields to return. Available fields: quota_usage, config. Defaults to ‘quota_usage,config’.
string
Instagram Business Account ID (IG User ID). Must be a valid IG User ID, NOT an IGSID/scoped ID (used for messaging). Defaults to ‘me’ for current user. To get your IG User ID, use GET /{facebook-page-id}?fields=instagram_business_account.
string
Facebook Graph API version to use

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_GET_IG_USER_LIVE_MEDIAGet live media objects for an Instagram Business or Creator account during an active broadcast, including the live video media ID and metadata.

Input Parameters

string
Comma-separated list of fields to return for the live media object. Available fields: id, media_type, media_url, timestamp, permalink. Defaults to all available fields.
string
Instagram Business or Creator Account ID (optional, defaults to ‘me’ for current user). Must be an account with an active live broadcast.
string
Facebook Graph API version to use

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_GET_IG_USER_MEDIAList one cursor-paginated page of user media with selected fields; use ig_user_id=‘me’ for the authenticated account.

Input Parameters

string
Forward-pagination cursor from paging.cursors.after in the previous response; omit for the first page.
integer
Maximum number of media objects to return in this page (default 25, maximum 100).
integer
Unix timestamp - filter results to media created after this time. If both ‘since’ and ‘until’ are provided, ‘since’ must be less than ‘until’.
integer
Unix timestamp - filter results to media created before this time. If both ‘since’ and ‘until’ are provided, ‘since’ must be less than ‘until’.
string
Cursor for backward pagination - retrieve media before this cursor
string
Comma-separated projection of fields to select for each media object. Available fields: id, caption, media_type, media_url, permalink, thumbnail_url, timestamp, username, comments_count, like_count, legacy_instagram_media_id, is_comment_enabled, owner, shortcode, media_product_type, alt_text, is_ai_generated, is_shared_to_feed, media_audio_type, view_count, reposts_count, saved_count, shares_count, total_like_count, total_comments_count, total_views_count, children{media_url,media_type,thumbnail_url}. Reels appear as media_type=VIDEO and media_product_type=REELS; filter both fields to identify reels. media_url is a direct file URL; permalink is the user-facing share link. Optional fields like caption and like_count may be null or absent in the response.
string
required
Instagram Business or Creator Account ID. Use ‘me’ for the authenticated user, or provide the numeric IG User ID obtained from the Instagram Graph API (typically 17 digits, e.g., ‘17841405793187218’). Facebook Page IDs are not supported or automatically converted.
string
Instagram Graph API version to use (e.g., ‘v21.0’)
boolean
Deprecated no-op retained for backwards compatibility. On Instagram Login the host follows the token (graph.instagram.com) and Facebook Page IDs are not resolved. Provide an Instagram Business or Creator Account ID directly (or ‘me’).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_GET_IG_USER_STORIESGet active story media objects for an Instagram Business or Creator account. Stories are retrieved via the /stories endpoint. Returns stories that are currently active within the 24-hour window. Use this to retrieve story content, metadata, and engagement metrics for monitoring or analytics purposes.

Input Parameters

string
Cursor for pagination to get the next page of results. Use the ‘after’ cursor from the previous response’s paging object.
integer
Number of stories to return per page for pagination. If not specified, returns all active stories.
string
Cursor for pagination to get the previous page of results. Use the ‘before’ cursor from the previous response’s paging object.
string
Comma-separated list of fields to return for each story. Available fields: id, caption, comments_count, ig_id, is_comment_enabled, like_count, media_type, media_url, owner, permalink, shortcode, thumbnail_url, timestamp, username. If not specified, defaults to id, media_type, media_url, permalink, and timestamp.
string
Instagram Business or Creator Account ID (optional, defaults to ‘me’ for current user). Must be an account with active stories within the 24-hour window. Must be a numeric ID; usernames are not accepted.
string
Facebook Graph API version to use

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_GET_IG_USER_TAGSGet one page of media tagging an Instagram Business or Creator account using Instagram Login. Select fields and use the returned cursors for pagination. Requires basic access and comment-management permission.

Input Parameters

string
Cursor for forward pagination - retrieve media after this cursor
integer
Number of tagged media items to return per page (default: 25, max: 100)
string
Cursor for backward pagination - retrieve media before this cursor
string
Comma-separated list of fields to return. Available fields: id, caption, comments_count, ig_id, is_comment_enabled, like_count, media_product_type, media_type, media_url, owner, permalink, shortcode, thumbnail_url, timestamp, username, video_title. If not specified, defaults to commonly used fields.
string
required
Instagram Business or Creator Account ID. Use ‘me’ for the authenticated user’s account.
string
Instagram Graph API version (e.g., ‘v21.0’). If not specified, uses v21.0 as default.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_GET_MESSENGER_PROFILEGet the messenger profile settings for an Instagram account. Returns ice breakers and other messaging configuration. Use when you need to retrieve messaging settings, ice breaker questions, or messenger configuration for an Instagram Business account.

Input Parameters

string
Comma-separated list of messenger profile fields to retrieve. Available options: ice_breakers, persistent_menu. Defaults to both supported fields.
string
required
The Instagram User ID for which to retrieve messenger profile settings
string
The Graph API version to use (e.g., ‘v21.0’). Defaults to ‘v21.0’.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_GET_MULTIPLE_NODESRetrieve selected fields for multiple Instagram Graph nodes and return the results keyed by requested node ID. The action reads nodes individually and fails if a node request fails.

Input Parameters

string
Optional exact comma-separated field projection valid for every requested node.
array
required
Instagram Graph node IDs to retrieve, up to 50 per action call.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_GET_PAGE_CONVERSATIONSGet a page of Instagram conversations for an Instagram Business account, with cursor pagination.

Input Parameters

string
Cursor for pagination to get the next page of results.
integer
Maximum number of conversations to return per page.
string
Platform to filter conversations. Set to ‘instagram’ to get Instagram conversations only.
string
required
Instagram Business Account ID to get conversations for. This is the Instagram Business Account ID that can be obtained from the /me endpoint. On graph.instagram.com this cannot be a Facebook Page ID.
string
The Graph API version to use (e.g., ‘v21.0’). Defaults to ‘v21.0’.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_GET_POST_COMMENTSDEPRECATED: Use INSTAGRAM_GET_IG_MEDIA_COMMENTS instead. Get comments on an Instagram post. Requires Instagram Business or Creator account. Returns empty data array (not an error) when no comments exist. Response data is nested under data.data; unwrap before processing. Timestamps are timezone-aware ISO 8601 strings; use UTC-based comparison.

Input Parameters

string
Cursor for forward pagination - get comments after this cursor. Value comes from paging.cursors.after in the response.
integer
Number of comments to return (max 100)
string
Cursor for backward pagination - get comments before this cursor. Value comes from paging.cursors.before in the response.
string
Comma-separated list of fields to return for each comment. Available fields: id, text, timestamp, like_count, hidden, username, from, replies, media, parent_id, legacy_instagram_comment_id
string
required
Instagram Post ID
string
The Facebook Graph API version to use for the request.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_GET_POST_INSIGHTSGet insights for an Instagram post from a Business or Creator account, using its numeric media ID and selected metrics or a metric preset. Available metrics vary by media type. DEPRECATED: Use INSTAGRAM_GET_IG_MEDIA_INSIGHTS instead.

Input Parameters

string
Metrics to retrieve for the media. Accepts a comma-separated string (e.g. ‘reach,likes,comments’) or an array of strings. If not provided and metric_preset is not set, uses auto_safe preset. Allowed metrics vary by media_product_type: IMAGE/CAROUSEL: reach, likes, comments, saved, shares. VIDEO: reach, views, likes, comments, saved, shares. REELS: reach, likes, comments, saved, shares, total_interactions, ig_reels_video_view_total_time, ig_reels_avg_watch_time, views, reels_skip_rate. Stories: reach, replies. Note: ‘engagement’ and ‘impressions’ are NOT valid standalone metrics - use individual metrics like likes, comments, saved, shares instead. ‘plays’ is dead (removed April 21, 2025) - use ‘views’ instead. If a metric is unsupported for the post type, API returns 400 error. Some metrics (e.g., shares) may return null even for supported media types; handle missing values before computing ratios.
string
required
Numeric Instagram Media ID from the Graph API (e.g., ‘17895695668004196’). This must be the numeric ID, NOT the shortcode from Instagram URLs (e.g., ‘DT0ndbTgcLH’ from instagram.com/p/DT0ndbTgcLH/ will NOT work). Use INSTAGRAM_GET_IG_USER_MEDIA to obtain valid numeric media IDs.
string ("auto_safe" | "image_basic" | "video_basic" | "reel_basic" | "carousel_basic")
Predefined metric sets for different media types to avoid API errors.
string
The Facebook Graph API version to use for the request.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_GET_POST_STATUSDEPRECATED: Use GetIgMedia instead. Check the processing status of a draft post container. Poll until status_code=‘FINISHED’ before calling INSTAGRAM_CREATE_POST; publishing early triggers OAuthException 9007 (HTTP 400). If status_code=‘ERROR’ or remains non-terminal after ~30 attempts, the container is permanently failed — recreate a new container. Poll every 3–5s with exponential backoff to avoid error 613/code 4/HTTP 429. For carousels, all child containers must reach FINISHED before publishing the parent.

Input Parameters

string
required
The media container ID returned from INSTAGRAM_CREATE_MEDIA_CONTAINER action. This is a numeric string (e.g., ‘17843131380645284’) that uniquely identifies the media container. Use this ID to check the container’s publishing status before calling the publish endpoint. Sourced from the data.id field (not data.creation_id) in the INSTAGRAM_CREATE_MEDIA_CONTAINER response. Containers expire after ~24 hours; do not reuse an expired creation_id.
string
The Facebook Graph API version to use for the request.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_GET_USER_INFOGet Instagram Business Account info including profile details and statistics. Use “me” to query your own authenticated account, or provide the numeric Business Account ID of an account you manage. NOTE: followers_count and follows_count are returned for your own profile (ig_user_id=“me”). For other accounts, follower/follow counts are surfaced through the business_discovery edge rather than this direct-node action, so they may be null here.

Input Parameters

string
Optional exact comma-separated projection of Instagram user fields. Supported profile fields include id, user_id, username, name, account_type, profile_picture_url, followers_count, follows_count, and media_count. When omitted, the action uses its existing profile field defaults.
string
Instagram Business Account ID. IMPORTANT: You can only query Business/Creator accounts that you manage through Facebook Business Manager. Use “me” to query your own authenticated account. To query other accounts you manage, provide their numeric Business Account ID. Arbitrary public accounts cannot be queried. If not provided, defaults to “me”.
string
The Facebook Graph API version to use for the request.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_GET_USER_INSIGHTSGet Instagram account-level insights and analytics (profile views, reach, follower count, etc.). Requires a Business or Creator account; personal accounts are not supported. Returned timestamps are in UTC. metric_type (time_series or total_value): When set to total_value, the API returns a total_value object instead of values. breakdown: Only applicable when metric_type=total_value and only for supported metrics. timeframe: Required for demographics-related metrics and overrides since/until for those metrics.

Input Parameters

integer
Start of time range (inclusive) as a Unix timestamp (seconds). Also accepts date strings (YYYY-MM-DD or ISO 8601 format) which will be converted to timestamps.
integer
End of time range (inclusive) as a Unix timestamp (seconds). Also accepts date strings (YYYY-MM-DD or ISO 8601 format) which will be converted to timestamps.
array
List or comma-separated metrics. Valid: reach, follower_count, online_followers, accounts_engaged, total_interactions, likes, comments, shares, saves, replies, follows_and_unfollows, profile_links_taps, views, profile_views, website_clicks, reposts, threads_likes, threads_replies, threads_followers, threads_views, threads_clicks, threads_reposts, quotes, content_views, and the demographics metrics engaged_audience_demographics, reached_audience_demographics, follower_demographics, and threads_follower_demographics. All demographics metrics require timeframe. All metrics in one call must share a period. Empty results are valid when data is unavailable (follower_count/online_followers require 100 followers; Threads metrics require a linked Threads profile). Rejected by Meta, do not request: impressions, email_contacts, phone_call_clicks, text_message_clicks, get_directions_clicks, audience_*.
string ("day" | "lifetime")
Valid period values for Instagram user insights aggregation. Available periods: - day: Daily aggregation (time-series metrics) - lifetime: Lifetime aggregation (for audience/demographics metrics) Note: ‘week’ and ‘days_28’ are no longer supported for IG user insights.
string
Breakdown to use when metric_type=total_value. Allowed values: contact_button_type, follow_type, media_product_type, age, city, country, gender.
string ("this_month" | "this_week")
Valid timeframe values for demographics-related Instagram user insights. Required for engaged_audience_demographics, reached_audience_demographics, follower_demographics, and threads_follower_demographics metrics. Overrides since/until parameters when specified. Note: As of 2025, Instagram deprecated the following timeframe values for demographics metrics: last_14_days, last_30_days, last_90_days, and prev_month. Only this_week and this_month are currently supported by the Instagram Graph API. All demographics metrics use period=lifetime and require the timeframe parameter.
string
Instagram Business Account ID - must be a numeric ID (e.g., ‘17841400008460056’). Content API IDs with ‘ca_’ prefix are not supported. Optional, defaults to current user.
string
Aggregation type for results. Allowed values: time_series, total_value.
string
The Facebook Graph API version to use for the request.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_GET_USER_MEDIADEPRECATED: Use INSTAGRAM_GET_IG_USER_MEDIA instead. Get Instagram user’s media (posts, photos, videos). Only works for connected Business or Creator accounts; personal accounts return no data. Response data is nested under data.data; unwrap before processing. Items mix images, videos, carousels, and reels — filter by media_type and media_product_type. Use media_url for file download, permalink for share links. Fields like caption, like_count may be null. Timestamps are UTC ISO 8601. HTTP 429 with Retry-After header indicates rate limiting.

Input Parameters

string
Cursor for pagination - get media after this cursor Chain calls using paging.cursors.after from the response to paginate; set an upper bound (e.g., ~300 posts) to avoid unbounded loops.
integer
Number of media items to return (max 100) A single call may not return all media; paginate via after for complete results.
string
Numeric Instagram Business Account ID (NOT username). Must be a numeric ID like ‘17841405793187218’. Omit or leave empty to get the current authenticated user’s media. To find an account’s numeric ID, use the INSTAGRAM_GET_USER_INFO action.
string
The Facebook Graph API version to use for the request.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_LIST_ALL_CONVERSATIONSList one cursor-paginated page of Instagram DM conversations for the authenticated or specified Business/Creator account, optionally selecting conversation fields and filtering for one participant.

Input Parameters

string
Forward-pagination cursor from paging.cursors.after in the previous response; omit for the first page.
integer
Maximum number of conversations to return in this page.
string
Optional exact comma-separated projection for each conversation. Supported fields include id, is_owner, messages, participants, and updated_time. Omit to preserve the API’s default fields.
string
Optional Instagram-scoped user ID (IGSID) to find the conversation with a specific person.
string
Platform to filter conversations. Required by the Instagram messaging API; set to ‘instagram’.
string
Instagram Business/Creator Account ID whose conversations to list. Omit to list conversations for the authenticated account via /me/conversations.
string
The Facebook Graph API version to use for the request.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_LIST_ALL_MESSAGESList one cursor-paginated page of messages from a specific Instagram DM conversation, with a caller-selectable field projection. Set the page size and use the returned cursor to retrieve the next page.

Input Parameters

string
Cursor for pagination. Pass paging.cursors.after from the previous response to fetch the next page. Stop when paging.cursors.after or paging.next is absent.
integer
Maximum number of messages to return.
string
Exact comma-separated projection for each message. Supported fields include id, created_time, from, to, message, attachments, is_unsupported, reactions, shares, story, and tags.
string
required
Unique identifier for the Instagram conversation. Obtain this by calling the INSTAGRAM_LIST_ALL_CONVERSATIONS action, which returns conversation IDs in the format ‘aWdfZAG06…’ (base64-encoded string).
string
The Facebook Graph API version to use for the request.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_LIST_SUBSCRIBED_APPSReturn one provider page of apps enabled for webhook notifications on the authenticated Instagram professional account, including subscribed fields. Check paging.next in the response when present; Meta does not expose a continuation input for this edge.

Input Parameters

string
Meta Graph API version to use (for example, ‘v25.0’). Defaults to ‘v25.0’.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_MARK_SEENMark Instagram DM messages as read/seen for a specific user. Sends a ‘mark_seen’ sender action to indicate messages from the specified recipient have been read. Marking as seen is visible to the other party and changes inbox read state — use with explicit user approval in automated or bulk flows. IMPORTANT LIMITATIONS: - The sender_action API feature may have limited support on Instagram - The recipient must have an active 24-hour messaging window open - Requires instagram_manage_messages permission - Only works with Instagram Business or Creator accounts If this action fails with a 500 error, it may indicate that the sender_action feature is not supported for your Instagram account or the specific recipient.

Input Parameters

string
Instagram Business Account ID. Optional - when not provided, the /me/messages endpoint is used instead of /{ig_user_id}/messages.
string
required
Instagram-Scoped User ID (IGSID) of the recipient. This is a numeric string obtained from conversation participants (e.g., ‘17841479358498320’). The recipient must have an existing conversation with your Instagram Business/Creator account. In multi-participant threads, use the individual participant’s IGSID, not a group or thread identifier.
string
Instagram Graph API version to use (e.g., ‘v21.0’).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_POST_IG_COMMENT_REPLIESTool to create a reply to an Instagram comment. Use when you need to reply to a specific comment on an Instagram post owned by a Business or Creator account. The reply must be 300 characters or less, contain at most 4 hashtags and 1 URL, and cannot consist entirely of capital letters.

Input Parameters

string
required
The text content of the reply to be posted. Maximum length: 300 characters. Maximum 4 hashtags allowed. Maximum 1 URL allowed. Cannot consist entirely of capital letters.
string
required
The unique identifier of the Instagram comment to which you want to reply. This is the ID of the parent comment that will receive the reply.
string
Instagram Graph API version to use. Defaults to v21.0.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_POST_IG_MEDIA_COMMENTSTool to create a comment on an Instagram media object. Use when you need to post a comment on a specific Instagram post, photo, video, or carousel. The comment must be 300 characters or less, contain at most 4 hashtags and 1 URL, and cannot consist entirely of capital letters.

Input Parameters

string
required
The text content of the comment to be posted on the media object. Maximum length: 300 characters. Maximum 4 hashtags allowed. Maximum 1 URL allowed. Cannot consist entirely of capital letters.
string
required
The unique identifier of the Instagram media object where the comment will be posted. This is the ID of the Instagram post, photo, video, or carousel.
string
Instagram Graph API version to use. Defaults to v21.0.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_POST_IG_USER_MEDIATool to create a media container for Instagram posts. Use this to create a container for images, videos, Reels, or carousels. This is the first step in Instagram’s two-step publishing process - after creating the container, use the media_publish endpoint to publish it.

Input Parameters

string
Caption text for the post. Use HTML URL encoding for hashtags (# becomes %23).
string
Custom accessibility alt text for a single image or an image carousel child. Maximum 1,000 characters. Not supported for videos, Reels, Stories, or carousel parent containers.
array
For carousel posts - array of container IDs (2-10 items) from previously created media containers.
string
For Reels - MUST be a valid HTTP/HTTPS URL pointing to a custom cover image that Meta can fetch. Query parameters, including signed CDN or object-storage URLs, are supported as long as the complete URL remains accessible while the container is processed. If both cover_url and thumb_offset are provided, cover_url takes precedence.
string
MUST be a valid HTTP/HTTPS URL pointing to a JPEG image file that Meta can fetch. Must start with ‘http://’ or ‘https://’ (e.g., ‘https://example.com/image.jpg’). Query parameters, including signed CDN or object-storage URLs, are supported as long as the complete URL remains accessible to Meta while the container is processed. DO NOT pass image descriptions or text - only actual URLs are accepted. At least one of: image_url, image_file, video_url, video_file, or children must be provided.
array
Array of user tag objects for tagging public Instagram accounts. For images: x and y coordinates (0.0-1.0, from top-left) are REQUIRED. For Reels: only username is allowed; x/y coordinates CANNOT be used.
string
MUST be a valid HTTP/HTTPS URL pointing to a video or Reel MP4 file that Meta can fetch. Must start with ‘http://’ or ‘https://’ (e.g., ‘https://example.com/video.mp4’). Query parameters, including signed CDN or object-storage URLs, are supported as long as the complete URL remains accessible to Meta while the container is processed. DO NOT pass video descriptions or text - only actual URLs are accepted. At least one of: image_url, image_file, video_url, video_file, or children must be provided. When using video_url alone, media_type will be automatically set to ‘REELS’ if not specified.
string
For Reels - custom name for the audio track (default: ‘Original Audio’).
string
required
The unique identifier of the Instagram Business account (IG User ID) to create media for. This must be an Instagram Business account.
object
Image file to upload. The file will be uploaded to a temporary public URL for Instagram to fetch. At least one of: image_url, image_file, video_url, video_file, or children must be provided.
string ("REELS" | "CAROUSEL" | "STORIES")
Media type for the container. Valid values: ‘REELS’ (for video content), ‘CAROUSEL’ (for carousel posts with children), ‘STORIES’ (for story posts). When posting video content with video_url alone (no image_url), this will automatically default to ‘REELS’ if not specified. Note: ‘VIDEO’ is deprecated and no longer supported - use ‘REELS’ for all video content.
object
Video file to upload. The file will be uploaded to a temporary public URL for Instagram to fetch. At least one of: image_url, image_file, video_url, video_file, or children must be provided.
string
Facebook Page ID of a location to tag. The Page must have latitude/longitude data.
integer
For videos/Reels - millisecond offset for thumbnail frame (default: 0).
boolean
For Reels - whether to share to both Feed and Reels tabs. Only applicable when media_type is REELS.
Indicates this container is part of a carousel. For carousels: create 2-10 individual containers, then create a parent carousel container with their IDs.
string
Instagram Graph API version to use. Defaults to v21.0.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_POST_IG_USER_MEDIA_PUBLISHPublish a media container to an Instagram Business account and return the published media ID. By default, the action polls for FINISHED status before publishing, subject to a wait timeout; setting the wait to zero skips status checks and attempts immediate publication.

Input Parameters

string
required
Instagram Business Account ID (numeric string) or ‘me’ for the authenticated user. This ID is returned by INSTAGRAM_GET_USER_INFO or similar actions. Do NOT pass bank account numbers, connection IDs, or other non-Instagram identifiers.
string
required
Container ID returned by INSTAGRAM_CREATE_MEDIA_CONTAINER (numeric string). This is NOT the same as ig_user_id. Do NOT pass bank account numbers or other non-Instagram identifiers.
integer
Maximum time in seconds to wait for the container to reach FINISHED status before publishing. Images are typically ready instantly, but videos/reels commonly take 30-120 seconds to process. WARNING: Setting this to 0 skips all status checks and attempts immediate publish, which will fail with error 9007 if the container is still processing (common for videos). Only use 0 if you are certain the container is already in FINISHED status (rare - typically only after manually checking via INSTAGRAM_GET_POST_STATUS). For videos/reels, use at least 60 seconds (default) or higher (up to 300).
string
Instagram Graph API version to use. Defaults to v21.0.
number
Interval in seconds between status checks while waiting for the container to be ready. Default is 3 seconds.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_POST_IG_USER_MENTIONSTool to reply to a mention of your Instagram Business or Creator account. Use when you need to respond to comments or media captions where your account has been @mentioned by another Instagram user. This creates a comment on the media or comment containing the mention.

Input Parameters

string
required
The text content of your reply to the mention. This creates a comment on the media or comment where you were mentioned.
string
required
The ID of the Instagram media object (post, photo, video, or carousel) where your account was mentioned. This is the media containing the original mention.
string
Optional ID of a specific comment where you were mentioned. If provided, your reply will be directed to that comment. If not provided, the reply will be posted on the media itself.
string
required
The unique identifier of the Instagram Business or Creator account that was mentioned. This is the ID of your Instagram account that received the mention.
string
Instagram Graph API version to use. Defaults to v21.0.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_REPLY_TO_COMMENTDEPRECATED: Use INSTAGRAM_POST_IG_COMMENT_REPLIES instead. Reply to a comment on Instagram media. Only usable on comments belonging to media owned by the authenticated account. Creates a public, irreversible reply; invoke only with explicit user confirmation, not for bulk or speculative use.

Input Parameters

string
required
Reply message text Must comply with Instagram content policies; overly long or policy-violating text may be rejected.
string
required
Instagram Comment ID to reply to Must belong to media owned by the authenticated Instagram account; replies to other accounts’ media are not permitted.
string
The Facebook Graph API version to use for the request.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_SEND_IMAGESend an image via Instagram DM to a specific user. Each send modifies inbox state; avoid bulk or automated sends without explicit user approval.

Input Parameters

string
required
Publicly accessible URL of the image to send. Must be a direct link to an image file (JPEG, PNG, or GIF) that is reachable over HTTPS. The URL must not require authentication to access.
string
Instagram Business Account ID. Must be a numeric ID string (e.g., ‘17841400123456789’), not a username. Optional when using /me/messages endpoint.
string
required
Recipient’s IGSID (Instagram Scoped User ID). Must be a numeric ID string (e.g., ‘17841479358498320’), NOT a username. IGSIDs are obtained from conversations or webhook events when users message your business first. You can only send messages to users who have initiated a conversation with your business within the past 24 hours (or 7 days with HUMAN_AGENT tag).
string
Instagram Graph API version to use (e.g., ‘v21.0’).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_SEND_TEXT_MESSAGESend a text message to an Instagram user via DM in an existing conversation. Cannot initiate new DM threads — a prior conversation must exist. Requires an Instagram Business or Creator account with messaging permissions. Fails with error_subcode 2534022 if outside the messaging window; do not retry these failures.

Input Parameters

string
required
Message text to send
string
Instagram Business Account ID (optional when using /me/messages)
string
required
Recipient PSID (Instagram-scoped ID) Must be a real PSID obtained from INSTAGRAM_LIST_ALL_CONVERSATIONS or INSTAGRAM_LIST_ALL_MESSAGES — usernames or fabricated IDs cause HTTP 400 (code 100).
string
Instagram Graph API version
string
Message ID (mid) to reply to. This creates a visual reply link to the original message in the conversation. The mid can be obtained from webhook events or previous API responses.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_SET_MEDIA_COMMENT_ENABLEDEnable or disable new comments on owned, published Instagram media. Live video media is not supported by Meta.

Input Parameters

string
required
Numeric Graph API ID of owned, published Instagram media.
boolean
required
True enables new comments; false disables them.
string
Meta Graph API version to use. Defaults to v25.0.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: INSTAGRAM_UPDATE_MESSENGER_PROFILEUpdate ice breakers for an Instagram Business account’s messenger profile. Ice breakers are suggested questions that help users start conversations.

Input Parameters

string
required
Instagram Business Account ID whose messenger profile will be updated.
array
required
Array of ice breaker objects to configure for the messenger profile. Ice breakers provide suggested questions to help users start conversations. Maximum 4 ice breakers allowed.
string
Instagram Graph API version to use. Defaults to v21.0.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not