Instagram API

--- name: Instagram API description: Use when working with Instagram's API to manage posts, stories, media, and account data through the Instagram Platform API (formerly Instagram Basic Display API) metadata: author: skynet version: 1.0.0 category: social --- # Instagram API ## Prerequisites - Facebook Developer Account - Instagram Business or Creator Account - App registered on Facebook for Developers - Valid access tokens ## Authentication Setup ### Get App Access Token ```bash # Exchange authorization code for access token curl -X POST \ https://api.instagram.com/oauth/access_token \ -F client_id={app-id} \ -F client_secret={app-secret} \ -F grant_type=authorization_code \ -F redirect_uri={redirect-uri} \ -F code={authorization-code} ``` ### Generate Long-Lived Token ```bash curl -i -X GET "https://graph.instagram.com/access_token ?grant_type=ig_exchange_token &client_secret={app-secret} &access_token={short-lived-token}" ``` ## Media Management ### Get User Media ```bash # Get user's media feed curl -i -X GET \ "https://graph.instagram.com/{user-id}/media?fields=id,caption,media_type,media_url,permalink,thumbnail_url,timestamp&access_token={access-token}" # Get specific media details curl -i -X GET \ "https://graph.instagram.com/{media-id}?fields=id,caption,media_type,media_url,permalink,timestamp,username&access_token={access-token}" ``` ### Upload Media (Business API) ```bash # Upload single photo curl -X POST \ "https://graph.facebook.com/v18.0/{instagram-account-id}/media" \ -F "image_url={image-url}" \ -F "caption={caption-text}" \ -F "access_token={access-token}" # Upload video curl -X POST \ "https://graph.facebook.com/v18.0/{instagram-account-id}/media" \ -F "video_url={video-url}" \ -F "caption={caption-text}" \ -F "media_type=VIDEO" \ -F "access_token={access-token}" ``` ### Publish Media Container ```bash # Publish the media container curl -X POST \ "https://graph.facebook.com/v18.0/{instagram-account-id}/media_publish" \ -F "creation_id={creation-id}" \ -F "access_token={access-token}" ``` ## Stories Management ### Upload Story ```bash # Upload story photo curl -X POST \ "https://graph.facebook.com/v18.0/{instagram-account-id}/media" \ -F "image_url={image-url}" \ -F "media_type=STORIES" \ -F "access_token={access-token}" # Upload story video curl -X POST \ "https://graph.facebook.com/v18.0/{instagram-account-id}/media" \ -F "video_url={video-url}" \ -F "media_type=STORIES" \ -F "access_token={access-token}" ``` ## Account Information ### Get User Profile ```bash # Get basic profile info curl -i -X GET \ "https://graph.instagram.com/{user-id}?fields=id,username,account_type,media_count&access_token={access-token}" # Get detailed business account info curl -i -X GET \ "https://graph.facebook.com/v18.0/{instagram-business-account-id}?fields=biography,id,ig_id,followers_count,follows_count,media_count,name,profile_picture_url,username,website&access_token={access-token}" ``` ## Hashtag Research ### Search Hashtags ```bash # Search for hashtag ID curl -i -X GET \ "https://graph.facebook.com/v18.0/ig_hashtag_search?user_id={user-id}&q={hashtag-name}&access_token={access-token}" # Get hashtag info curl -i -X GET \ "https://graph.facebook.com/v18.0/{hashtag-id}?fields=id,name&access_token={access-token}" # Get top media for hashtag curl -i -X GET \ "https://graph.facebook.com/v18.0/{hashtag-id}/top_media?user_id={user-id}&fields=id,caption,media_type,media_url,permalink&access_token={access-token}" ``` ## Insights and Analytics ### Get Media Insights ```bash # Get insights for photo/video curl -i -X GET \ "https://graph.facebook.com/v18.0/{media-id}/insights?metric=impressions,reach,saved,video_views&access_token={access-token}" # Get story insights curl -i -X GET \ "https://graph.facebook.com/v18.0/{story-id}/insights?metric=impressions,reach,replies&access_token={access-token}" ``` ### Get Account Insights ```bash # Get account insights curl -i -X GET \ "https://graph.facebook.com/v18.0/{instagram-business-account-id}/insights?metric=impressions,reach,profile_views&period=day&since={start-date}&until={end-date}&access_token={access-token}" # Get audience insights curl -i -X GET \ "https://graph.facebook.com/v18.0/{instagram-business-account-id}/insights?metric=audience_gender_age,audience_locale,audience_country&period=lifetime&access_token={access-token}" ``` ## Comments and Moderation ### Get Media Comments ```bash # Get comments on media curl -i -X GET \ "https://graph.facebook.com/v18.0/{media-id}/comments?fields=id,text,timestamp,username,replies&access_token={access-token}" # Reply to comment curl -X POST \ "https://graph.facebook.com/v18.0/{comment-id}/replies" \ -F "message={reply-text}" \ -F "access_token={access-token}" ``` ### Moderate Comments ```bash # Hide comment curl -X POST \ "https://graph.facebook.com/v18.0/{comment-id}" \ -F "hide=true" \ -F "access_token={access-token}" # Delete comment curl -i -X DELETE \ "https://graph.facebook.com/v18.0/{comment-id}?access_token={access-token}" ``` ## Webhooks Setup ### Configure Webhook ```bash # Subscribe to webhooks curl -X POST \ "https://graph.facebook.com/v18.0/{app-id}/subscriptions" \ -F "object=instagram" \ -F "callback_url={webhook-url}" \ -F "fields=comments,mentions" \ -F "verify_token={verify-token}" \ -F "access_token={app-access-token}" ``` ## Decision Tree ``` Instagram API Task ├── Content Management? │ ├── Upload Media → Use media upload endpoints │ ├── Publish Stories → Use stories endpoints │ └── Schedule Posts → Use Business API with publish time ├── Analytics Needed? │ ├── Post Performance → Use media insights │ ├── Account Metrics → Use account insights │ └── Audience Data → Use audience insights ├── Engagement Management? │ ├── Monitor Comments → Use comments API + webhooks │ ├── Respond to Mentions → Use mentions webhook │ └── Moderate Content → Use comment moderation └── Research & Discovery? ├── Hashtag Analysis → Use hashtag endpoints ├── Competitor Research → Use public content API └── Trend Discovery → Use top media for hashtags ``` ## Common Workflows ### Complete Media Upload Flow ```bash #!/bin/bash # 1. Create media container CONTAINER_ID=$(curl -s -X POST \ "https://graph.facebook.com/v18.0/${IG_ACCOUNT_ID}/media" \ -F "image_url=${IMAGE_URL}" \ -F "caption=${CAPTION}" \ -F "access_token=${ACCESS_TOKEN}" | jq -r '.id') # 2. Publish media curl -X POST \ "https://graph.facebook.com/v18.0/${IG_ACCOUNT_ID}/media_publish" \ -F "creation_id=${CONTAINER_ID}" \ -F "access_token=${ACCESS_TOKEN}" ``` ### Bulk Analytics Export ```bash #!/bin/bash # Get all media IDs MEDIA_IDS=$(curl -s "https://graph.instagram.com/${USER_ID}/media?access_token=${ACCESS_TOKEN}" | jq -r '.data[].id') # Get insights for each media for media_id in $MEDIA_IDS; do curl -s "https://graph.facebook.com/v18.0/${media_id}/insights?metric=impressions,reach,saved&access_token=${ACCESS_TOKEN}" >> insights.json done ``` ## Troubleshooting ### Common Errors **Error: Invalid access token** ```json {"error": {"message": "Invalid OAuth access token.", "type": "OAuthException", "code": 190}} ``` **Fix:** Regenerate access token or check token permissions **Error: Media upload failed** ```json {"error": {"message": "Media could not be posted", "code": 9004}} ``` **Fix:** Verify image format (JPG/PNG), size limits (8MB for photos, 1GB for videos) **Error: Insufficient permissions** ```json {"error": {"message": "Insufficient permission for this action", "code": 10}} ``` **Fix:** Add required permissions: `instagram_basic`, `instagram_content_publish`, `pages_show_list` **Error: Rate limit exceeded** ```json {"error": {"message": "Application request limit reached", "code": 4}} ``` **Fix:** Implement exponential backoff, respect rate limits (200 calls per hour per user) ### Debug Commands ```bash # Test token validity curl -i -X GET "https://graph.instagram.com/me?access_token={access-token}" # Check token permissions curl -i -X GET "https://graph.facebook.com/v18.0/me/permissions?access_token={access-token}" # Validate webhook curl -X GET "{webhook-url}?hub.mode=subscribe&hub.challenge=test&hub.verify_token={verify-token}" ```