Engineering

Instagram Graph API: the complete 2026 developer guide

A practical guide to Instagram's developer APIs: choose a login flow, obtain tokens, publish media, and handle permissions, analytics, messaging, and limits.

Instagram Graph API: the complete 2026 developer guide

The Instagram Graph API lets developers publish content, read insights, moderate comments, and handle messages for Instagram professional accounts. Meta now documents these capabilities under the Instagram Platform, with different login setups that determine your permissions, token type, and API host. Personal accounts are not supported, and the old Instagram Basic Display API is shut down.

TL;DR

  • Use a Business or Creator account, not a personal account.
  • Instagram API with Instagram Login does not require a Facebook Page. Instagram API with Facebook Login does.
  • As of November 2026, Meta also recommends Unified Login for new integrations. It is a distinct setup, not another name for Instagram Login.
  • Publishing means creating a media container, checking readiness, then publishing it.
  • Instagram Login long-lived tokens last 60 days and must be refreshed before expiration.
  • Outstand includes Instagram Managed Keys, so you can use its approved Meta app instead of obtaining approval for your own app.

What is the Instagram Graph API today?

“Instagram Graph API” remains a useful search term, but it is not enough to identify an integration. Meta's current Instagram Platform overview describes three setups:

Setup

Facebook Page required?

API host

Token family

Instagram API with Instagram Login

No

graph.instagram.com

Instagram User

Instagram API with Facebook Login

Yes

graph.facebook.com

Facebook User or Page, depending on endpoint

Instagram API with Unified Login

No; business portfolio required

graph.facebook.com

Business Integration System User

All serve professional accounts. Instagram Login is useful for integrations that already onboard people directly through Instagram. Facebook Login remains relevant for existing Page-linked integrations and capabilities such as hashtag search and product tagging that Instagram Login does not support.

Meta recommends Unified Login for new integrations. Evaluate it against your asset and business-portfolio requirements rather than assuming an older Facebook Login tutorial describes it correctly. The raw tutorial below intentionally uses Instagram Login, with an Instagram User token and graph.instagram.com throughout.

Keep the login method, host, token type, and account ID together in your connection model. Copying a token from one setup into requests for another is not a migration strategy.

What happened to the Instagram Basic Display API?

Meta shut down Instagram Basic Display API on December 4, 2024. Requests to that retired API no longer work.

The replacement for supported business use cases is the Instagram Platform, not a renamed personal-account API. A user who previously authorized a personal account must move to a professional account and complete a supported authorization flow. There is no drop-in token conversion that preserves Basic Display access for personal accounts.

Also, graph.instagram.com is not itself deprecated. Current Instagram Login integrations use that host. The retired product and the hostname are different things.

Account requirements, permissions, and App Review

Start with an Instagram Business or Creator account. For Facebook Login, link it to a Facebook Page and ensure the authorizing person has the necessary Page tasks. A linked Page is not a universal Instagram API requirement.

Request permissions for the features you ship

For Instagram Login, use the following permission names. The publishing and messaging requirements are documented in Meta's publishing guide and Send Messages guide; analytics has its own requirement below.

Capability

Instagram Login permission

Basic account access

instagram_business_basic

Publish content

instagram_business_content_publish

Moderate comments

instagram_business_manage_comments

Read insights

instagram_business_manage_insights

Send and receive messages

instagram_business_manage_messages

Facebook Login uses a different family: instagram_basic, instagram_content_publish, instagram_manage_comments, and instagram_manage_insights, with applicable Page permissions. Publishing requires pages_read_engagement; discovery commonly uses pages_show_list. Additional permissions can depend on how the person received their Page role. Check the endpoint's requirements rather than treating this as one universal scope string.

Old tutorials using Instagram Login scopes such as business_basic are stale. Meta's Business Login guide says those older scope values were deprecated on January 27, 2025.

Standard Access is not customer-facing approval

According to Meta's overview, Standard Access covers accounts you own or manage within the documented app-role setup. Serving professional accounts you do not own or manage requires Advanced Access, App Review, and Business Verification.

Prepare a working review flow, reviewer instructions, test access, a privacy policy, and a recording showing why each requested permission is necessary. Test the actual customer journey, not only an administrator token generated in the dashboard. Do not promise a fixed approval time in your launch plan.

Instagram Graph API access tokens

For Instagram Login, the documented flow is:

  1. Send the account owner through authorization with the requested scopes and a validated state value.
  2. Exchange the single-use authorization code at https://api.instagram.com/oauth/access_token on your server.
  3. Exchange the short-lived token at https://graph.instagram.com/access_token using grant_type=ig_exchange_token and your Instagram app secret.
  4. Store the long-lived token, granted permissions, account ID, and returned expiration securely.
  5. Refresh the long-lived token before it expires.

