The Ultimate Instagram API Documentation Guide

Trying to figure out which Instagram API to use can feel a bit confusing at first, but for nearly every developer today, the choice is actually pretty simple. The modern, full-featured Instagram Graph API is the go-to for businesses and creators, while the much older Instagram Basic Display API has been deprecated and offers very little in comparison.

Getting this right from the start is the first step toward building a solid integration.

Deciding Between the Graph API and Basic Display API

When you're building an app that needs to talk to Instagram, your first big decision is picking the right API. This choice will define everything—what data you can access, what actions you can perform, and which types of Instagram accounts your app will even work with.

For all practical purposes, the entire ecosystem now revolves around a single, powerful solution: the Instagram Graph API.

The Instagram Graph API is a robust, business-focused interface built for professional use. It’s what you need if you want to manage public media, moderate comments, pull detailed analytics, or publish content for Instagram Business and Creator accounts. This makes it the only real option for social media management tools, marketing apps, and analytics platforms.

On the other hand, the Instagram Basic Display API provides a tiny fraction of that functionality. It was designed for personal, non-business apps that only needed read-only access to basic profile info and media. Its capabilities are extremely limited—no publishing, no analytics, and no comment management.

Instagram API Feature Comparison

To make it crystal clear, here’s a quick breakdown of what each API offers. This table should help you see why the Graph API is almost always the right choice.

As you can see, the Graph API is built for just about any serious application, while the Basic Display API is a relic with very narrow, non-commercial use cases.

Key Functional Differences

Let’s boil it down. To choose the right API, think about what your app actually needs to do:

• Need to publish content, manage comments, or get analytics? The Graph API is your only option. It’s the only one with endpoints for posting media, viewing insights, and handling user engagement.
• Just need to display a user's photos on their personal blog? The Basic Display API can technically handle this, but that’s about all it can do.
• Building for businesses or content creators? You have to use the Graph API. It’s the only one that supports the features and data access that professional accounts rely on.

Starting with the Graph API from day one makes your application scalable and future-proof. If you build on the deprecated Basic Display API, you'll hit a wall fast and eventually be forced into a complete rewrite.

For almost any app being built today, the Instagram Graph API is the right tool for the job. If you're curious how Instagram's API stacks up against others, check out our guide on the top 10 social media APIs for developers.

Understanding Key API Updates and Deprecations

To build a stable, compliant application, you have to stay on top of API changes. The Instagram API has seen some major shifts over the years, moving away from older, less secure versions toward the much more robust and feature-rich Graph API. This evolution wasn't just for show—it brought better security, protected user privacy, and gave developers more powerful, streamlined tools to work with.

Knowing this history isn't just an academic exercise. It has a real impact on how you build or migrate your app, influencing everything from the authentication methods you use to the data you can actually access. Understanding why these changes happened will help you build future-proof integrations that play nicely with Instagram's long-term strategy.

The Shift Away from Legacy APIs

The biggest shake-up in the Instagram API documentation was the systematic retirement of older APIs. Both the original Legacy Instagram API and the more recent Basic Display API were phased out, with everything consolidating under the unified Instagram Graph API. This move was driven by a need for much stronger security and more fine-grained control over data permissions.

This transition is part of a larger trend in the industry toward APIs with clearer functions for specific user types. The Graph API, for instance, is built specifically for Instagram Business and Creator accounts. It delivers the deep analytics and content management features that professionals actually need.

By focusing all development on the Graph API, Meta was able to streamline its documentation, patch security holes tied to older authentication methods, and offer a single, powerful interface for anyone building professional-grade applications.

Key Deprecation Timelines and Impact

The retirement of Instagram's old APIs wasn't an overnight thing; it happened over several years. The process to shut down the Legacy Instagram API was a huge effort, finally wrapping up when Meta pulled the official legacy API documentation in June 2022. This move pushed all developers toward the new, comprehensive Instagram Platform documentation.

By August 19, 2024, all apps were required to be compliant with the new standards, which affected thousands of services. You can dig into the official changelog to learn more about these platform updates.

