Instagram Hashtag Search API: Get Posts by Hashtag

The Instagram hashtag search API is a two-step flow in the Instagram Graph API: GET /ig_hashtag_search turns a hashtag into a hashtag ID, then GET /{hashtag-id}/top_media or /recent_media returns public posts that use it. Every call runs on behalf of an Instagram professional account, and that account can query 30 unique hashtags per rolling 7 days.

Access is the hard part. Hashtag search needs the Facebook Login version of the API and App Review for a feature called Instagram Public Content Access. For the rest of the platform, see our Instagram API guide.

What do you need before you start?#

Hashtag search needs Facebook Login, an approved feature, and one permission. Per Meta's hashtag search guide:

• The right API version. Meta documents hashtag search for the Instagram API with Facebook Login and with Unified Login. Calls go to graph.facebook.com.
• Instagram Public Content Access. A feature, not a permission, that your app requests in App Review.
• instagram_basic. Also through App Review. If the user's Page role was granted through Business Manager, add one of ads_management, business_management, or pages_read_engagement.
• A User access token from a Facebook user approved for tasks on the Page linked to the Instagram account.
• The IG user ID of that professional account. Every hashtag call takes it as user_id.

Instagram Login can't do this. Meta now steers new apps toward the Instagram Login version. Charles Jiang and Sairaj Bharath Yalamanchili wrote on the Meta for Developers blog on July 30, 2024:

"We recommend using Instagram API with Instagram Login to take advantage of these latest updates."

That advice holds for publishing, comments, and messaging. If hashtag search is on your roadmap, though, plan for Facebook Login from the start, since switching later means your users reconnect. Our Instagram API permissions post compares the two permission sets.

Step 1: Get the hashtag ID with ig_hashtag_search#

Call ig_hashtag_search with your IG user ID and the hashtag name, without the #.

curl -G "https://graph.facebook.com/v26.0/ig_hashtag_search" \
  --data-urlencode "user_id=<IG_USER_ID>" \
  --data-urlencode "q=coffee" \
  --data-urlencode "access_token=$FB_USER_ACCESS_TOKEN"

The response is a list with one ID:

{ "data": [{ "id": "17843857450040591" }] }

Cache the ID. Meta's ig_hashtag_search reference says hashtag IDs are "both static and global", so the same hashtag has the same ID for every app and every user. Caching it saves a call, but it doesn't save quota: fetching media for a hashtag still counts as querying it.

Two inputs fail: emojis aren't supported in hashtag queries, and hashtags Meta deems sensitive or offensive return a generic error.

Step 2: Get posts by hashtag with top_media or recent_media#

Request top_media for the most popular posts, or recent_media for posts from the last 24 hours, with user_id and a fields list.

curl -G "https://graph.facebook.com/v26.0/17843857450040591/recent_media" \
  --data-urlencode "user_id=<IG_USER_ID>" \
  --data-urlencode "fields=id,caption,media_type,media_url,permalink,timestamp,like_count,comments_count,children{media_url}" \
  --data-urlencode "limit=50" \
  --data-urlencode "access_token=$FB_USER_ACCESS_TOKEN"

Pagination is unusual. Both edges return only an after cursor, and Meta notes its value stays the same on every page. Keep following paging.next until it disappears.

recent_media only covers the last 24 hours. To collect every post with a hashtag over a week, poll it during the week and dedupe by id. You can't backfill.

Which fields does hashtag search return?#

Hashtag search returns a short list of IG Media fields, and username isn't one of them. Per Meta's references, you can request:

You can't request username, so a hashtag feed can't show who posted without the user opening the permalink. You also can't comment on posts found through hashtag search, per Meta's guide.

What are the Instagram hashtag search API limits?#

The main limit is 30 unique hashtags per Instagram account in any rolling 7-day window. Meta's guide sets out how it counts:

• Per account, not per app. The 30 belong to the Instagram professional account in user_id.
• Unique hashtags. Querying the same hashtag again within 7 days doesn't count again.
• Media fetches count. Calling top_media or recent_media counts as querying that hashtag, even with a cached ID.
• Track usage. GET /{ig-user-id}/recently_searched_hashtags lists the unique hashtags the account searched in the current week.

Other limits from the references:

• Public posts only. No private accounts.
• No promoted posts. Boosted and ad media are excluded.
• No Stories. Hashtags on Stories aren't supported.
• Rate limits still apply. Every call also counts toward the app's call budget for that account; see our Instagram API rate limit guide.

Design for 30. If your product lets customers track hashtags, make 30 per connected account a visible limit in your UI, and show what's left from recently_searched_hashtags.

Can the Instagram API get posts from an account instead of a hashtag?#

Yes, for accounts that authorized your app, and for other Business or Creator accounts through business discovery. Hashtag search is for discovery across public posts. To read one account's feed, use the media edge, covered in our guide to getting Instagram posts with the Graph API.

Where does Adeli fit?#

Adeli's documented API doesn't include hashtag search; it covers the accounts your users connect. If your product needs hashtag discovery, the calls above run on your own Meta app with Public Content Access.

For everything that happens on your users' own accounts, Adeli holds the Meta developer app, carried Meta's review, and refreshes every connected account's tokens:

• Publish feed posts, Reels, Stories, and carousels from one endpoint (Instagram on Adeli).
• List posts from every connected account, with likes and comments (List posts).
• Read account insights for views, reach, interactions, and accounts engaged (analytics API).

An AI content tool can pair the two: hashtag research on their own Meta app, then publishing to customers' accounts through Adeli. Adeli for AI content generation shows that setup, and your first 2 user profiles are free on pricing.