Did you know? Meta deprecated the Basic Display API specifically to restrict third-party access to personal Instagram accounts, tightening control over data access and prioritizing business accounts over consumer applications.
Instagram operates as one of the world’s largest visual social networks with over 2 billion monthly active users. Behind this massive ecosystem lies a sophisticated set of APIs that power everything from content management tools to analytics dashboards. The Instagram Graph API is the primary interface for developers, businesses, and creators who need programmatic access to Instagram data and functionality.
With the deprecation of the Basic Display API completed, all Instagram integrations must now use either the Instagram Graph API or Instagram Messaging API. This guide walks you through the entire ecosystem, from authentication to optimization strategies, so you can build efficient, scalable applications.
- How Instagram’s rate limiting and Business Use Case logic works
- Available endpoints and what operations each supports
- Step-by-step authentication setup for both business login methods
- Real-world implementation patterns for common use cases
- Optimization techniques to maximize your rate limits
Understanding your use case is the first step. Let’s explore the key concepts, beginning with common applications of the Instagram Graph API.
Where Is Instagram Graph API Applied?
The Instagram Graph API serves multiple developer communities, each with distinct use cases and requirements.
Product Developers
When you’re building SaaS solutions that leverage Instagram content, the Instagram Graph API is your foundation. Whether creating social media management platforms, influencer marketing tools, content curation services, or analytics dashboards, the API provides structured access to Instagram’s data infrastructure.
Social Media Agencies & Consultants
Agencies managing multiple client accounts use the Graph API to pull performance data, schedule content across accounts, track campaign metrics, and generate automated reports without having to log into each client’s Instagram account individually.
Content Creators & Studios
Professional creators and content studios integrate the Graph API to automate bulk uploads, manage metadata across videos, track performance trends over time, coordinate with team members, and extract insights for content strategy decisions. The API enables creators to focus on content creation rather than platform mechanics.
E-Commerce Businesses
Businesses with Instagram Shops use the Graph API to manage product tags, track shoppable post performance, sync catalog data, and monitor conversion metrics. The API bridges the gap between Instagram’s native commerce features and external inventory management systems.
Research & Analytics Platforms
Researchers, market analysts, and data scientists leverage the Instagram Graph API for large-scale studies. You can analyze trends, study audience demographics, track engagement patterns, and conduct content analysis across thousands of accounts – no need for extensive manual collection.
Understanding Instagram Graph API Authentication
Before making any API requests, you must authenticate. The Instagram Graph API supports two authentication approaches, each designed for different scenarios and use cases.
🎯 Method 1: Business Login (Instagram API with Instagram Login)
The Business Login approach uses OAuth 2.0 to authenticate users directly through Instagram. This method generates Instagram User access tokens that represent a specific Instagram Business or Creator account’s permissions.
When to use
- Building apps where users authenticate directly through Instagram
- Accessing data from a single specific Instagram account
- Scenarios where you want minimal Facebook infrastructure involvement
- Mobile apps or consumer-facing applications
How it works
- User initiates login in your app
- Your app redirects to Instagram’s authorization endpoint
- User authenticates and grants permissions
- Instagram returns an authorization code
- Your app exchanges the code for a short-lived access token
- You exchange the short-lived token for a long-lived token (60-day expiration)
Required permissions:
instagram_basic — Read basic Instagram profile and media data instagram_graph_user_profile — Access to user profile information instagram_manage_messages — If managing direct messages
🔗 Method 2: Facebook Login for Business (Instagram API with Facebook Login)
The Facebook Login approach uses Instagram accounts that are connected to Facebook Pages. This method is more common for enterprise applications and integrations with Facebook’s ecosystem.
When to use
- Building platform solutions managing multiple client accounts
- Integrating with Facebook Pages (which often manage Instagram accounts)
- Enterprise applications with centralized account management
- Systems where Instagram accounts are managed through Business Manager
How it works
- Create a Facebook app in Facebook Developers
- Add required permissions:
pages_show_listbusiness_managementinstagram_basic - User connects their Instagram Business account to a Facebook Page
- Retrieve the connected Instagram account ID from the Page
- Use that ID to generate access tokens
Requirements
- Instagram account must be a Business or Creator account
- Instagram account must be connected to a Facebook Page
- User must have admin access on the connected Facebook Page
📊 Comparison: Which Authentication Method?
To help you choose, here’s a detailed comparison of how these two approaches differ across key dimensions:
| Feature | Business Login | Facebook Login |
|---|---|---|
| Setup complexity | Moderate | Higher |
| Best for | Single account, user-facing apps | Multi-account, enterprise tools |
| Token source | Direct Instagram OAuth | Facebook Page connection |
| Permissions required | 3-4 Instagram-specific scopes | 3+ Facebook + Instagram scopes |
| Account linking | Direct | Via Facebook Page |
| Token lifespan | 60 days (long-lived) | 60 days (long-lived) |
Choose Business Login for simplicity with single accounts, or Facebook Login if you’re managing multiple client integrations.
Understanding Instagram Rate Limiting & Business Use Case Logic
The Instagram Graph API uses a Business Use Case (BUC) rate limiting system that differs significantly from standard rate limiting. Understanding this system prevents your application from hitting limits unexpectedly.
📄 Basic Rate Limit Structure
The Instagram Graph API enforces the following rate limits:
200 requests per hour per user
This means that for each unique Instagram account you’re accessing data for, your app can make up to 200 API calls within any one-hour window. If you have 10 Instagram accounts connected, your total capacity increases to 2,000 requests per hour (200 × 10).
Key implications
- Each Instagram account has an isolated rate limit pool. Multiple API keys within the same app don’t share limits with accounts
- The limit resets hourly, not daily. However, the hourly window is rolling—every API call advances the window forward by one hour
- All requests count toward the limit, whether they succeed or fail. An invalid request still consumes your rate limit
- Pagination counts as separate requests. Fetching 5 pages of comments uses 5 of your 200 hourly requests
- Rate limit is tied to the app, not the authenticated user. All users of your app share the same pool for a given Instagram account
How Business Use Case Rate Limiting Works
Unlike standard rate limiting, Instagram’s BUC system calculates limits based on the account’s characteristics and engagement level:
Formula: 200 requests per hour per Instagram User
The base allocation is fixed at 200 requests per hour. However, Meta notes that this allocation may be adjusted based on:
- Application behavior and compliance history
- Account activity patterns
- Type of operations being performed
- Volume of data being accessed
This system is designed to prevent abuse while allowing legitimate applications to operate at scale.
Rate Limit Headers & Monitoring
Most API responses include the following header:
X-Business-Use-Case-Usage: { "ig_api_usage": [ { "acc_id_util_pct": 50, "reset_time_duration": 3600 } ] } Parse these headers to monitor your rate limit consumption:
acc_id_util_pct — Percentage of your hourly limit you’ve consumed (0-100)
reset_time_duration — Seconds until your rate limit counter resets
Implementation tip: When acc_id_util_pct reaches 80-90%, implement exponential backoff and queue remaining requests for the next hour. Never let it reach 100%.
What Can You Actually Do With 200 Hourly Requests?
The quota might seem limiting, but it depends entirely on how efficiently you design your API usage. Here are realistic scenarios:
Scenario 1: Multi-Account Dashboard
- Retrieve 5 accounts’ basic info: 5 requests
- Get recent 20 posts per account: 5 requests
- Get engagement metrics per post: 100 requests (20 posts × 5 accounts)
- Hourly usage: ~110 requests | Capacity: Can refresh dashboard 1-2 times per hour
Scenario 2: Real-Time Comment Monitoring
- Check for new comments every 5 minutes: 12 requests per hour
- Fetch 50 comments per check: 12 requests
- Get comment author details: 24 requests
- Hourly usage: ~48 requests | Capacity: Monitoring system runs all day with overhead
Scenario 3: Lightweight Feed Display
- Retrieve 10 posts from an account: 1 request
- Get basic captions and engagement: 1 request (included in response)
- Display on website: No additional requests
- Hourly usage: ~2 requests per page view | Capacity: Can support thousands of page views per hour
🔌 Instagram Graph API Endpoints & Capabilities
The Instagram Graph API provides multiple sets of endpoints, each serving specific purposes. Understanding what operations each supports is crucial for application design.
Core Endpoint Categories
Media Management
Retrieve, analyze, and publish media content from Instagram Business and Creator accounts.
Supported operations:
GET /{ig-user-id}/media — List all media (photos, videos, reels) for an accountGET /{ig-media-id} — Retrieve single media object with metadataGET /{ig-media-id}/media_product_tags — Get product tags on media (commerce)POST /{ig-user-id}/media — Create media container for publishingPOST /{ig-user-id}/media_publish — Publish media after container status is FINISHEDGET /{ig-user-id}/media?fields=id,caption,media_type,media_url,permalink,timestamp
Comment Management
Retrieve, reply to, and moderate comments on media.
Supported operations:
GET /{ig-media-id}/comments — List comments on a media objectGET /{ig-comment-id}/replies — Get replies to a specific commentPOST /{ig-media-id}/comments — Post a comment to a media object (requires permission)POST /{ig-comment-id}/replies — Reply to a specific commentPOST /{ig-comment-id}?fields=hidden&hidden=true — Hide inappropriate commentsDELETE /{ig-comment-id} — Delete your own comments
Insights & Analytics
Access detailed performance metrics about media, accounts, and audience behavior.
Supported operations:
GET /{ig-media-id}/insights — Media-level metrics (impressions, reach, saves, video views)GET /{ig-user-id}/insights — Account-level metrics (audience size, reach, impressions)
Accessible metrics: impressions, reach, engagement, saves, shares
Hashtag Search
Find publicly available Instagram media tagged with specific hashtags.
Supported operations:
GET /ig_hashtag_search?user_id={ig-user-id}&hashtag={hashtag_name} — Get hashtag node IDGET /{ig-hashtag-id}/top_media — Get top posts for a hashtagGET /{ig-hashtag-id}/recent_media — Get recent posts for a hashtagGET /{ig-user-id}/recently_searched_hashtags — Get hashtags searched in past 7 days
Rate limiting note: You can search up to 30 unique hashtags per week per Instagram account. After 7 days, the limit resets for previously searched hashtags.
Business Discovery
Get metadata and statistics about other Instagram Business and Creator accounts.
Supported operations:
GET /{ig-user-id}?fields=business_discovery.username({target_username}){id,followers_count,media_count,biography,website,username} — Discover business account data
Returns: follower count, media count, bio, website, verified status
Mentions & Tags
Find media where your account has been @mentioned by other users.
Supported operations:
GET /{ig-user-id}/mentioned_comment — Get comments where account was @mentionedGET /{ig-user-id}/mentioned_media — Get posts where account was @mentioned
Returns: comment text, author info, timestamp
Supported Resource Types & Operations
Not all resources support the same operations. Here’s a complete breakdown of what you can do with each Instagram resource type:
| Resource | List | Create | Update | Delete | Purpose |
|---|---|---|---|---|---|
| IG User | ✓ | ✗ | ✗ | ✗ | Account profile and basic info |
| IG Media | ✓ | ✓ | ✗ | ✗ | Photos, videos, reels, carousels |
| IG Comment | ✓ | ✓ | ✗ | ✓ | Comments on media (moderation) |
| IG Insight | ✓ | ✗ | ✗ | ✗ | Performance metrics (read-only) |
| IG Hashtag | ✓ | ✗ | ✗ | ✗ | Hashtag search and discovery |
| IG Story | ✓ | ✗ | ✗ | ✗ | Story data (limited access) |
| IG Mention | ✓ | ✗ | ✗ | ✗ | @mentions and tags (read-only) |
Use this matrix as a reference when planning your integration, preventing attempts at operations that the API simply doesn’t support.
Setting Up Instagram Graph API Authentication: Step-by-Step
Let’s walk through both authentication flows step-by-step so you have a working token and can start making API calls immediately.
🔑 Getting Started With Business Login
Step 1: Create a Meta Developer App
Navigate to https://developers.facebook.com and create a new app. Select “Business” as the app type when prompted.
Step 2: Add Instagram Product
- In your app dashboard, click “Add Products”
- Find “Instagram Graph API” and click “Set up”
- This adds Instagram as an available product in your app
Step 3: Generate Access Token
Use the Graph API Explorer or SDK to generate a token:
GET /oauth/authorize ?client_id={YOUR_APP_ID} &redirect_uri={YOUR_REDIRECT_URI} &response_type=code &scope=instagram_basic,instagram_graph_user_profile After user authorization, exchange the code for a token:
POST /oauth/access_token ?client_id={YOUR_APP_ID} &client_secret={YOUR_APP_SECRET} &grant_type=authorization_code &code={AUTHORIZATION_CODE} &redirect_uri={YOUR_REDIRECT_URI}
Step 4: Exchange for Long-Lived Token
The token you receive is short-lived (typically 1 hour). Exchange it for a long-lived token (60 days):
GET /access_token ?grant_type=ig_exchange_token &client_secret={YOUR_APP_SECRET} &access_token={SHORT_LIVED_TOKEN}
Getting Started With Facebook Login for Business
Step 1: Connect Instagram to Facebook Page
- Go to your Instagram Business account
- Open Profile → Edit Profile
- Under “Professional Dashboard,” find “Page” and click “Connect or create a Facebook Page”
- Select or create your Facebook Page
Step 2: Create Meta Developer App
Follow the same app creation process as Business Login, but configure it specifically for Facebook Login.
Step 3: Configure Permissions
In your app configuration, request these permissions:
pages_show_list — Access your list of Facebook Pages
business_management — Manage business and accountsinstagram_basic — Basic Instagram access
Step 4: Retrieve Instagram Account ID
GET /{FACEBOOK_PAGE_ID} ?fields=instagram_business_account &access_token={PAGE_ACCESS_TOKEN} This returns the connected Instagram Account ID you’ll use for API calls.
Step 5: Generate Instagram Tokens
Once you have the Instagram Account ID, use it to access Instagram endpoints and generate account-specific tokens.
🔄 Token Lifecycle & Refresh
Long-lived tokens expire after 60 days of non-use. However, they can be refreshed anytime after 24 hours of being issued.
Refresh a token:
GET /refresh_access_token ?grant_type=ig_refresh_token &access_token={LONG_LIVED_TOKEN} Best practices:
- Store tokens securely (encrypted in database, never in frontend code)
- Implement token refresh logic to refresh every 50-55 days automatically
- Set up alerts when tokens are about to expire
- Never hard-code tokens in your application
Common Implementation Patterns
Below are the most common tasks you’ll perform with the Instagram Graph API. These patterns form the foundation for most production integrations.
💻 Retrieving Media Insights
Pull engagement data for recent posts:
GET /{ig-user-id}/media ?fields=id,caption,media_type,timestamp &access_token={LONG_LIVED_TOKEN} For each media ID returned, get insights:
GET /{media-id}/insights ?metric=impressions,reach,engagement,saves &access_token={LONG_LIVED_TOKEN}
💬 Managing Comments
Fetch recent comments on a post:
GET /{media-id}/comments ?fields=id,text,username,timestamp,user &access_token={LONG_LIVED_TOKEN} Reply to a comment:
POST /{media-id}/comments ?message={REPLY_MESSAGE} &access_token={LONG_LIVED_TOKEN} Hide an inappropriate comment:
POST /{comment-id} ?hidden=true &access_token={LONG_LIVED_TOKEN}
📇 Publishing Content
The content publishing process uses “containers.” First create a container, monitor its status, then publish:
POST /{ig-user-id}/media ?image_url={IMAGE_URL} &caption={CAPTION} &access_token={LONG_LIVED_TOKEN} Check container status:
GET /{container-id} ?fields=status_code &access_token={LONG_LIVED_TOKEN} Publish when status is FINISHED:
POST /{ig-user-id}/media_publish ?creation_id={CONTAINER_ID} &access_token={LONG_LIVED_TOKEN}
🔖 Searching by Hashtag
Find posts tagged with a specific hashtag:
GET /ig_hashtag_search ?user_id={ig-user-id} &hashtag={HASHTAG_NAME} &access_token={LONG_LIVED_TOKEN} This returns a hashtag node ID. Then retrieve posts:
GET /{hashtag-id}/recent_media ?fields=id,caption,media_type,timestamp &access_token={LONG_LIVED_TOKEN}
Optimization Strategies: Reduce API Calls & Stay Within Rate Limits
With only 200 requests per hour per account, optimization isn’t optional—it’s essential for scalability.
1. Request Only Necessary Fields
By default, many endpoints return extensive data. Use the fields parameter to request only what you need:
Instead of:
GET /{media-id} Use:
GET /{media-id}?fields=id,caption,timestamp,media_url This reduces response size, improves latency, and shows Meta that you’re being thoughtful about data usage.
2. Implement Intelligent Caching
Cache API responses with appropriate TTL (time-to-live):
- Static content (captions, post URLs): 24 hours
- Engagement metrics (likes, comments): 1-6 hours
- Real-time data (live comments): 5-30 seconds
Caching benefit: A dashboard that previously required 50 API calls per refresh can drop to 10 calls with caching, freeing up 40 requests for other operations.
3. Batch Requests When Possible
Some endpoints allow multiple IDs in one request:
GET / ?ids={id1},{id2},{id3} &fields=id,caption,engagement &access_token={TOKEN} This fetches 3 media objects with 1 API call instead of 3. Always batch when the API supports it.
4. Paginate Efficiently
Instagram returns paginated results with cursor-based pagination. Fetch only the data you need:
GET /{media-id}/comments ?limit=50 &after={PAGINATION_CURSOR} &access_token={TOKEN} Set limit to match your needs (50-100 is typical). Avoid fetching all available data if you only need recent items.
5. Use Webhooks for Real-Time Updates
Instead of polling the API repeatedly to check for new comments or mentions, subscribe to webhooks. When events occur, Instagram pushes notifications to your endpoint. This reduces API calls from continuous polling to only event-driven requests.
POST /app/webhooks
Supported events:
- Comments (new comments on posts)
- Mentions (@mentions of your account)
- Story Insights (story performance updates)
- Messages (direct message notifications)
6. Implement Exponential Backoff for Retries
When rate limits are hit (429 error), don’t immediately retry. Instead, wait with exponential backoff:
wait_time = initial_wait * (2 ^ attempt_number)
Attempt 1: Wait 1 second Attempt 2: Wait 2 seconds Attempt 3: Wait 4 seconds Attempt 4: Wait 8 seconds
This prevents hammering the API and gives your quota time to reset.
Instagram Basic Display API Deprecation & Migration
While the deprecation deadline has passed, many developers still have legacy integrations to migrate. Understanding what changed and why will help you plan your transition smoothly.
🔍 What Changed?
On December 4, 2024, the Instagram Basic Display API reached end-of-life. This API previously allowed read-only access to personal Instagram accounts through a simple OAuth flow. After this date, it no longer functions.
Key changes
- Personal Instagram accounts are no longer supported via third-party APIs
- Only Business and Creator accounts can connect to applications
- All integrations must migrate to Instagram Graph API
- Basic Display API tokens no longer generate or function
Impact & Migration Path
Who was affected:
- Applications displaying personal Instagram feeds on websites
- Social media aggregation tools
- Portfolio services showing Instagram content
- Any integration using the Basic Display API’s User Token Generator
Migration steps:
- Convert personal Instagram accounts to Business or Creator accounts
- Link Instagram account to a Facebook Page
- Update your application to use Instagram Graph API endpoints
- Request new permissions through Meta App Review if building public services
- Test thoroughly before the deprecation deadline
🚀 Advanced Features & Specialized APIs
Beyond the core Graph API, Meta provides specialized APIs for specific use cases. If your application requires direct messaging, advertising management, or advanced content analysis, these complementary APIs extend your capabilities significantly.
Instagram Messaging API (via Messenger API)
Send and receive direct messages on behalf of business and creator accounts, enabling automated customer communication without manual intervention.
Supported operations:
- Send messages to customers
- Receive incoming messages with webhook notifications
- Manage multi-message conversations
- Send media files, quick replies, and templated messages
This API is ideal for building customer support platforms, chatbot integrations, order notifications, and automated response systems. Message throughput is separate from Graph API rate limits.
Instagram Ads API (via Marketing API)
Programmatically manage Instagram advertising campaigns and access detailed performance metrics for ads running on Instagram.
Capabilities include:
- Create and manage ad campaigns targeting Instagram users
- Access conversion tracking and audience insights
- Monitor ad performance metrics in real-time
- Automate bid optimization and budget allocation
The Ads API requires additional permissions and is primarily useful for agencies and platforms managing multiple advertising accounts. Rate limits are determined by your advertising account tier.
🔧 Handling Errors & Common Issues
Even well-designed integrations encounter errors. Here’s what you need to know to handle them gracefully.
Common Error Codes
When things go wrong, understanding error codes helps you debug quickly. Here are the most common errors you’ll encounter and how to resolve each one:
| Error Code | Type | Cause | Solution |
|---|---|---|---|
| 190 | OAuthException | Invalid access token | Token is expired, revoked, or invalid → Refresh token or re-authenticate |
| 200 | Permissions Error | Insufficient permissions | App doesn’t have required permissions for the operation → Request permission through Meta App Review or add required scope |
| 100 | Invalid Parameter | Malformed request | Missing required parameters or incorrect format → Log and fix request format |
| 429 | Rate Limited | Too many requests | Exceeded 200 requests per hour limit → Implement exponential backoff |
Always wrap API calls in try-catch blocks and parse error responses:
{ "error": { "message": "Invalid OAuth access token", "type": "OAuthException", "code": 190 } }
FAQ: Instagram Graph API Questions & Troubleshooting
Can I access personal Instagram accounts with Graph API?
What's the difference between Business Login and Facebook Login?
How long do access tokens last?
What happens if I exceed my rate limit?
Do all API calls count toward my rate limit?
How do I minimize API calls and stay within rate limits?
Need more help? Check the official Instagram Platform documentation or ask the Meta Developer Community for solutions from experienced developers.
📈 Best Practices: Building Reliable Instagram Integrations
The difference between a fragile integration and a production-ready system comes down to how you handle edge cases, rate limits, and security. These practices aren’t optional—they’re what separate successful integrations from those that fail under real-world conditions.
- Always use long-lived tokens. Short-lived tokens expire too quickly for reliable applications.
- Implement comprehensive error handling. Don’t assume API calls succeed; handle 429, 190, and other errors gracefully.
- Design for rate limits from day one. Build caching, batching, and webhooks into your architecture from the start.
- Store credentials securely. Never commit tokens to version control; use environment variables and encrypted storage.
- Monitor rate limit consumption. Set up alerts when approaching 80% of hourly quota.
- Test thoroughly in development mode. Meta apps start in development mode with limited capabilities; understand what changes when moving to live mode.
- Document your API usage. Keep records of which endpoints you use, how frequently, and for what purposes.
Following these practices from day one saves you from costly rewrites and emergency debugging sessions down the road. They’re not shortcuts – they’re the foundation of scalable, maintainable integrations.
Moving Forward
Whether you’re displaying Instagram feeds on websites, building social media management tools, or creating analytics platforms, the Instagram Graph API provides the foundation for all professional Instagram integrations. Start with the authentication method that fits your use case, implement optimization strategies early, and scale your application with confidence.
Stay informed about Graph API version releases and deprecations. Meta typically announces major changes with 90+ days notice, giving you time to migrate before deadlines take effect.