This structured deprecation gave developers a window to migrate their apps, but it also highlighted how important it is to stay informed. If you're using a unified API service, these transitions are often handled for you. For example, tools that offer a single endpoint, like the one covered in this guide to the Buffer API, manage these platform-specific updates so your integration doesn't break.

In the end, these updates have created a more secure and capable ecosystem. Developers now have a well-documented, powerful API designed for the needs of modern businesses and creators. This ensures that apps built on the platform are both reliable and respectful of user privacy, and the focus on a single, primary API makes new development a whole lot more straightforward.

A Practical Guide to Authentication and Permissions

Before you can make a single call to the Instagram Graph API, you need to handle authentication. This is the process that proves your app is who it says it is, and more importantly, that a user has given you permission to access their data. The whole exchange is built on the industry-standard OAuth 2.0 protocol.

It all starts when you register your application with Meta. Once you do, you'll get a unique App ID and App Secret. Think of these as your app's username and password—they're used to identify your application every time it communicates with the API.

It's absolutely critical to keep these credentials safe. Following proper secrets management best practices isn't just a recommendation; it's essential for preventing unauthorized access and protecting both your application and your users' private data.

This visual helps put the current API into context, showing the evolution from older, now-deprecated versions to the modern Graph API we use today. Understanding this history clarifies why the current authentication methods are so robust.

The platform has deliberately moved towards a more secure, powerful, and unified API. That's exactly why mastering the Graph API's authentication flow is non-negotiable for any developer in this space.

The OAuth 2.0 User Authorization Flow

At its heart, authentication is a multi-step dance between your app, the user, and Instagram's servers to get the user's explicit consent.

Here’s how it works in practice:

1. Generate an Authorization URL: Your app kicks things off by creating a special URL. This link sends the user to an Instagram authorization screen and includes your App ID, the specific permissions (scopes) you need, and a Redirect URI.

2. User Grants Permission: The user logs into Instagram and is shown a consent screen that clearly lists what your app wants to do. If they click "Allow," they're sent back to the Redirect URI you provided.

3. Exchange Code for Access Token: The magic happens here. The Redirect URI now has a short-lived authorization code attached to it. Your application needs to grab this code immediately and exchange it for a user access token. This token is the key that lets you make API calls on that user's behalf from now on.

This entire flow is designed to build trust. Users know exactly what they're agreeing to, and their privacy is respected. You'll find similar authentication patterns across most major platforms, like the one used for the YouTube Upload API.

Understanding Scopes and Permissions

Scopes are just simple strings that spell out the exact permissions your app is requesting. You can't just ask for blanket access to a user's account; you have to be specific about what you need and why. This is a core security principle known as "least privilege."

A quick heads-up from experience: Requesting only the permissions your app absolutely needs isn't just good practice—it's a requirement for passing Meta's App Review. Asking for too many scopes is one of the most common reasons for rejection.

Here are some of the most common scopes you'll encounter:

• instagram_basic: Lets you read a user's profile information and see their media. This is your starting point for most read-only actions.
• instagram_manage_comments: Grants the ability to post, hide, unhide, and delete comments on the user's media.
• instagram_content_publish: The big one. This scope is required to publish photos, videos, or carousels to an Instagram account.
• instagram_manage_insights: Unlocks access to user, post, and story insights. It's essential for any kind of analytics feature.

Each scope corresponds to specific API endpoints. You should always make sure the scopes you request line up perfectly with the features your app provides. This not only improves your chances of passing App Review but also gives your users a much clearer and more trustworthy experience.

A Comprehensive Graph API Endpoint Reference

This section is your go-to reference for the most common Instagram Graph API endpoints. We’ve structured it like a developer's cheat sheet, designed for quick lookups and easy implementation. Each entry breaks down exactly what you need to make a successful API call.

The Instagram API is becoming a cornerstone of marketing tech stacks everywhere. A 2024 industry report pointed out a 35% jump in businesses using the API for customer engagement over the last year. That kind of growth shows just how critical it is to get these endpoints right. You can read more about the rising adoption of Instagram's API on unipile.com.

User Endpoints

Think of User endpoints as your starting point. After you’ve handled authentication, these are often the first calls you'll make to get basic profile information and see the media tied to an Instagram Business or Creator account.