Meta's overview specifies a one-hour short-lived token and a 60-day long-lived token. Its Instagram Login documentation requires a token to be at least 24 hours old and still valid before refresh:

bash
1curl --get 'https://graph.instagram.com/refresh_access_token' \
2  --data-urlencode 'grant_type=ig_refresh_token' \
3  --data-urlencode "access_token=$IG_ACCESS_TOKEN"

The refreshed token is valid for another 60 days. An expired token cannot be revived with this endpoint; reconnect the account. Use the returned expires_in, schedule refresh with a safety margin, and alert when refresh fails. Redact token-bearing URLs from logs.

Do not apply ig_refresh_token to Facebook User, Page, or Unified Login system-user tokens. Their lifecycle depends on their own authorization setup. For the Page-linked path, see our Facebook and Instagram token guide.

Instagram Graph API tutorial: publish a photo with curl

This minimal example follows Meta's content publishing flow. It assumes you already have an Instagram Login token with publishing access and the corresponding professional account ID.

Set GRAPH_VERSION to a version supported by your app. Use a publicly reachable JPEG URL; Meta must fetch the bytes without your application's cookies or authorization headers.

bash
1export GRAPH_VERSION='v27.0'
2export IG_USER_ID='YOUR_INSTAGRAM_PROFESSIONAL_ACCOUNT_ID'
3# Set IG_ACCESS_TOKEN securely in your server environment.
4
5curl -sS -X POST \
6  "https://graph.instagram.com/$GRAPH_VERSION/$IG_USER_ID/media" \
7  -H "Authorization: Bearer $IG_ACCESS_TOKEN" \
8  --data-urlencode 'image_url=https://example.com/photo.jpg' \
9  --data-urlencode 'caption=Published through the Instagram API'

The response contains the container ID, not the published post ID. Copy it into IG_CONTAINER_ID, then check readiness:

bash
1export IG_CONTAINER_ID='CONTAINER_ID_FROM_PREVIOUS_RESPONSE'
2
3curl -sS --get \
4  "https://graph.instagram.com/$GRAPH_VERSION/$IG_CONTAINER_ID" \
5  -H "Authorization: Bearer $IG_ACCESS_TOKEN" \
6  --data-urlencode 'fields=status_code'

Publish when status_code is FINISHED:

bash
1curl -sS -X POST \
2  "https://graph.instagram.com/$GRAPH_VERSION/$IG_USER_ID/media_publish" \
3  -H "Authorization: Bearer $IG_ACCESS_TOKEN" \
4  --data-urlencode "creation_id=$IG_CONTAINER_ID"

Store the returned published media ID. If a request times out, reconcile container status before repeating publication. A network timeout is not proof that Instagram rejected the post.

Images, carousels, Reels, and Stories

The container workflow stays similar, but the parameters change:

  • Image: create a container with image_url and an optional caption.
  • Carousel: create image or video child containers with is_carousel_item=true, then a parent with media_type=CAROUSEL and children containing their IDs. Publish the parent.
  • Reel: create a container with media_type=REELS and video_url. Wait for processing before publishing.
  • Story: create a container with media_type=STORIES and an image or video URL. Do not assume native Instagram stickers are available through the API.

Meta's media reference permits up to 20 carousel items and specifies JPEG images up to 8 MB. Video requirements differ between Reels, Stories, and carousel children, so validate against the target format. Our Reels and Stories API guide covers those workflows in more detail.

Core endpoints beyond publishing

Read media and insights

Use GET /{ig-user-id}/media to retrieve the authorized account's media, not an arbitrary personal account's feed. Follow pagination and select only needed fields. See getting Instagram posts through the API.

Account analytics uses GET /{ig-user-id}/insights; media analytics uses GET /{ig-media-id}/insights. Meta's account insights reference requires instagram_business_manage_insights for Instagram Login. Choose compatible metrics, periods, and breakdowns. Account impressions was retired in favor of views; copying an old analytics query can break an otherwise valid integration.

An empty insights dataset is not necessarily zero engagement. Meta explicitly distinguishes unavailable data from zero and documents delays of up to 48 hours.

Moderate comments and handle messages

Meta's comment moderation guide documents GET /{ig-media-id}/comments, POST /{ig-comment-id}/replies, comment deletion, and hide/unhide operations. Prefer comment webhooks over constant polling.

