Skip to main content

Get Stories

Retrieves currently active stories from an Instagram profile. Stories are temporary content that expire after 24 hours. Returns story details including media URLs, timestamps, captions, and expiration times.

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.
  • Username - Instagram username to retrieve stories from (without the @ symbol).

Output​

  • Stories - Array of story items, each containing:

    • story_id - Unique story identifier
    • is_video - Boolean indicating if story is a video
    • url - Media URL (video URL for videos, image URL for photos)
    • thumbnail_url - Thumbnail URL (for videos only)
    • caption - Story caption text (if any)
    • caption_hashtags - Array of hashtags in the caption
    • caption_mentions - Array of mentioned usernames
    • created_at - When the story was created (UTC)
    • expires_at - When the story will expire (UTC)
    • video_duration - Duration in seconds (for videos only)

  • Story Count - Number of active story items retrieved.

How It Works​

The Get Stories node retrieves currently active stories from a profile. When executed, it:

  1. Validates the Session ID and Username
  2. Retrieves the profile to get the user ID
  3. Fetches active stories for that user
  4. Iterates through each story item
  5. Extracts media URLs, captions, and metadata
  6. Returns all story items with their expiration times

Requirements​

  • An active Instagram session (from Login node)
  • A valid Instagram username
  • Permission to view the profile's stories (public accounts or accounts you follow)
  • Stories must be currently active (not expired)

Error Handling​

The node will return specific errors in the following cases:

  • ErrInvalidArg - Username is missing or empty
  • ErrNotFound - Profile does not exist
  • ErrPermission - Profile is private and you don't follow them
  • ErrRuntime - General failure to retrieve stories

Common Errors​

Profile Not Found:

Profile 'username' does not exist

Solution: Verify the username is correct.

Private Profile:

Profile 'username' is private and you don't follow them

Solution: You must follow the account to view their stories.

No Stories: If a profile has no active stories, the node returns an empty array (not an error).

Usage Notes​

  • Stories are only available for 24 hours after posting
  • The expires_at field shows when each story will be automatically deleted
  • You can only retrieve stories from accounts you have permission to view
  • Stories from private accounts require you to follow them
  • Multiple story items may be returned if the user posted several stories
  • Story order matches the posting sequence
  • Video stories include duration information
  • Some stories may not have captions

Example: Monitor Brand Mentions​

Inputs:

  • Session ID: (from Login node)
  • Username: "influencer_account"

Output Sample:

{
  "stories": [
    {
      "story_id": "2987654321098765432",
      "is_video": true,
      "url": "https://instagram.com/.../story_video.mp4",
      "thumbnail_url": "https://instagram.com/.../thumbnail.jpg",
      "caption": "Loving this new product! @brand #sponsored",
      "caption_hashtags": ["sponsored"],
      "caption_mentions": ["brand"],
      "created_at": "2024-01-15T10:30:00+00:00",
      "expires_at": "2024-01-16T10:30:00+00:00",
      "video_duration": 15.5
    },
    {
      "story_id": "2987654321098765433",
      "is_video": false,
      "url": "https://instagram.com/.../story_image.jpg",
      "thumbnail_url": null,
      "caption": "",
      "caption_hashtags": [],
      "caption_mentions": [],
      "created_at": "2024-01-15T12:15:00+00:00",
      "expires_at": "2024-01-16T12:15:00+00:00",
      "video_duration": null
    }
  ],
  "stories_count": 2
}

Example: Story Archival​

Workflow:

Schedule (Every 4 hours)
  ↓
Login
  ↓
For each monitored account:
  Get Stories
  ↓
  If stories_count > 0:
    For each story:
      Download media using URL
      Save metadata to database
  ↓
Logout

Use Case: Archive competitor or influencer stories before they expire.

Example: Real-Time Brand Monitoring​

Workflow:

Schedule (Every 30 minutes)
  ↓
Login
  ↓
Get Stories (from tracked influencers)
  ↓
Filter stories with caption_mentions containing "@yourbrand"
  ↓
Send notification with story details
  ↓
Logout

Use Case: Get alerted when influencers mention your brand in their stories.

Example: Content Analysis​

Workflow:

Get Stories
  ↓
Analyze:
  - Count video vs image stories
  - Extract all hashtags
  - Identify mention patterns
  - Calculate average video duration
  ↓
Generate report

Best Practices​

  • Check stories frequently (every 2-4 hours) to avoid missing content before it expires
  • Store story data and media immediately as stories disappear after 24 hours
  • Monitor the expires_at field to prioritize which stories to process first
  • Handle cases where stories_count is 0 (no active stories)
  • Use caption_mentions to track brand mentions
  • Download story media if you need to preserve it
  • Add appropriate delays when checking multiple accounts
  • Consider time zones when scheduling story checks

Tips for Effective Use​

  • Timing: Stories expire exactly 24 hours after creation; check the expires_at timestamp
  • Video Stories: Use video_duration to filter short vs long video content
  • Brand Monitoring: Search caption_mentions for your brand or competitors
  • Content Strategy: Analyze what types of stories (video/image) get posted most
  • Hashtag Tracking: Monitor caption_hashtags for campaign hashtags
  • Archival: Download stories within a few hours of detection to ensure capture
  • Multiple Stories: Users often post multiple story items; process all items in the array
  • Empty Captions: Many stories have no caption; don't rely on caption data always being present

Common Use Cases​

  1. Brand Monitoring - Track when influencers mention your brand in stories
  2. Content Archival - Save competitor stories before they expire
  3. Influencer Tracking - Monitor influencer story activity and frequency
  4. Campaign Monitoring - Track hashtag usage in stories
  5. Competitive Intelligence - Analyze competitor story strategies
  6. Crisis Management - Detect negative mentions in real-time
  7. UGC Collection - Find user-generated content featuring your brand
  8. Trend Analysis - Study story content patterns over time

Performance Considerations​

  • Stories retrieval is relatively fast (1-2 seconds typically)
  • The node returns all active stories in a single call
  • No pagination is needed as stories are limited by the 24-hour window
  • Consider checking stories every 2-4 hours to balance completeness and efficiency
  • Download media immediately if archival is important

Important Notes​

  • Time Sensitivity: Stories expire after 24 hours; implement frequent checks
  • Viewing Privacy: The account owner may see that you viewed their story (Instagram's native behavior)
  • Private Accounts: Requires follow relationship to access stories
  • No Stories: Empty array is returned, not an error
  • Multiple Items: One story "post" may contain multiple items (photos/videos)