GET /{ig-user-id}

This is the bread-and-butter endpoint for pulling fields and edges on a specific Instagram user.

• HTTP Method:GET
• Required Permissions:instagram_basic, pages_show_list
• Common Parameters:
  • fields: A comma-separated list of the data you want back. Popular fields include id, username, media_count, followers_count, and profile_picture_url.

Example Request
GET graph.facebook.com/v19.0/17841405822304914?fields=id,username,media_count
&access_token={access-token}

Sample Response
{
"id": "17841405822304914",
"username": "example_user",
"media_count": 150
}

Media Endpoints

For anything related to photos, videos, carousels, or Reels, you'll be using the Media endpoints. They’re essential for fetching content details, checking performance metrics, and managing engagement.

GET /{ig-media-id}

Use this to get all the data and metrics for a single photo, video, or album.

• HTTP Method:GET
• Required Permissions:instagram_basic
• Common Parameters:
  • fields: A comma-separated list of fields like id, caption, media_type, media_url, permalink, timestamp, and like_count.

Example Request
GET graph.facebook.com/v19.0/17918921319012345?fields=id,caption,media_type,like_count
&access_token={access-token}

Sample Response
{
"id": "17918921319012345",
"caption": "Our latest product launch! #newproduct",
"media_type": "IMAGE",
"like_count": 1234
}

Pro Tip: When you're working with a CAROUSEL_ALBUM, you'll need to use the children edge to grab the individual images or videos inside it. It's a common oversight but crucial for displaying carousels correctly in your app.

Story Endpoints

Stories are a massive part of the Instagram experience, and the API lets you pull active stories and see how they're performing. Just remember, the media URLs for stories don't last long, so plan accordingly.

GET /{ig-user-id}/stories

This endpoint fetches a collection of all currently active stories for a user.

• HTTP Method:GET
• Required Permissions:instagram_basic, instagram_manage_insights
• Common Parameters:
  • fields: A comma-separated list specifying what to return for each story, like id, media_type, media_url, and timestamp.

Example Request
GET graph.facebook.com/v19.0/17841405822304914/stories?fields=id,media_url,timestamp
&access_token={access-token}

Sample Response
{
"data": [
{
"id": "18012345678901234",
"media_url": "https://scontent.xx.fbcdn.net/...",
"timestamp": "2024-05-21T18:30:00+0000"
}
],
"paging": { ... }
}

Comment Endpoints

For any social media management tool, handling comments is a core feature. The API gives you everything you need to read, post, and delete comments on your media.

POST /{ig-media-id}/comments

Use this endpoint to post a brand new comment or to reply to an existing one.

• HTTP Method:POST
• Required Permissions:instagram_manage_comments
• Common Parameters:
  • message: The text of your comment.
  • comment_id (optional): If you're replying to a specific comment, include its ID here.

Example Request (New Comment)
POST graph.facebook.com/v19.0/17918921319012345/comments?message=Love this!
&access_token={access-token}

Sample Response
{
"id": "17892345678901234"
}

This reference covers the endpoints you'll use most often, giving you a solid foundation for building apps that work with Instagram data. By combining these different calls, you can start creating some truly powerful and complex features.

Publishing Content with the API

If you're building an application that needs to post content programmatically, the Instagram Content Publishing API is where the action is. But a word of warning: it's not a simple, one-shot endpoint. Instagram enforces a specific, multi-step workflow to ensure that larger files, like videos, are handled reliably and all content is validated before it hits a user's profile.

Before you even start, make sure you have the instagram_content_publish permission. Without it, every attempt to create or publish media will flat-out fail. The whole process boils down to creating a "container" for your media, polling for it to be ready, and then making a final API call to actually publish it.

The Three-Step Publishing Workflow

Getting this right is crucial. Almost every developer who stumbles with this API misses a step in this sequence. To successfully post content, you always have to follow these three steps.

1. Create a Media Container: First, you hit the user's media edge with a POST request. You'll pass in the URL for your image or video, a caption, and other details like user tags. This call doesn't publish anything yet—it just registers your content with Instagram and gives you back a container ID.

