Skip to main content

Search Hashtag

Searches for Instagram posts by hashtag and retrieves post details including captions, engagement metrics, and media URLs. Useful for discovering trending content, monitoring brand hashtags, and researching popular topics.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.
info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs​

  • Session ID - The session identifier from the Login node.
  • Hashtag - The hashtag to search for (with or without the # symbol). Example: "travel" or "#travel".
  • Max Posts - Maximum number of posts to retrieve. Set to 0 for default limit (typically 50 posts). Use caution with very popular hashtags.

Options​

  • Include Videos - Include video posts in the results. Default is true. When set to false, only image posts will be returned.

Output​

  • Posts - Array of post objects containing the hashtag, each with:

    • shortcode - Unique post identifier
    • post_id - Numeric post ID
    • caption - Post caption text
    • caption_hashtags - Array of all hashtags in the caption
    • caption_mentions - Array of mentioned usernames
    • date - Post publication date (UTC)
    • likes - Number of likes
    • comments_count - Number of comments
    • is_video - Boolean indicating if it's a video post
    • video_view_count - View count (for videos only)
    • url - Media URL (video URL for videos, image URL for photos)
    • thumbnail_url - Thumbnail URL (for videos only)
    • owner_username - Username of the post creator
    • location - Location name (if tagged)
    • post_url - Full Instagram post URL

  • Post Count - Total number of posts retrieved.

How It Works​

The Search Hashtag node discovers posts using a specific hashtag. When executed, it:

  1. Validates the Session ID and Hashtag
  2. Removes the # symbol if provided (accepts both formats)
  3. Queries Instagram's hashtag search API
  4. Iterates through posts containing the hashtag
  5. Filters out videos if Include Videos is disabled
  6. Extracts comprehensive data for each post
  7. Stops when Max Posts limit is reached
  8. Returns the posts array and count

Requirements​

  • An active Instagram session (from Login node)
  • A valid hashtag
  • Login is required to search hashtags
  • The hashtag must exist on Instagram

Error Handling​

The node will return specific errors in the following cases:

  • ErrInvalidArg - Hashtag is missing or empty
  • ErrAuth - Login is required to search hashtags
  • ErrRuntime - General failure to search (hashtag doesn't exist, network error, etc.)

Common Errors​

Missing Hashtag:

Hashtag is required

Solution: Provide a valid hashtag.

Login Required:

Login required to search hashtags

Solution: Ensure you're using a valid authenticated session.

Search Failed:

Failed to search hashtag: [error details]

Solution: Verify the hashtag exists and you have proper authentication.

Usage Notes​

  • The # symbol is optional; the node accepts both "travel" and "#travel"
  • Posts are typically returned by relevance or recency
  • Very popular hashtags may have millions of posts
  • Max Posts defaults to 50 when set to 0 (Instagram's default)
  • The search returns posts that include the exact hashtag
  • Hashtag searches are case-insensitive (#Travel = #travel)
  • Results may include sponsored posts
  • Video filtering can speed up processing if you only need images

Example: Monitor Brand Hashtag​

Inputs:

  • Session ID: (from Login node)
  • Hashtag: "#yourbrandname"
  • Max Posts: 100

Options:

  • Include Videos: true

Output Sample:

{
  "posts": [
    {
      "shortcode": "CxYz123",
      "post_id": "1234567890123456789",
      "caption": "Loving my new #yourbrandname products! #quality #recommended",
      "caption_hashtags": ["yourbrandname", "quality", "recommended"],
      "caption_mentions": ["yourbrandname"],
      "date": "2024-01-15T10:30:00+00:00",
      "likes": 342,
      "comments_count": 28,
      "is_video": false,
      "video_view_count": null,
      "url": "https://instagram.com/.../image.jpg",
      "thumbnail_url": null,
      "owner_username": "happy_customer",
      "location": "New York, NY",
      "post_url": "https://www.instagram.com/p/CxYz123/"
    }
  ],
  "posts_count": 100
}

Example: Trend Discovery​

Workflow:

Login
  ↓
Search Hashtag (#trending_topic, max: 200)
  ↓
Analyze:
  - Top posts by likes
  - Common co-occurring hashtags
  - Posting frequency over time
  - Geographic distribution (locations)
  ↓
Generate trend analysis report
  ↓
Logout

Use Case: Identify trending content and patterns in your industry.

Example: User-Generated Content Collection​

Workflow:

Schedule (Every 4 hours)
  ↓
Login
  ↓
Search Hashtag (#yourbrand, max: 50)
  ↓
For each post:
  Check if already processed (using post_id)
  If new:
    Download Post Media
    Store post metadata
    Notify social media team
  ↓
Logout

Use Case: Automatically collect and archive UGC featuring your brand.

Example: Competitive Hashtag Analysis​

Workflow:

For each competitor hashtag:
  Search Hashtag (max: 100)
  ↓
  Calculate:
    - Average engagement (likes + comments)
    - Posting frequency
    - Top contributing users
    - Common co-hashtags
  ↓
Compare metrics across competitor hashtags
  ↓
Generate competitive hashtag strategy report

Example: Campaign Performance Tracking​

Workflow:

Search Hashtag (#campaign_hashtag, max: 500)
  ↓
Group posts by date
  ↓
Calculate daily metrics:
  - Post count
  - Total engagement
  - Unique users
  - Average likes per post
  ↓
Generate campaign performance dashboard

Best Practices​

  • Use specific hashtags for more relevant results (#brandname vs #fashion)
  • Set reasonable Max Posts limits based on hashtag popularity
  • Remove the # symbol or include it; the node handles both
  • Monitor brand hashtags regularly to discover UGC
  • Track competitor hashtags for competitive intelligence
  • Combine with Download Post Media to archive content
  • Store post_id to avoid processing duplicates
  • Analyze caption_hashtags to discover related tags
  • Check owner_username to identify brand advocates

Tips for Effective Use​

  • Hashtag Selection: Specific hashtags yield more targeted results than broad ones
  • Popular vs Niche: Popular hashtags have more posts but may be less relevant
  • Co-Hashtag Analysis: Extract caption_hashtags to find related tags
  • User Identification: Track owner_username to find consistent contributors
  • Engagement Metrics: Sort by likes + comments to find top-performing content
  • Video Content: Enable/disable video filtering based on your needs
  • Location Data: Use location field for geographic insights
  • Trend Timing: Post dates reveal when hashtag usage peaks
  • Duplicate Prevention: Store post_id to track previously processed posts

Common Use Cases​

  1. Brand Monitoring - Track mentions of your brand hashtag
  2. User-Generated Content - Discover customer posts about your products
  3. Trend Research - Identify trending topics and content in your niche
  4. Campaign Tracking - Monitor custom campaign hashtag usage
  5. Competitive Analysis - Research competitor hashtag strategies
  6. Influencer Discovery - Find users creating content in your space
  7. Content Curation - Collect relevant content for reposting
  8. Market Research - Understand conversations around topics
  9. Event Coverage - Track event hashtags in real-time
  10. Crisis Monitoring - Watch for negative hashtag usage

Hashtag Analysis Metrics​

Key Metrics to Calculate:

Engagement Rate:

avg_engagement = sum(likes + comments) / posts_count
- Indicates hashtag quality and audience interest

Post Frequency:

posts_per_day = posts_count / date_range
- Shows hashtag popularity and activity level

User Diversity:

unique_users = count(distinct owner_username)
diversity = unique_users / posts_count
- High diversity: Broad adoption
- Low diversity: Dominated by few users

Video vs Image Ratio:

video_ratio = count(is_video == true) / posts_count
- Reveals content format preferences

Example: Comprehensive Hashtag Analysis​

Workflow:

Search Hashtag (max: 500)
  ↓
Calculate:
  - Total posts and engagement
  - Average likes and comments
  - Unique contributors
  - Video vs image ratio
  - Posting time patterns
  ↓
Extract:
  - Top 10 posts by engagement
  - Most active contributors
  - Related hashtags (from caption_hashtags)
  - Common locations
  ↓
Identify:
  - Peak posting times
  - Content themes
  - Influencer participation
  ↓
Generate comprehensive hashtag report

Performance Considerations​

  • Popular hashtags (1M+ posts) return results quickly but contain vast amounts of content
  • Setting Max Posts to 50-200 provides good balance of data and performance
  • Video posts require slightly more processing than images
  • Hashtag searches are generally fast (2-5 seconds for 50 posts)
  • Rate limiting may occur with excessive searches
  • Consider caching results for frequently searched hashtags

Hashtag Strategy Insights​

From Search Results:

  1. Popularity Assessment - High post count indicates popular hashtag
  2. Engagement Quality - Average likes/comments shows audience interest
  3. Competition Level - More posts means more competition for visibility
  4. Content Types - Video ratio reveals format preferences
  5. User Behavior - Location and mention patterns show usage context
  6. Related Tags - Co-occurring hashtags suggest topic associations
  7. Posting Patterns - Date analysis reveals optimal posting times

Important Notes​

  • Authentication Required: Hashtag search requires an active login session
  • Case Insensitive: #Travel, #travel, and #TRAVEL return same results
  • Exact Match: Searches for exact hashtag, not partial matches
  • # Symbol Optional: Node accepts both "#hashtag" and "hashtag"
  • Result Order: Posts typically ordered by relevance or recency (Instagram's algorithm)
  • Rate Limiting: Excessive searches may trigger Instagram rate limits
  • Popular Hashtags: Extremely popular tags may have limited result sets
  • Real-Time: Results reflect current state, not historical data
  • Sponsored Content: Results may include sponsored/promoted posts
  • Default Limit: Setting Max Posts to 0 uses Instagram's default (~50 posts)