📸 Instagram Story Presence Tracker

Monitor competitor Instagram stories without account ownership. Track when competitors post stories, how frequently, and what type of content they're sharing—all in real-time.

---

🎯 What This Tool Does

✅ Track ANY Public Instagram Profile:

• ✅ Story presence detection - Know instantly when competitors post stories
• ✅ Story count & composition - See how many frames (images vs videos)
• ✅ Story age tracking - Monitor how old their stories are
• ✅ Expiry countdown - Know when stories will disappear
• ✅ Posting patterns - Analyze competitor story frequency
• ✅ Content type analysis - Video-heavy or image-focused?

❌ What This Tool Does NOT Do:

• ❌ View counts (Instagram only shows these to story owners)
• ❌ Story content download (respects Instagram's terms)
• ❌ Private account access (public profiles only)

No account ownership required! Works for competitors, brands, influencers—anyone with a public profile.

---

🚀 Use Cases

1. Competitive Intelligence

Monitor when competitors are most active on stories:

{
  "profiles": ["nike", "adidas", "puma"],
  "maxProfilesPerRun": 50
}

Result: Know who's posting, when they're posting, and how often.

2. Influencer Campaign Monitoring

Track if influencers are posting your campaign stories:

{
  "profiles": ["influencer1", "influencer2", "influencer3"]
}

Result: Verify campaign deliverables in real-time.

3. Brand Health Tracking

Monitor multiple brand accounts across regions:

{
  "profiles": ["brand_us", "brand_uk", "brand_de"]
}

Result: Ensure consistent story activity across markets.

4. Event Coverage Monitoring

Track live event story coverage:

{
  "profiles": ["event_official", "sponsor1", "sponsor2"]
}

Result: See who's covering the event in real-time.

5. Trend Analysis

Analyze posting patterns over time:

• Schedule hourly runs
• Export to Google Sheets
• Build time-series analysis

---

📊 Sample Output

{
  "username": "nike",
  "profileUrl": "https://www.instagram.com/nike/",
  "active_story": true,
  "story_count": 8,
  "story_frames": [
    {
      "index": 1,
      "id": "3234567890123456789",
      "type": "video",
      "taken_at": "2024-02-06T14:30:00.000Z",
      "expiring_at": "2024-02-07T14:30:00.000Z",
      "duration": 15.2
    },
    {
      "index": 2,
      "id": "3234567890123456790",
      "type": "image",
      "taken_at": "2024-02-06T15:45:00.000Z",
      "expiring_at": "2024-02-07T15:45:00.000Z",
      "duration": null
    }
  ],
  "story_metadata": {
    "oldest_story": "2024-02-06T14:30:00.000Z",
    "newest_story": "2024-02-06T18:20:00.000Z",
    "video_count": 5,
    "image_count": 3
  },
  "story_age_hours": 6.5,
  "hours_left_until_expiry": 17.5,
  "profile_context": {
    "followers": 305000000
  },
  "success": true,
  "scrapedAt": "2024-02-06T21:00:00.000Z"
}

Key Metrics Explained:

active_story (boolean)

Does this profile currently have an active story?

• true = Yes, story is live
• false = No active story

story_count (integer)

Total number of story frames currently published.

story_age_hours (float)

How old is the oldest story frame (in hours)?

• Useful for tracking posting freshness
• 6.5 = Story started 6.5 hours ago

hours_left_until_expiry (float)

Time until the newest story expires (24h from posting).

• 17.5 = Story will disappear in 17.5 hours

story_metadata

Content breakdown:

• video_count: Number of video frames
• image_count: Number of image frames
• Identify content strategy (video-heavy vs static images)

---

📥 Input Configuration

Minimal Setup (No Session ID):

{
  "profiles": ["competitor1", "competitor2"]
}

With Optional Session ID (Better Reliability):

{
  "sessionId": "YOUR_SESSION_ID",
  "profiles": ["competitor1", "competitor2", "@competitor3"],
  "includeProfileContext": true,
  "maxProfilesPerRun": 50
}

Required Fields:

• profiles (array): Instagram usernames to monitor

Optional Fields:

• sessionId (string): Your Instagram session cookie (improves reliability)
• includeProfileContext (boolean, default: true): Include follower counts
• maxProfilesPerRun (integer, default: 50): Batch size
• maxRequestsPerMinute (integer, default: 15): Rate limiting

---

🔐 Session ID (Optional but Recommended)

Session ID improves reliability for:

• Protected profiles that require login
• High-volume monitoring (reduces rate limits)
• More stable API access

How to Get Session ID:

1. Log into Instagram in your browser
2. Press F12 to open DevTools
3. Go to Application → Cookies → https://instagram.com
4. Copy sessionid value

Note: Session ID is optional. Many profiles work without it!

---

⚙️ Advanced Usage

Scheduled Monitoring (Hourly Checks)

{
  "schedule": "0 * * * *",
  "input": {
    "profiles": ["competitor1", "competitor2"]
  }
}

Webhook Integration

Send data to your analytics dashboard:

{
  "webhooks": [
    {
      "eventTypes": ["ACTOR.RUN.SUCCEEDED"],
      "requestUrl": "https://your-api.com/instagram-webhook"
    }
  ]
}

Export to Google Sheets

1. Run actor on schedule
2. Use Apify integration to push to Google Sheets
3. Build time-series dashboard

---

🚨 Common Scenarios

"Login required for [username]"

Cause: Profile is protected/private or rate limit hit.
Solution:

• Provide a session ID
• Reduce maxRequestsPerMinute
• Only track public profiles

"No active stories"

Cause: Profile genuinely has no stories posted in last 24h.
Solution: This is expected behavior—not all profiles post daily.

"Rate limit hit"

Cause: Too many requests to Instagram.
Solution:

• Wait 15 minutes
• Reduce maxRequestsPerMinute to 10 or lower
• Use Apify Proxy

Story count but no frames data

Cause: API returned story count but not individual frames.
Solution: This is rare but happens. Data is still useful (you know they have stories).

---

📈 Best Practices

1. Rate Limiting

• Keep maxRequestsPerMinute ≤ 15
• For 100+ profiles, use multiple scheduled runs

2. Scheduling Strategy

• Hourly runs: Catch stories as they're posted
• Daily runs (9 AM, 6 PM): Peak posting times
• Weekly summaries: Aggregate posting patterns

3. Data Analysis

• Export to CSV for historical analysis
• Track competitor posting frequency
• Identify optimal posting times based on their patterns

4. Session Management

• Session ID lasts ~60 days
• Refresh monthly for best results
• Use Apify encrypted input fields

---

🔄 API Reliability

Current Version: 1.0.0
Instagram API Stability: Medium

Instagram occasionally updates their API structure. If data quality degrades:

1. Check for Actor updates
2. Verify session ID is fresh (if using)
3. Report issues via GitHub

---

📊 Competitive Analysis Example

Monitor top 10 competitors hourly:

// Scheduled run every hour
{
  "profiles": [
    "nike", "adidas", "puma", "underarmour",
    "reebok", "newbalance", "asics", "skechers",
    "fila", "converse"
  ],
  "sessionId": "YOUR_SESSION_ID",
  "maxRequestsPerMinute": 12
}

Weekly Report:

• Who posts stories most frequently?
• Average stories per day per brand
• Video vs image content mix
• Peak posting times

---

🎁 Roadmap

• Hashtag monitoring in stories (if visible)
• Location tag detection
• Multi-account comparison dashboard
• Story duration analysis (video length trends)
• Alert system (Slack/email when competitor posts)

---

📞 Support

• Documentation: Apify Docs
• Instagram API Limits: Respect Instagram Terms

---

📜 License & Compliance

License: MIT

Instagram Terms Compliance:

• Only accesses publicly available data
• Respects rate limits
• No content downloading
• No private profile access

Ethical Use:

• Competitive analysis ✅
• Market research ✅
• Campaign verification ✅
• Spam/harassment ❌

---

🚀 Quick Start

# Install Apify CLI
npm install -g apify-cli

# Run locally
apify run -p

# Sample input
{
  "profiles": ["competitor_username"]
}

Expected Output:

{
  "username": "competitor_username",
  "active_story": true,
  "story_count": 5,
  "story_age_hours": 3.2,
  "hours_left_until_expiry": 20.8
}

---

Built for marketers, agencies, and competitive intelligence teams 🎯