2. Check Container Status: Once you have the container ID, you need to check on its upload status. This means making a GET request to that container's endpoint and looking at the status_code field. It'll probably say IN_PROGRESS at first. Your job is to keep polling this endpoint until the status flips to FINISHED.

3. Publish the Media Container: Finally, once the status is FINISHED, you can make the last call: a POST to the user's media_publish edge, passing in the container ID from the first step. This is the action that makes your content go live on the user's Instagram profile.

This structured workflow is designed to prevent timeouts and failures, which is especially important for big video files that can take a while to process on Instagram's end.

Handling Different Media Types

While that three-step process is the same for everything, the details of creating the container change depending on what you're posting. Each media type comes with its own set of rules and constraints.

• Single Photos: This is the easiest one. You just need to provide an image_url and an optional caption. The image has to be a JPEG and must fit within an aspect ratio of 4:5 to 1.91:1.

• Videos: For videos, you'll need a video_url and you must explicitly set the media_type parameter to VIDEO. Make sure your file is in MOV or MP4 format and meets all the duration, file size, and dimension limits found in the official Instagram API documentation.

• Carousels: This is where it gets a bit more involved. You have to create individual containers for each photo or video in the carousel first (without publishing them). Then, you create a final "carousel container" and pass the list of all the child container IDs in the children parameter.

Important Note: There's a ticking clock. Once a media container's status becomes FINISHED, you have exactly 24 hours to execute the final publishing call. If you wait any longer, the container expires, and you’ll have to start the entire process all over again.

By getting a handle on this multi-step workflow and the specific requirements for each media type, you can build solid, reliable publishing features. Of course, if you'd rather not deal with this complexity, Late's unified API abstracts this whole process into a single, straightforward API call, automatically managing the container creation, status polling, and publishing behind the scenes.

Managing Rate Limits and Common Errors

If you're building a serious application, you have to plan for the inevitable API limits and errors. The Instagram API, like any major service, relies on rate limiting to keep the platform stable and prevent abuse. Getting a handle on this system isn't just a suggestion; it’s a core part of building a reliable app that doesn't just crash on your users.

The Instagram Graph API calculates its limits on a sliding one-hour window, and these are applied at the app level. That means every API call your app makes for a single user counts toward the same limit. For most endpoints, you're looking at a cap of 200 calls per user per hour.

Best Practices for Rate Limit Management

It's always better to be proactive with your API calls than to constantly react to 429 errors. A few smart strategies can keep your app running smoothly and well within its limits, preventing any frustrating disruptions for your users.

• Cache Data Aggressively: Stop making the same API calls over and over for data that rarely changes. A user's profile, old media posts, and even follower counts are perfect candidates for caching. Just store this info locally for a reasonable amount of time to slash your request volume.
• Leverage Webhooks: Instead of polling Instagram every few minutes to check for new comments or mentions, use Instagram Webhooks. This flips the script: Instagram will ping you in real-time when an event happens, which is vastly more efficient than making endless GET requests.
• Implement Exponential Backoff: When you inevitably do hit a rate limit, don't just hammer the API by retrying the call immediately. That only makes things worse. Instead, implement an exponential backoff strategy, where you wait for progressively longer intervals between retries. This gives the system time to breathe and reset the limit.

Common Instagram API Error Codes and Solutions

Even with the best planning, errors are a fact of life. Knowing what the error codes mean and how to fix them is the difference between a quick fix and hours of painful debugging.

Here’s a quick rundown of some of the most common error codes you'll bump into when working with the Instagram API. Think of this as your first stop when something goes wrong.

Common Instagram API Error Codes and Solutions

Bookmark this table. When you see one of these codes, a quick look here can often point you directly to the cause and get you back on track without wasting much time.

Using Webhooks for Real-Time Data

Constantly asking a server "anything new yet?" is a terrible way to build an application. This process, called polling, is inefficient and wastes resources. A much smarter approach is to use webhooks, which let Instagram's servers tell your app the instant something important happens.

This real-time data flow is the secret sauce for building responsive, modern features. Instead of your app making hundreds of API calls just to check for new comments, Instagram can send a single notification straight to your server the moment a user posts one. It’s a push-based model that dramatically cuts down your API usage, keeping you safely under rate limits while delivering data immediately.

