openapi: 3.0.3
info:
title: Instagram Graph API
description: >-
The Instagram Graph API allows Instagram Professionals (Business and Creator
accounts) to manage their presence on Instagram, including media publishing,
comments, hashtags, mentions, insights, and messaging. Uses the Facebook Graph
API infrastructure with OAuth 2.0 authentication.
version: "21.0"
contact:
name: Meta for Developers
url: https://developers.facebook.com/docs/instagram-api
license:
name: Meta Platform Terms
url: https://developers.facebook.com/terms
servers:
- url: https://graph.facebook.com/v21.0
description: Facebook Graph API (Facebook Login)
- url: https://graph.instagram.com/v21.0
description: Instagram Graph API (Instagram Login)
externalDocs:
description: Instagram Platform Documentation
url: https://developers.facebook.com/docs/instagram-platform
tags:
- name: Users
description: Instagram Business and Creator account profiles
- name: Media
description: Photos, videos, stories, reels, and carousels
- name: Publishing
description: Content creation and publishing workflow
- name: Comments
description: Comment management and moderation
- name: Hashtags
description: Hashtag search and media discovery
- name: Insights
description: Account and media level analytics
- name: Mentions
description: Content where account was mentioned
- name: Messaging
description: Instagram Direct messaging
paths:
/{user_id}:
get:
operationId: getUser
summary: Instagram Get User Profile
description: Get fields and edges on an Instagram Business or Creator account.
tags: [Users]
parameters:
- name: user_id
in: path
required: true
description: The Instagram user ID.
schema:
type: string
example: "17841400123456789"
- name: fields
in: query
required: false
description: Comma-separated list of fields to return.
schema:
type: string
example: "id,username,name,biography,followers_count,media_count"
- name: access_token
in: query
required: true
description: User access token.
schema:
type: string
responses:
'200':
description: User profile data.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/{user_id}/media:
get:
operationId: getUserMedia
summary: Instagram Get User Media
description: Get a collection of IG Media objects published on the account.
tags: [Media]
parameters:
- name: user_id
in: path
required: true
description: The Instagram user ID.
schema:
type: string
- name: fields
in: query
description: Comma-separated list of fields.
schema:
type: string
example: "id,caption,media_type,media_url,timestamp,permalink"
- name: limit
in: query
description: Maximum number of results per page.
schema:
type: integer
example: 25
- name: after
in: query
description: Cursor for pagination.
schema:
type: string
- name: access_token
in: query
required: true
schema:
type: string
responses:
'200':
description: List of media objects.
content:
application/json:
schema:
$ref: '#/components/schemas/MediaList'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createMediaContainer
summary: Instagram Create Media Container
description: Create a media container for publishing content. Step 1 of the publishing flow.
tags: [Publishing]
parameters:
- name: user_id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateContainerRequest'
responses:
'200':
description: Container created.
content:
application/json:
schema:
$ref: '#/components/schemas/ContainerResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/{user_id}/media_publish:
post:
operationId: publishMedia
summary: Instagram Publish Media Container
description: Publish a media container. Step 2 of the publishing flow.
tags: [Publishing]
parameters:
- name: user_id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [creation_id, access_token]
properties:
creation_id:
type: string
description: The container ID from createMediaContainer.
example: "17889615691921648"
access_token:
type: string
responses:
'200':
description: Media published.
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The published media ID.
example: "17854360229135492"
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/{user_id}/stories:
get:
operationId: getUserStories
summary: Instagram Get User Stories
description: Get a collection of story IG Media objects on the account.
tags: [Media]
parameters:
- name: user_id
in: path
required: true
schema:
type: string
- name: fields
in: query
schema:
type: string
- name: access_token
in: query
required: true
schema:
type: string
responses:
'200':
description: List of story media.
content:
application/json:
schema:
$ref: '#/components/schemas/MediaList'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/{user_id}/insights:
get:
operationId: getUserInsights
summary: Instagram Get User Insights
description: Get social interaction metrics for the account.
tags: [Insights]
parameters:
- name: user_id
in: path
required: true
schema:
type: string
- name: metric
in: query
required: true
description: Comma-separated list of metrics.
schema:
type: string
example: "impressions,reach,profile_views"
- name: period
in: query
required: true
description: Time period for aggregation.
schema:
type: string
enum: [day, week, days_28, month, lifetime]
example: "day"
- name: since
in: query
description: Unix timestamp for start of range.
schema:
type: integer
- name: until
in: query
description: Unix timestamp for end of range.
schema:
type: integer
- name: access_token
in: query
required: true
schema:
type: string
responses:
'200':
description: Account insights data.
content:
application/json:
schema:
$ref: '#/components/schemas/InsightsResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/{user_id}/tags:
get:
operationId: getUserTags
summary: Instagram Get User Tags
description: Get IG Media objects where the user has been tagged by other users.
tags: [Mentions]
parameters:
- name: user_id
in: path
required: true
schema:
type: string
- name: fields
in: query
schema:
type: string
- name: access_token
in: query
required: true
schema:
type: string
responses:
'200':
description: List of tagged media.
content:
application/json:
schema:
$ref: '#/components/schemas/MediaList'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/{user_id}/business_discovery:
get:
operationId: getBusinessDiscovery
summary: Instagram Get Business Discovery
description: Get data about other Instagram Business or Creator accounts.
tags: [Users]
parameters:
- name: user_id
in: path
required: true
schema:
type: string
- name: fields
in: query
required: true
description: Must include business_discovery.fields().
schema:
type: string
example: "business_discovery.fields(username,media_count,followers_count)"
- name: access_token
in: query
required: true
schema:
type: string
responses:
'200':
description: Business discovery data.
content:
application/json:
schema:
type: object
properties:
business_discovery:
$ref: '#/components/schemas/User'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/{user_id}/content_publishing_limit:
get:
operationId: getContentPublishingLimit
summary: Instagram Get Content Publishing Limit
description: Get current content publishing usage and rate limit status.
tags: [Publishing]
parameters:
- name: user_id
in: path
required: true
schema:
type: string
- name: fields
in: query
schema:
type: string
example: "config,quota_usage"
- name: access_token
in: query
required: true
schema:
type: string
responses:
'200':
description: Publishing limit data.
content:
application/json:
schema:
type: object
properties:
config:
type: object
properties:
quota_total:
type: integer
example: 100
quota_duration:
type: integer
example: 86400
quota_usage:
type: integer
example: 5
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/{media_id}:
get:
operationId: getMedia
summary: Instagram Get Media
description: Get fields on an Instagram photo, video, story, reel, or album.
tags: [Media]
parameters:
- name: media_id
in: path
required: true
description: The IG Media ID.
schema:
type: string
- name: fields
in: query
description: Comma-separated list of fields.
schema:
type: string
example: "id,caption,media_type,media_url,timestamp,like_count,comments_count"
- name: access_token
in: query
required: true
schema:
type: string
responses:
'200':
description: Media object.
content:
application/json:
schema:
$ref: '#/components/schemas/Media'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: updateMedia
summary: Instagram Update Media
description: Enable or disable comments on a media object.
tags: [Media]
parameters:
- name: media_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
comment_enabled:
type: boolean
example: true
access_token:
type: string
responses:
'200':
description: Update success.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteMedia
summary: Instagram Delete Media
description: Delete an Instagram media object (post, story, reel, or carousel).
tags: [Media]
parameters:
- name: media_id
in: path
required: true
schema:
type: string
- name: access_token
in: query
required: true
schema:
type: string
responses:
'200':
description: Media deleted.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
deleted_id:
type: string
example: "17854360229135492"
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/{media_id}/comments:
get:
operationId: getMediaComments
summary: Instagram Get Media Comments
description: Get comments on an Instagram media object.
tags: [Comments]
parameters:
- name: media_id
in: path
required: true
schema:
type: string
- name: fields
in: query
schema:
type: string
example: "id,text,username,timestamp,like_count"
- name: access_token
in: query
required: true
schema:
type: string
responses:
'200':
description: List of comments.
content:
application/json:
schema:
$ref: '#/components/schemas/CommentList'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createComment
summary: Instagram Create Comment
description: Create a comment on an Instagram media object.
tags: [Comments]
parameters:
- name: media_id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [message, access_token]
properties:
message:
type: string
description: The comment text.
example: "Great post!"
access_token:
type: string
responses:
'200':
description: Comment created.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: "17858893269000001"
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/{media_id}/insights:
get:
operationId: getMediaInsights
summary: Instagram Get Media Insights
description: Get social interaction metrics for a media object.
tags: [Insights]
parameters:
- name: media_id
in: path
required: true
schema:
type: string
- name: metric
in: query
required: true
description: Comma-separated list of metrics.
schema:
type: string
example: "impressions,reach,engagement,saved"
- name: access_token
in: query
required: true
schema:
type: string
responses:
'200':
description: Media insights data.
content:
application/json:
schema:
$ref: '#/components/schemas/InsightsResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/{media_id}/children:
get:
operationId: getMediaChildren
summary: Instagram Get Carousel Children
description: Get media objects within a carousel album.
tags: [Media]
parameters:
- name: media_id
in: path
required: true
schema:
type: string
- name: fields
in: query
schema:
type: string
- name: access_token
in: query
required: true
schema:
type: string
responses:
'200':
description: List of child media.
content:
application/json:
schema:
$ref: '#/components/schemas/MediaList'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/{comment_id}:
get:
operationId: getComment
summary: Instagram Get Comment
description: Get fields on an Instagram comment.
tags: [Comments]
parameters:
- name: comment_id
in: path
required: true
schema:
type: string
- name: fields
in: query
schema:
type: string
example: "id,text,username,timestamp,like_count,hidden"
- name: access_token
in: query
required: true
schema:
type: string
responses:
'200':
description: Comment data.
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: hideComment
summary: Instagram Hide or Unhide Comment
description: Hide or unhide a comment on your media.
tags: [Comments]
parameters:
- name: comment_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required: [hide, access_token]
properties:
hide:
type: boolean
description: True to hide, false to unhide.
example: true
access_token:
type: string
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteComment
summary: Instagram Delete Comment
description: Delete a comment on your media.
tags: [Comments]
parameters:
- name: comment_id
in: path
required: true
schema:
type: string
- name: access_token
in: query
required: true
schema:
type: string
responses:
'200':
description: Comment deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/{comment_id}/replies:
get:
operationId: getCommentReplies
summary: Instagram Get Comment Replies
description: Get replies to a comment.
tags: [Comments]
parameters:
- name: comment_id
in: path
required: true
schema:
type: string
- name: fields
in: query
schema:
type: string
- name: access_token
in: query
required: true
schema:
type: string
responses:
'200':
description: List of reply comments.
content:
application/json:
schema:
$ref: '#/components/schemas/CommentList'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createCommentReply
summary: Instagram Create Comment Reply
description: Reply to a comment.
tags: [Comments]
parameters:
- name: comment_id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [message, access_token]
properties:
message:
type: string
example: "Thanks for the feedback!"
access_token:
type: string
responses:
'200':
description: Reply created.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: "17858893269000002"
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/ig_hashtag_search:
get:
operationId: searchHashtag
summary: Instagram Search Hashtag
description: Search for a hashtag by name and get its ID.
tags: [Hashtags]
parameters:
- name: q
in: query
required: true
description: The hashtag to search for (without #).
schema:
type: string
example: "photography"
- name: user_id
in: query
required: true
description: The ID of the user making the request.
schema:
type: string
- name: access_token
in: query
required: true
schema:
type: string
responses:
'200':
description: Hashtag search results.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
example: "17843853986012965"
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/{hashtag_id}/top_media:
get:
operationId: getHashtagTopMedia
summary: Instagram Get Hashtag Top Media
description: Get the most popular media tagged with a specific hashtag.
tags: [Hashtags]
parameters:
- name: hashtag_id
in: path
required: true
schema:
type: string
- name: user_id
in: query
required: true
schema:
type: string
- name: fields
in: query
schema:
type: string
example: "id,caption,media_type,permalink"
- name: access_token
in: query
required: true
schema:
type: string
responses:
'200':
description: Top media for the hashtag.
content:
application/json:
schema:
$ref: '#/components/schemas/MediaList'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/{hashtag_id}/recent_media:
get:
operationId: getHashtagRecentMedia
summary: Instagram Get Hashtag Recent Media
description: Get the most recently published media tagged with a specific hashtag.
tags: [Hashtags]
parameters:
- name: hashtag_id
in: path
required: true
schema:
type: string
- name: user_id
in: query
required: true
schema:
type: string
- name: fields
in: query
schema:
type: string
- name: access_token
in: query
required: true
schema:
type: string
responses:
'200':
description: Recent media for the hashtag.
content:
application/json:
schema:
$ref: '#/components/schemas/MediaList'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/{container_id}:
get:
operationId: getContainer
summary: Instagram Get Container Status
description: Check the publishing status of a media container.
tags: [Publishing]
parameters:
- name: container_id
in: path
required: true
schema:
type: string
- name: fields
in: query
schema:
type: string
example: "status_code,status"
- name: access_token
in: query
required: true
schema:
type: string
responses:
'200':
description: Container status.
content:
application/json:
schema:
type: object
properties:
id:
type: string
status_code:
type: string
enum: [EXPIRED, ERROR, FINISHED, IN_PROGRESS, PUBLISHED]
example: "FINISHED"
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
oauth2:
type: oauth2
description: OAuth 2.0 authentication via Instagram Login or Facebook Login.
flows:
authorizationCode:
authorizationUrl: https://www.facebook.com/dialog/oauth
tokenUrl: https://graph.facebook.com/oauth/access_token
scopes:
instagram_basic: Read user profile and media.
instagram_content_publish: Publish content on behalf of the user.
instagram_manage_comments: Manage comments on media.
instagram_manage_insights: Access insights and analytics.
instagram_manage_messages: Manage Instagram Direct messages.
pages_show_list: Show list of pages managed by user.
pages_read_engagement: Read engagement data from pages.
schemas:
User:
type: object
properties:
id:
type: string
description: App-scoped user ID.
example: "17841400123456789"
username:
type: string
description: Instagram username.
example: "examplebusiness"
name:
type: string
description: Profile name.
example: "Example Business"
biography:
type: string
description: Profile bio text.
example: "Official account for Example Business."
website:
type: string
description: Website URL from profile.
example: "https://www.example.com"
profile_picture_url:
type: string
description: Profile picture URL.
example: "https://scontent.cdninstagram.com/example.jpg"
followers_count:
type: integer
description: Total followers.
example: 15000
follows_count:
type: integer
description: Total accounts followed.
example: 500
media_count:
type: integer
description: Total published media.
example: 342
Media:
type: object
properties:
id:
type: string
example: "17854360229135492"
caption:
type: string
example: "Beautiful sunset at the beach! #photography"
media_type:
type: string
enum: [IMAGE, VIDEO, CAROUSEL_ALBUM, REELS, STORIES]
example: "IMAGE"
media_url:
type: string
example: "https://scontent.cdninstagram.com/media/example.jpg"
thumbnail_url:
type: string
description: Thumbnail URL for videos.
permalink:
type: string
example: "https://www.instagram.com/p/ABC123/"
shortcode:
type: string
example: "ABC123"
timestamp:
type: string
format: date-time
example: "2026-04-17T12:00:00+0000"
like_count:
type: integer
example: 250
comments_count:
type: integer
example: 15
is_comment_enabled:
type: boolean
example: true
is_shared_to_feed:
type: boolean
example: true
alt_text:
type: string
description: Alt text for accessibility.
username:
type: string
example: "examplebusiness"
MediaList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Media'
paging:
$ref: '#/components/schemas/Paging'
Comment:
type: object
properties:
id:
type: string
example: "17858893269000001"
text:
type: string
example: "Amazing photo!"
username:
type: string
example: "fan_account"
timestamp:
type: string
format: date-time
example: "2026-04-17T14:30:00+0000"
like_count:
type: integer
example: 5
hidden:
type: boolean
example: false
parent_id:
type: string
description: ID of the parent comment if this is a reply.
CommentList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Comment'
paging:
$ref: '#/components/schemas/Paging'
InsightsResponse:
type: object
properties:
data:
type: array
items:
type: object
properties:
name:
type: string
example: "impressions"
period:
type: string
example: "day"
values:
type: array
items:
type: object
properties:
value:
type: integer
example: 1500
end_time:
type: string
format: date-time
example: "2026-04-17T07:00:00+0000"
title:
type: string
example: "Impressions"
description:
type: string
example: "Total number of times the media has been seen."
id:
type: string
CreateContainerRequest:
type: object
properties:
image_url:
type: string
description: Public URL of the image to publish.
example: "https://www.example.com/images/photo.jpg"
video_url:
type: string
description: Public URL of the video to publish.
caption:
type: string
description: Caption text for the media.
example: "Check out our latest product! #newlaunch"
media_type:
type: string
description: Type of media to publish.
enum: [IMAGE, VIDEO, REELS, STORIES, CAROUSEL]
example: "IMAGE"
is_carousel_item:
type: boolean
description: Set to true if this is an item in a carousel.
example: false
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/instagram/refs/heads/main/openapi/instagram-graph-api.yaml