All Instagram credentials and session cookies are encrypted with AES-256-GCM before being written to PostgreSQL. The encryption key (
CREDENTIALS_ENC_KEY_B64) is server-side only and is never transmitted to any external service.How the connection works
Stagehand launches a real Chromium browser on the server, navigates to your Instagram profile, and extracts follower counts, engagement metrics, and post performance data from the page DOM. For publishing, Stagehand fills in the post compose interface and submits. Instagram’s bot detection is among the most aggressive of any major platform. The integration mitigates this by using realistic Chrome fingerprints and injecting existing session cookies whenever available — but HITL escalation is more frequent with Instagram than with adult content platforms.Authentication
Instagram only supports email/password login in the connect flow. X/Twitter OAuth is not available for Instagram.- Email / Password: GenieHelper logs in with your Instagram email and password, then stores the resulting session cookies in
platform_sessions. - Cookie only: No password is stored. You log in manually in your browser, export session cookies via the GenieHelper extension, and GenieHelper uses those cookies for all subsequent operations.
Setup
Choose your auth method
Select Email / Password to store credentials, or Cookie only to manage sessions manually. Cookie only is recommended for accounts where you have 2FA enabled.
Enter your credentials
For email/password: enter your Instagram login email and password, and your
@handle (profile URL username). All values are AES-256-GCM encrypted before being saved.Save the connection
GenieHelper creates a
platform_connections record and enqueues an initial scrape_profile job. Profile stats will appear in the dashboard once the first scrape completes.Data collected
Thescrape_profile job extracts the following from your Instagram profile:
| Field | Source | Collection |
|---|---|---|
| Follower count | Profile page DOM | platform_connections |
| Following count | Profile page DOM | platform_connections |
| Post count | Profile page DOM | platform_connections |
| Display name | Profile page DOM | platform_connections |
| Bio text | Profile page DOM | platform_connections |
| Verification status | Profile page DOM | platform_connections |
| Post captions | Per-post extraction | media_assets |
| Likes per post | Per-post extraction | media_assets |
| Comments per post | Per-post extraction | media_assets |
| Posted date | Per-post extraction | media_assets |
scrape_post_performance job records engagement snapshots:
| Metric | Collection |
|---|---|
| Likes | post_performance_snapshots |
| Comments | post_performance_snapshots |
| Views | post_performance_snapshots |
Reel view counts and story metrics are not currently extracted — Instagram surfaces these only through its private API or the Creator Studio interface, which requires additional authentication flows not yet implemented.
Publishing
GenieHelper can schedule and publish posts to Instagram via Stagehand browser automation. Thepublish_post BullMQ job navigates to the Instagram post compose interface, fills in the caption, attaches any media, and submits.
Publishing is queued through the scheduled_posts collection. The post scheduler polls every 60 seconds and dispatches publish_post jobs for posts with a scheduled_for timestamp in the past.
Current publishing status: Instagram automated posting is implemented as a stub in operations/publish.js. The platform is listed as unsupported for the publish_post job until the full Instagram compose flow is implemented (tracked under the H-series sprint). Until then, scheduling posts for Instagram queues the job but it will not publish automatically.
Rate limits and safe usage
Instagram imposes strict rate limits and monitors accounts for unusual activity:- Scraping your own profile once every 6 hours (the default
runScrapeSchedulerinterval) is low-risk - Avoid triggering manual scrapes repeatedly in a short window
- If your account enters a checkpoint or gets temporarily restricted, stop all automation immediately, complete the manual verification Instagram requires, and wait 24 hours before re-enabling automated scraping
- Cookie-based sessions expire; when they do, the next scrape will escalate to HITL
Session management
Instagram session cookies are stored inplatform_sessions:
- Cookies are AES-256-GCM encrypted using the same envelope format as all other platform credentials
- Active sessions are visible in the Cookie Sessions tab in Platform Connections
- Revoking a session forces the next scrape to re-authenticate
- Instagram sessions typically last days to weeks depending on account activity and login frequency
Connection health monitoring
Theplatform_health_checks collection records each scrape outcome. The Platform Connections card reflects:
| Status | Meaning |
|---|---|
connected | Last scrape completed successfully |
scraping | A scrape job is currently running |
hitl_required | Instagram presented a checkpoint — your action is needed |
failed | Last scrape failed |
pending_connection | Profile saved, no successful scrape yet |
Resolving HITL alerts
Open the alert in the dashboard
The Center Stage switches to
scrape_alert mode. The alert explains what Instagram displayed (e.g., “Suspicious login detected — enter the code sent to your email”).Complete verification in your browser
Open Instagram in your own browser. Complete any verification step Instagram requires — email code, phone code, or “This was me” confirmation.
Export fresh cookies
After successful verification, use the GenieHelper browser extension to export your Instagram cookies, or paste the cookie string in the Cookie Sessions tab.