Instagram — hashtag/get

7-day hashtag limit: Instagram limits each user to searching 30 unique hashtags per 7 days. Unique means distinct hashtag names — searching the same hashtag again counts only once. Cache hashtagId values in your database to avoid re-querying. Do not search the same hashtag in multiple workflows without caching.

When to Use

Hashtag media search prerequisite: Always call hashtag/get first when you need to use hashtag/getRecentMedia or hashtag/getTopMedia. Cache the returned hashtagId to avoid re-querying.
Brand hashtag monitoring setup: During initial campaign setup, resolve all campaign hashtags to their IDs and store them in a configuration table for use by the monitoring workflow.
Trend discovery: Resolve trending hashtag names from an external trend feed (e.g. Twitter/X trending topics) to Instagram hashtag IDs to cross-platform trend analysis.
Competitor hashtag surveillance: Resolve competitor brand hashtags to IDs so the monitoring workflow can fetch recent and top media using those hashtags to track user sentiment and usage patterns.
Campaign hashtag validation: Before launching a campaign with a custom hashtag, verify the hashtag exists and retrieve its ID to confirm it is already in use (or not), informing the naming decision.

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 for hashtag search context.

Operation

Field	Required	Description
`resource`	Required	Must be `ig-hashtag`.
`operation`	Required	Must be `search`.
`query`	Required	Hashtag name to search (without the # symbol, e.g. `fashion` not `#fashion`). Case-insensitive.

Sample Configuration JSON

{
  "resource": "ig-hashtag",
  "operation": "search",
  "accessToken": "{{ $credential.instagram.accessToken }}",
  "igUserId": "17841400000000000",
  "query": "sustainablefashion"
}

Validation Errors

Error	Cause
`accessToken is required`	`accessToken` field is missing or empty.
`igUserId is required`	`igUserId` field is missing or empty.
`query is required`	`query` field is missing or empty.
Graph API error 2207013	Weekly unique hashtag search limit (30) exceeded.

Output

Success Port

Field	Type	Description
`status`	string	`"success"`
`hashtagId`	string	Stable Graph API hashtag ID. Pass to `hashtag/getRecentMedia` or `hashtag/getTopMedia`.
`name`	string	Confirmed hashtag name as stored in Graph API.
`payload`	string	Raw JSON response from the Graph API.

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",
  "name": "sustainablefashion",
  "payload": "{\"data\":[{\"id\":\"17843819102081146\"}]}"
}

Expression Reference

Expression	Value
`{{ $output.instagram.hashtagId }}`	Hashtag ID for getRecentMedia / getTopMedia
`{{ $output.instagram.name }}`	Confirmed hashtag name string

Node Policies & GuardRails

Cache hashtagId: Always store the returned hashtagId in a database or workflow variable after the first resolution. Re-querying the same hashtag unnecessarily wastes your 30-hashtag weekly budget.
Conditional query: Add a cache-check node before this operation — if the hashtagId is already stored for this hashtag name, skip this node entirely and use the cached ID.
Weekly quota management: Maintain a count of unique hashtags searched in the past 7 days. Alert if approaching 25 to prevent unexpected failures from quota exhaustion.
Rate limit: 200 calls per user per hour in addition to the weekly 30-hashtag unique search limit.

Examples

Campaign hashtag setup with caching

// Step 1: Check cache (database lookup node)
// If not cached:
{
  "resource": "ig-hashtag",
  "operation": "search",
  "accessToken": "{{ $credential.instagram.accessToken }}",
  "igUserId": "17841400000000000",
  "query": "{{ $input.hashtagName }}"
}
// Step 2: Store hashtagId in DB for future use

Monitor three campaign hashtags

[
  { "query": "yourbrandname" },
  { "query": "summercollection2025" },
  { "query": "sustainablefashion" }
]

Run each through hashtag/get once at campaign start, store the three hashtagId values, then use them in the daily monitoring workflow with hashtag/getRecentMedia without re-resolving the names.