For Instagram Login messaging, use POST /{ig-user-id}/messages with an Instagram-scoped recipient ID and message payload. Subscribe to the appropriate message webhooks. This is not an unrestricted cold-DM endpoint: Meta's messaging guide requires an eligible user interaction and an applicable messaging window, normally 24 hours for ordinary inbound messages. See our Instagram DM API guide for implementation details.

Rate limits and publishing quotas

There are separate budgets for publishing, container creation, and API calls. Do not collapse them into “200 requests per hour.”

Limit

Current official documentation

API-published posts

100 per account in a rolling 24-hour period; a carousel counts as one

Container creation

400 containers per account in a rolling 24-hour period

Container expiration

24 hours after creation

General Instagram Platform calls, excluding messaging

Documented BUC formula: 4,800 multiplied by impressions in the last 24 hours, per app/account pair

Conversations API

2 calls per second per professional account

Sources: Meta's publishing guide, media reference, and rate-limit documentation, checked November 17, 2026.

There is a documentation inconsistency: the publishing guide's main rate-limit section says 100, while its carousel subsection still says 50. Query GET /{ig-user-id}/content_publishing_limit for current account usage and quota configuration instead of hardcoding assumptions. Track returned usage headers and throttle errors as well. Messaging has separate endpoint-specific budgets.

Create containers near execution time, not when someone schedules a post weeks ahead. Use per-account queues, bounded retries, and backoff. A carousel consumes one published-post slot but needs multiple containers.

Common errors and what to check

Symptom

First checks

Authorization code rejected

Code already used or expired; redirect URI differs between authorization and exchange

Permission denied

Wrong scope family, missing consent, missing Advanced Access, or insufficient Page task

Media cannot be fetched

URL requires authentication, expired, or returns something other than the media bytes

Container is IN_PROGRESS

Processing is unfinished; wait before publishing

Container is ERROR or EXPIRED

Inspect failure details or create a new valid container

Throttling

Check publishing usage and API usage separately; stop immediate retries

Insights query fails

Deprecated metric or incompatible period/breakdown combination

Preserve the upstream error code, subcode, and trace ID where provided, without storing tokens. Meta's publishing guide recommends checking container status once per minute for no more than five minutes, rather than running a tight polling loop.

How Outstand fits

Outstand is useful when Instagram is one destination inside a broader publishing product. Instagram is a Managed Keys network: your subscription includes Outstand's Meta app, so you do not need to register and submit your own app to publish through that managed integration. Optional BYOK is available for your own app credentials.

You still need an eligible account and the owner's authorization. Managed Keys does not remove Instagram's content rules, quotas, or messaging restrictions.

The request below uses the container schema documented by Outstand's create-post endpoint and the published Instagram Reel-cover example:

bash
1curl -X POST https://api.outstand.so/v1/posts \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "content": "Our new product in 30 seconds",
6    "accounts": ["YOUR_INSTAGRAM_ACCOUNT_ID"],
7    "containers": [
8      {
9        "content": "Our new product in 30 seconds",
10        "media": [{ "url": "https://example.com/reel.mp4", "filename": "reel.mp4" }]
11      }
12    ],
13    "instagram": {
14      "reelCoverUrl": "https://example.com/reel-cover.jpg"
15    }
16  }'

Use the connected Outstand account ID, not the string instagram or Meta's raw account ID. In production, use the media URL returned by Outstand's confirm-upload step. Omit scheduledAt to publish immediately or supply a future ISO 8601 timestamp to schedule. Instagram-specific options belong at the top-level instagram key.

Direct Messages are separately opt-in and require requesting the messaging scope when connecting. The Instagram configuration docs describe the supported setup. Do not assume Meta's newer Unified Login is available through Outstand merely because Meta documents it.

FAQ

Can I use the Instagram Graph API with a personal account?

No. Current account-management integrations require a professional Business or Creator account. Basic Display's shutdown did not leave a supported personal-account replacement.

Do I need a Facebook Page?

For Instagram API with Facebook Login, yes. Instagram Login does not require one. Unified Login also removes the Page requirement but has its own business-portfolio setup.

How do I get an Instagram Graph API access token?

Complete authorization for your selected login setup. With Instagram Login, exchange the code for a short-lived token, then exchange that server-side for a long-lived token.

Can I refresh an expired Instagram access token?

Not through Instagram Login's refresh endpoint. Refresh a valid long-lived token after it is at least 24 hours old and before expiration. Otherwise, reconnect.

Can the API publish Reels, Stories, and carousels?

Yes, through their respective media-container flows. Validate format-specific requirements, check readiness, and publish the container. Native app editing features are not automatically API features.