Setting Up Your Webhook Endpoint

The first step happens inside your Meta App Dashboard. You'll need to provide a secure, public callback URL—this is the digital address where your server will listen for notifications from Instagram. Think of it as the front door for all real-time updates.

Along with the URL, you'll need to create and provide a Verify Token. This is just a secret string of your choosing that Instagram uses to make sure it’s really you on the other end of that callback URL.

Subscribing to Webhook Topics

Once Instagram has verified your endpoint, you can subscribe to specific "topics." These topics are just the events you actually care about. You don’t have to get pinged for every little thing; you can pick and choose what’s relevant to your app.

Some of the most common topics include:

• comments: Get a notification every time a new comment is made on your media.
• mentions: Triggers whenever your Instagram Business Account gets an @mention in a comment or a caption.
• story_insights: Sends updates on Story performance metrics for real-time analytics.

Properly subscribing to these topics is a core part of a solid instagram api documentation implementation. It unlocks the power to react to user engagement as it happens. Beyond just publishing, the API is a powerful tool for analytics; you can explore different strategies for measuring social media engagement to really dial in your content strategy.

Verifying Incoming Notifications

Security is non-negotiable here. Since your endpoint is public, anyone could try sending a fake notification to it. You absolutely must verify that every single request comes from Instagram and not an imposter.

This is done by checking the X-Hub-Signature header that comes with every notification.

The signature is a SHA1 hash of the request's body, created using your App Secret as the key. Your server's job is to perform the exact same calculation and see if your result matches the signature in the header. If they don't match, you throw the request out.

This one step ensures the integrity and authenticity of the data you process, protecting your application from bad actors and malicious payloads. When you get webhooks right, you can build powerful, event-driven features that feel magical to users without ever hammering the API.

Frequently Asked Questions

Working with the Instagram API can be tricky, especially given its history of changes and deprecations. Here are some quick answers to the common questions and roadblocks developers hit along the way.

What Is the Difference Between the Graph API and Basic Display API?

Think of it this way: the Instagram Graph API is the heavy-duty toolkit for businesses and creators. It’s what you need to publish content, get detailed analytics, manage comments, and track mentions. It's the full-featured, professional option.

On the other hand, the Basic Display API was a much simpler, read-only tool for personal accounts. Its only job was to let users display their own photos and videos. It had none of the powerful management features of the Graph API.

Meta's direction is now crystal clear. They announced the deprecation of the Basic Display API on December 4, 2024, pushing developers toward the more secure and capable Graph API. This was a big shift, estimated to affect over 50% of apps that relied on the old API, forcing them to migrate or lose functionality. You can read the official notice in the platform changelog.

Why Am I Getting a Permission Denied Error?

If you've run into an error like (OAuthException - #10) This endpoint requires the 'instagram_manage_comments' permission, you're not alone. This is probably the most common hiccup developers face, and it almost always boils down to one thing: your app is missing the right scope.

Scopes are permissions that the user must grant your application. To fix it, you just need to update your authorization flow:

1. Find the Right Scope: Dig into the official Instagram API documentation for the endpoint you’re using and find out which permission it needs (e.g., instagram_content_publish for posting content).
2. Update Your Auth Request: Add that missing scope to your OAuth authorization URL.
3. Get the User to Re-Authenticate: The user will need to go through your app's connection process again to approve the new permission. Once they do, your app will get a fresh access token with the correct scopes attached.

How Can I Test My API Integration Before Going Live?

Meta has a great built-in system for this called App Roles, which you can find right in your App Dashboard. This is your sandbox for testing.

You can assign 'developer' or 'tester' roles to any Instagram account. Those accounts can then fully use your app’s integration while it’s still in "Development" mode, meaning before it has gone through the formal App Review process.

This is a critical step. It lets you test every part of your integration—API calls, authentication, webhooks—with real accounts in a safe environment. Once you’ve confirmed everything works perfectly, you can confidently submit your app for review to take it public.

Tired of juggling different social media APIs? Late offers a unified API that handles Instagram and nine other major platforms through a single, consistent interface. You can streamline your development and launch faster. Check out the docs and get started for free.