Troubleshooting

If requests fail, run zero doctor check-connector --env-name INSTAGRAM_TOKEN or zero doctor check-connector --url https://graph.facebook.com/v21.0/me --method GET

How to Use

All examples below assume you have already set:

INSTAGRAM_TOKEN
INSTAGRAM_BUSINESS_ACCOUNT_ID

1. Fetch recent media for the account

Fetch the most recent media (photos / videos / Reels) for the account:

curl -s -X GET "https://graph.facebook.com/v21.0/$INSTAGRAM_BUSINESS_ACCOUNT_ID/media?fields=id,caption,media_type,media_url,permalink,timestamp" --header "Authorization: Bearer $INSTAGRAM_TOKEN"

Notes:

• Each item in the returned JSON represents a media object
• Common fields:
  • id: media ID (used for details / insights later)
  • caption: caption text
  • media_type: IMAGE / VIDEO / CAROUSEL_ALBUM
  • media_url: direct URL to the media
  • permalink: Instagram permalink
  • timestamp: creation time

2. Get details for a single media

If you already have a media id, you can fetch more complete information. Replace <your-media-id> with the id field from the "Get User Media" response (section 1 above):

curl -s -X GET "https://graph.facebook.com/v21.0/<your-media-id>?fields=id,caption,media_type,media_url,permalink,thumbnail_url,timestamp,username" --header "Authorization: Bearer $INSTAGRAM_TOKEN"

3. Search media by hashtag

Note: hashtag search requires proper business use cases and permissions as defined by Facebook/Instagram. Refer to the official docs.

This usually involves two steps:

3.1 Get the hashtag ID

Replace <hashtag-name> with any hashtag name you want to search for (without the # symbol), e.g., "travel", "food", "photography":

curl -s -X GET "https://graph.facebook.com/v21.0/ig_hashtag_search?user_id=$INSTAGRAM_BUSINESS_ACCOUNT_ID&q=<hashtag-name>" --header "Authorization: Bearer $INSTAGRAM_TOKEN"

Note the id field in the returned JSON for use in the next step.

3.2 Fetch recent media for the hashtag

Replace <hashtag-id> with the id field from the "Search Hashtag" response (section 3.1 above):

curl -s -X GET "https://graph.facebook.com/v21.0/<hashtag-id>/recent_media?user_id=$INSTAGRAM_BUSINESS_ACCOUNT_ID&fields=id,caption,media_type,media_url,permalink,timestamp" --header "Authorization: Bearer $INSTAGRAM_TOKEN"

4. Publish an image post

Publishing an image post via the Graph API usually requires two steps:

1. Create a media container
2. Publish the container to the feed

4.1 Create a media container

Write the request data to /tmp/request.json:

{
  "image_url": "https://example.com/image.jpg",
  "caption": "Hello from Instagram API 👋"
}

Replace https://example.com/image.jpg with any publicly accessible image URL and update the caption text as needed.

curl -s -X POST "https://graph.facebook.com/v21.0/$INSTAGRAM_BUSINESS_ACCOUNT_ID/media" -H "Content-Type: application/json" -d @/tmp/request.json --header "Authorization: Bearer $INSTAGRAM_TOKEN"

The response will contain an id (media container ID), for example:

{
  "id": "1790xxxxxxxxxxxx"
}

Note this ID for use in the next step.

4.2 Publish the media container to the feed

Write the request data to /tmp/request.json:

{
  "creation_id": "<your-creation-id>"
}

Replace <your-creation-id> with the id field from the "Create Media Container" response (section 4.1 above):

curl -s -X POST "https://graph.facebook.com/v21.0/$INSTAGRAM_BUSINESS_ACCOUNT_ID/media_publish" -H "Content-Type: application/json" -d @/tmp/request.json --header "Authorization: Bearer $INSTAGRAM_TOKEN"

If successful, the response will contain the final media id:

{
  "id": "1791yyyyyyyyyyyy"
}

You can then use the "Get details for a single media" command to fetch its permalink.

5. Common errors and troubleshooting

1. Permissions / OAuth errors

• Typical error message: (#10) Application does not have permission for this action
• Check:
• Whether the app has been reviewed / approved
• Whether the required Instagram permissions are enabled
• Whether INSTAGRAM_TOKEN is a valid long-lived token

2. Unsupported account type

• Most Graph API features require Business / Creator accounts
• Make sure the Instagram account type is correct and linked to a Facebook Page

3. Rate limits

• Too many requests in a short period may hit rate limits; add delays for bulk operations

Guidelines

1. Do not log tokens: INSTAGRAM_TOKEN is sensitive; avoid printing it in logs or chat transcripts
2. Validate curl commands in a test environment first: confirm flows before wiring them into automation / agents
3. Keep API version up to date: periodically check Facebook docs and update the v21.0 version in URLs to the latest
4. Use placeholder text for IDs: all examples use placeholder text like <your-media-id> instead of shell variables in URLs to avoid dependencies and make examples self-contained