Instagram — hashtag/getTopMedia

Algorithmic selection: Unlike hashtag/getRecentMedia which returns posts in chronological order, getTopMedia returns posts Instagram considers most engaging and relevant. Results change as Instagram's algorithm re-ranks posts. Use both together for comprehensive hashtag coverage.

When to Use

Benchmark content quality: Retrieve the top posts for your industry hashtag to understand what types of content (format, composition, caption style) perform best — use insights to inform your own content strategy.
Influencer identification: Top posts often come from highly engaged accounts. Extract the top post authors to build an influencer prospect list for outreach.
Trend validation: Before committing to a content theme, check top posts for related hashtags to validate that the theme has high engagement and your intended angle is not already saturated.
Competitive intelligence: Monitor top posts for competitor brand hashtags to identify their most successful content and the accounts creating it.
Content inspiration feeds: Curate a weekly "top posts" digest for your content team by fetching top media from 3–5 industry hashtags and presenting them in an internal newsletter or Slack message.

Configuration

Connection

Field	Required	Description
`accessToken`	Required	Long-lived Instagram access token stored in BizFirst Credentials Manager.
`igUserId`	Required	Your Instagram Business/Creator account ID. Required by the Graph API.

Operation

Field	Required	Description
`resource`	Required	Must be `ig-hashtag`.
`operation`	Required	Must be `get-top-media`.
`hashtagId`	Required	Hashtag ID from hashtag/get.
`limit`	Optional	Items per page. Default `25`. Instagram returns at most 10 results per call regardless.
`after`	Optional	Pagination cursor from previous page's `paging.after`.

Sample Configuration JSON

{
  "resource": "ig-hashtag",
  "operation": "get-top-media",
  "accessToken": "{{ $credential.instagram.accessToken }}",
  "igUserId": "17841400000000000",
  "hashtagId": "{{ $db.hashtagCache.where(name='sustainablefashion').hashtagId }}"
}

Validation Errors

Error	Cause
`accessToken is required`	`accessToken` field is missing or empty.
`igUserId is required`	`igUserId` field is missing or empty.
`hashtagId is required`	`hashtagId` field is missing or empty.

Output

Success Port

Field	Type	Description
`status`	string	`"success"`
`hashtagId`	string	The queried hashtag ID.
`media`	array	Array of top media objects. Max 10 per page.
`paging.before`	string	Cursor for previous page.
`paging.after`	string	Cursor for next page. Empty on last page.
`paging.nextUrl`	string	Full Graph API URL for next page.
`payload`	string	Raw JSON response.

Error Port

Field	Type	Description
`status`	string	`"error"`
`errorCode`	string	Graph API error code.
`errorMessage`	string	Error description.
`payload`	string	Raw error response.

Sample Output JSON

{
  "status": "success",
  "hashtagId": "17843819102081146",
  "media": [
    {
      "id": "17855590000000030",
      "caption": "Our most engaged post this season! #sustainablefashion #ecolife",
      "media_type": "CAROUSEL_ALBUM",
      "permalink": "https://www.instagram.com/p/EFGH5678/"
    }
  ],
  "paging": {
    "before": "",
    "after": "QVFIUm...",
    "nextUrl": "https://graph.facebook.com/v18.0/..."
  }
}

Expression Reference

Expression	Value
`{{ $output.instagram.media }}`	Array of top media items
`{{ $output.instagram.media[0].id }}`	Top post media ID
`{{ $output.instagram.media[0].caption }}`	Top post caption
`{{ $output.instagram.media[0].permalink }}`	Top post public URL

Node Policies & GuardRails

Requires cached hashtagId: Pre-resolve hashtag names with hashtag/get and cache IDs in your database. Do not re-resolve on each workflow run to avoid consuming the 30 unique hashtag weekly budget.
Result variability: Top media results change as Instagram re-ranks posts based on engagement velocity. Run this operation on a schedule to capture changes over time rather than relying on a single snapshot.
Available fields: Like getRecentMedia, field access for other users' media is limited via hashtag endpoints. like_count and comments_count may not be available for third-party posts.
GDPR: Store only necessary data fields and apply appropriate retention policies for third-party user content.

Examples

Weekly content inspiration digest

{
  "resource": "ig-hashtag",
  "operation": "get-top-media",
  "accessToken": "{{ $credential.instagram.accessToken }}",
  "igUserId": "{{ $env.IG_USER_ID }}",
  "hashtagId": "{{ $loop.current.hashtagId }}"
}

Run weekly, iterating over 5 industry hashtag IDs. Results from each hashtag are merged into a curated list and formatted into a Slack message or internal email digest for the content team.

Competitive top content benchmark

{
  "resource": "ig-hashtag",
  "operation": "get-top-media",
  "accessToken": "{{ $credential.instagram.accessToken }}",
  "igUserId": "17841400000000000",
  "hashtagId": "{{ $env.COMPETITOR_HASHTAG_ID }}"
}

Fetches the algorithmically top posts for a competitor's brand hashtag. The next node extracts permalink and caption from each item and stores them in a competitive intelligence database for trend analysis.