Instagram API: A Developer's Guide to the Graph API
The Instagram API, often called the Instagram Graph API, is Meta's official API for Instagram Business and Creator accounts. It comes in two versions: one with Instagram Login and one with Facebook Login. Both publish posts, Reels, Stories, and carousels, and read insights, comments, and messages. Personal accounts are not supported. Adeli publishes feed posts, Reels, Stories, and carousels through one API key and handles the Meta app, review, and tokens.
The Instagram API is Meta's official way for apps to work with Instagram accounts. You'll often see it called the Instagram Graph API. It covers Business and Creator accounts only, and it comes in two versions that differ by how users log in: the Instagram API with Instagram Login and the Instagram API with Facebook Login. With either one, an approved app can publish posts, Reels, Stories, and carousels, read insights, and manage comments and messages.
Cost and rate limits have their own post, Is the Instagram API free?, and so does Meta app review.
Does Instagram have an API?#
Yes. Meta calls it the Instagram Platform, and it's the only official Instagram API that's still running. It works with Instagram professional accounts, meaning Business or Creator accounts, and every app that calls it is registered in the Meta App Dashboard.
Older guides also list the Instagram Basic Display API, the read-only API for personal accounts. Meta shut it down on December 4, 2024. If a tutorial tells you to use it, skip that tutorial.
What is the Instagram Graph API?#
The Instagram Graph API is the common name for the Instagram Platform APIs. Both versions sit on Meta's Graph API, so developers use the name for either one. The names you'll run into, and what each one means now:
| Name you'll see | What it refers to | Status |
|---|---|---|
| Instagram Graph API | The Instagram Platform, either version | Live |
| Instagram API with Instagram Login | Direct Instagram login, no Facebook Page | Live |
| Instagram API with Facebook Login | Login through a Facebook Page linked to the account | Live |
| Instagram Basic Display API | Read-only access to personal accounts | Shut down December 4, 2024 |
Instagram Graph API with Instagram Login vs. with Facebook Login#
Pick by where your users' accounts live. If they manage Instagram on its own, use Instagram Login. If their Instagram account is linked to a Facebook Page, or you need hashtag search or product tagging, use Facebook Login. Both versions serve professional accounts only. Instagram Login doesn't work with personal accounts.
| Instagram API with Instagram Login | Instagram API with Facebook Login | |
|---|---|---|
| Who logs in | The Instagram account, with Instagram credentials | A Facebook user who manages the linked Page |
| Facebook Page needed | No | Yes |
| Base URL | graph.instagram.com |
graph.facebook.com |
| Token type | Instagram User access token | Facebook User or Page access token |
| Publishing, comments, insights, mentions | Yes | Yes |
| Messaging | Yes | Through the Messenger Platform |
| Hashtag search | No | Yes |
| Product tagging and partnership ads | No | Yes |
Source: Meta's Instagram Platform overview.
The two versions use different permissions, and Meta reviews each set separately. If you want to support both logins, you request and pass review for both sets. When we went through Meta's review, the Facebook Login permissions were separate submissions from their Instagram Login twins, with their own use cases and screencasts.
Which Instagram accounts work with the API?#
Only professional accounts: Business or Creator. Personal accounts can't be published to or read through the official API. Any user can switch to a professional account for free in the Instagram app.
| Account type | Works with the Instagram API? |
|---|---|
| Business | Yes, with either login |
| Creator | Yes, with either login |
| Personal | No |
For Facebook Login, the professional account also has to be linked to a Facebook Page the user manages. And for insights, Meta says some metrics aren't available on accounts with fewer than 100 followers, so a brand-new test account can return sparse data.
What permissions does the Instagram API need?#
Each feature has its own permission, and the names depend on the login. Request only what your product uses, because every permission you request needs its own review.
| Feature | Instagram Login | Facebook Login |
|---|---|---|
| Profile and media (required for everything) | instagram_business_basic |
instagram_basic, pages_show_list |
| Publishing | instagram_business_content_publish |
instagram_content_publish |
| Comments | instagram_business_manage_comments |
instagram_manage_comments |
| Insights | instagram_business_manage_insights |
instagram_manage_insights |
| Messages | instagram_business_manage_messages |
instagram_manage_messages |
Facebook Login also asks for pages_read_engagement for most of these. Sources: the overview, content publishing, and insights docs.
Each permission also has an access level. Standard Access covers accounts you own or manage, which is enough for testing or posting to your own account. Advanced Access is required when your app serves accounts you don't own, which is any product where customers connect their own Instagram. Advanced Access requires App Review and Business Verification. Our Meta app review guide covers how long that takes and what gets rejected.
How do Instagram API access tokens work?#
Every connected Instagram account has its own access token, and it expires. Your app gets a token when a user logs in, swaps it for a longer-lived one, and has to refresh it before it runs out.
With Instagram Login, the lifecycle looks like this (Business Login docs):
- Authorize. Send the user to
https://www.instagram.com/oauth/authorizewith your app ID, redirect URI, and scopes. - Exchange the code. Trade the authorization code for a short-lived token, valid for 1 hour, at
https://api.instagram.com/oauth/access_token. - Get a long-lived token. Call
graph.instagram.com/access_tokenwithgrant_type=ig_exchange_tokenand your app secret. Long-lived tokens are valid for 60 days. - Refresh. Before day 60, call the refresh endpoint. A token can be refreshed once it's at least 24 hours old and still valid, and each refresh gives it another 60 days.
curl -X GET "https://graph.instagram.com/refresh_access_token?grant_type=ig_refresh_token&access_token=LONG_LIVED_TOKEN"A token nobody refreshes for 60 days is gone for good, and the user has to log in again. For a product with many connected accounts, that means running a refresh job for every account and handling the ones users revoke. For a quick test on your own account, you can also generate a token in the App Dashboard under Instagram > API setup.
What are Instagram API keys?#
The Instagram API has no single API key. A search for one usually means one of these:
- App ID. The public identifier of your Meta app.
- App Secret. A private credential for server-side calls, like the long-lived token exchange. Never ship it in client code.
- Access tokens. One per connected Instagram account. These authorize your API calls, so they're the closest thing to a "key".
To get the first two, create a Business-type app in the Meta App Dashboard and add the Instagram product. The tokens come from each user's login. A unified API like Adeli works the other way around: you get one API key, and Adeli holds the Meta app and every account's tokens.
What can you do with the Instagram API?#
Publish content, read insights, and manage comments and messages for the professional accounts that connect to your app.
| Capability | What it covers | Meta docs |
|---|---|---|
| Publish | Single images, videos, Reels, Stories, and carousels of up to 10 items | Content publishing |
| Insights | Account-level and media-level metrics | Insights |
| Comments | Read, reply to, hide, and delete comments on the account's media | Overview |
| Messages | Read and reply to Instagram Direct messages | Overview |
| Mentions | Media and comments where the account is @mentioned | Overview |
| Hashtag search | Public media by hashtag (Facebook Login only) | Overview |
How does publishing work?#
Publishing takes two calls: create a media container, then publish it. Meta fetches the media from your URL, so it has to be hosted on a public server when you make the call.
# 1. Create a container (use media_type=REELS or STORIES for those formats)
curl -X POST "https://graph.instagram.com/v25.0/IG_ID/media" \
-d "image_url=https://example.com/photo.jpg" \
-d "caption=Hello from the API" \
-d "access_token=ACCESS_TOKEN"
# 2. Publish the container
curl -X POST "https://graph.instagram.com/v25.0/IG_ID/media_publish" \
-d "creation_id=CONTAINER_ID" \
-d "access_token=ACCESS_TOKEN"A few rules catch people out:
- JPEG only. Images have to be JPEG, so PNG uploads need converting first.
- No filters or shopping tags through the API.
- Video takes time. Video containers process before they can be published, and large files can use resumable upload.
- A 100-post cap. Each account can publish 100 posts through the API per rolling 24 hours. The pricing and limits post covers the rest.
If you're building posting into a product, Adeli's posting API replaces these two calls for feed posts, Reels, Stories, and carousels. One request publishes to Instagram and the other networks you've connected, and you get a per-platform status and a webhook when each one lands.
How do I get access to the Instagram API?#
Create a Meta app, add Instagram, and pass review for anything beyond your own accounts.
- Switch the account to professional. Business or Creator, and link a Facebook Page if you'll use Facebook Login.
- Create a Business-type app in the Meta App Dashboard and add the Instagram product.
- Choose a login and build it with the permissions your features need.
- Test with Standard Access on accounts you own or manage.
- Apply for Advanced Access. Complete Business Verification and submit each permission to App Review with a use case and a screencast.
Step 5 takes the longest. Our guide to how long Meta app review takes covers the timeline and the common rejections, and Is the Instagram API free? adds up the rest of the setup cost.
Should I build on the Instagram API or use a unified API?#
Build directly if Instagram is your only network and you have time for review. The API is free, and Meta's docs are clear once you know which login you need.
Use a unified API if you need other networks or want to skip the setup. Adeli maintains the Instagram developer app, goes through Meta's review, and refreshes every connected account's tokens. It publishes feed posts, Reels, Stories, and carousels to Instagram. Each of your users connects their own Instagram account, and the same request publishes to Instagram, TikTok, YouTube, Facebook, and X. You can also read post analytics and handle comments and messages through the same API. If you're using an AI agent rather than writing code, the Instagram MCP guide covers that route.
On Adeli's pricing, your first 3 connected accounts are free, with no credit card. Access starts with a short onboarding call, and then you get your API key.