instagram

Original：🇺🇸 English
Translated

Instagram Graph API integration via curl. Use this skill to fetch and publish Instagram media.

14installs
Sourcevm0-ai/vm0-skills
Added on

NPX Install

npx skill4agent add vm0-ai/vm0-skills instagram

Tags

Translated version includes tags in frontmatter
instagram-graph-apicurl-commandsmedia-retrievalmedia-publishingapi-integration

SKILL.md Content

View Translation Comparison →

Instagram API (Graph API)

Use the Instagram Graph API by directly executing 
curl
commands to read and publish Instagram content.
Official docs: 
https://developers.facebook.com/docs/instagram-api

When to Use

Use this skill when you need to:
  • Fetch recent media (photos / videos / Reels) from an account
  • Get detailed information about a specific media item (caption, type, link, time, etc.)
  • Search recent media by hashtag
  • Publish image posts via API (with caption)

Prerequisites

  1. You must have an Instagram Business / Creator account linked to a Facebook Page
  2. Create an app in Facebook Developers and enable Instagram Basic Display / Instagram Graph API permissions
  3. Obtain:
  • INSTAGRAM_ACCESS_TOKEN
    : a long-lived user access token
  • INSTAGRAM_BUSINESS_ACCOUNT_ID
    : your Instagram Business account ID
Set the environment variables, for example:
bash
export INSTAGRAM_ACCESS_TOKEN="EAAG..."
export INSTAGRAM_BUSINESS_ACCOUNT_ID="1784140xxxxxxx"
These examples use Graph API version 
v21.0
. You can replace this with the latest version if needed.

Required permissions (scopes)

Depending on which endpoints you use, make sure your app has requested and been approved for (at least):
  • instagram_basic
  • pages_show_list
  • instagram_content_publish
    (for publishing media)
  • instagram_manage_insights
    and related permissions (for insights / some hashtag use cases)
Important: When using 
$VAR
in a command that pipes to another command, wrap the command containing 
$VAR
in 
bash -c '...'
. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
bash
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq '.'

How to Use

All examples below assume you have already set:
bash
INSTAGRAM_ACCESS_TOKEN
INSTAGRAM_BUSINESS_ACCOUNT_ID

1. Fetch recent media for the account

Fetch the most recent media (photos / videos / Reels) for the account:
bash
bash -c '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_ACCESS_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):
bash
bash -c '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_ACCESS_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":
bash
bash -c '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_ACCESS_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):
bash
bash -c '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_ACCESS_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
:
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.
bash
bash -c '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_ACCESS_TOKEN}"'
The response will contain an 
id
(media container ID), for example:
json
{
  "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
:
json
{
  "creation_id": "<your-creation-id>"
}
Replace 
<your-creation-id>
with the 
id
field from the "Create Media Container" response (section 4.1 above):
bash
bash -c '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_ACCESS_TOKEN}"'
If successful, the response will contain the final media 
id
:
json
{
  "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_ACCESS_TOKEN
    is a valid long-lived token
  1. 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
  1. 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_ACCESS_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