Unofficial Instagram & Threads mobile API SDK for Python & TypeScript / Node.js. Talks to the same private endpoints the real Android/iOS app uses — feed, profiles, direct messages, media/reels upload, friendships, warmup exploration loops, and Threads keyword search/replies — with full request signing (X-IG-Capabilities, X-IG-App-ID, Pigeon/Scribe telemetry, JA4 TLS 1.3 BoringSSL). No Meta for Developers account, no OAuth, no app review, no 24-hour messaging window. You drive a real logged-in session, not the throttled official API.
This is a reverse-engineering / automation toolkit. Use it on accounts and data you are authorized to access.
| Official Meta Graph API | instagram-private-api | |
|---|---|---|
| Developer account / app review | required | not needed |
| Access token permissions | scoped, strict review | full mobile permissions |
| Reading feed, explore, other users | No (not exposed) | Yes |
| Cold direct messaging & outreach | No (24h window for approved pages) | Yes (unlimited 1-on-1 & threads) |
| Likes / comments / follows / blocks | No | Yes |
| Reels & Carousel publishing | restricted formats & web upload | Yes (native segmented chunked upload) |
| Threads public search & replies | No (restricted Tech Provider only) | Yes (sub-80ms real-time search & reply) |
| Rate limits | tight, per-app | per-account, mobile-grade |
The official Content Publishing / Graph API only lets you touch your own business connected account in a restricted sandbox. This SDK speaks the native mobile protocol, so it does what the real mobile app does.
- Full mobile signing & anti-fraud — Authentic Android 14 (Pixel 8 Pro) and iOS 17 hardware presets, JA4 TLS 1.3 BoringSSL cipher suites, and companion Pigeon/Scribe telemetry batching.
- Dual Platform (Instagram + Threads) — Drive both Instagram and Threads (
com.instagram.barcelona) using a single unified Meta session or API key. - 60+ endpoints across 7 modules — feed, user, direct, media/reels, friendship, warmup, and threads.
- Reliable direct messaging — 1-on-1 and group threads, typing indicators, read receipts, rich OpenGraph link preview cards, and media attachments.
- Human-like Warmup engine — Natural dwell intervals, feed scroll exploration, and story viewing routines to eliminate automated checkpoint flags.
- Session-based auth & 2FA — Encrypted password challenge, 2FA TOTP seed handling, and instant session serialization/recovery across proxy shifts.
- Managed remote signer or local daemon — Request signing runs on our managed infrastructure or local daemon. You get a clean API and never touch raw reverse-engineered crypto internals.
Request signing runs on our hosted service or high-throughput signing daemon — you just need an API key. No emulators, no Android ADB bridges, no local signing setup to maintain.
from instagramflow import InstagramAPI, ThreadsAPI
# Initialize Instagram client
ig = InstagramAPI(api_key="ig_...") # get a key — see "Get access" below
# Inspect account profile
me = ig.user.profile_self()
print(f"Logged in as @{me['username']} ({me['pk']})")
# Browse timeline feed
feed = ig.feed.timeline(count=12)
# Send direct message with rich link preview card
ig.direct.send_message(
username="target_founder",
text="Hey! Loved your recent breakdown on infrastructure.",
link_preview="https://example.com/demo"
)
# Run an organic warmup exploration session
ig.warmup.run_session(feed_scrolls=10, story_views=5)# Threads client uses the same Meta session or API key
threads = ThreadsAPI(api_key="ig_...")
# Search real-time discussions for keywords
results = threads.search("ai agents", limit=15)
for post in results.posts:
print(f"[{post.author}] ({post.like_count} likes): {post.text[:80]}...")
# Reply directly to any external thread post
threads.reply(
parent_post_id="3141592653589793238",
text="Great perspective! Native HTTP/2 makes a huge difference."
)Looking for a maintained, production-grade TypeScript / Node.js alternative to dilame/instagram-private-api? While Dilame's public library was frozen in early 2024, our SDK provides first-class TypeScript bindings with authentic iOS 17 / Android 14 JA4 TLS 1.3 fingerprints:
import { InstagramAPI, ThreadsAPI } from "@molkex/instagram-private-api";
// Initialize client with iPhone 15 Pro hardware preset
const ig = new InstagramAPI({
apiKey: "ig_...",
devicePreset: "iphone_15_pro"
});
// Watch active story with paired timestamp beacons
await ig.story.seen("3141592653589793238_12345");
// Send DM with reaction and link preview card
await ig.direct.sendMessage({
username: "target_founder",
text: "Loved your latest breakdown on infrastructure!",
linkPreview: "https://example.com/demo"
});
// Fast Threads keyword search (<80ms)
const threads = new ThreadsAPI({ apiKey: "ig_..." });
const { posts } = await threads.search("ai agents", 10);
for (const p of posts) {
console.log(`[${p.author}] (${p.like_count} likes): ${p.text.slice(0, 60)}...`);
}This SDK is Agent-Ready and ships with native MCP server support for autonomous AI workflows (Claude Desktop, Cursor, Windsurf, Devin):
# Launch the MCP server via stdio
python -m instagramflow.mcp_serverClaude Desktop / Cursor config (mcp.json):
{
"mcpServers": {
"instagram": {
"command": "python3",
"args": ["-m", "instagramflow.mcp_server"],
"env": {
"INSTAGRAM_API_KEY": "ig_live_key"
}
}
}
}Available agent tools:
instagram_send_direct_message(username, text, link_preview)instagram_run_warmup(feed_scrolls, story_views)threads_search_posts(query, limit)threads_reply_post(parent_post_id, text)
See AGENT_GUIDE.md and llms.txt for detailed agent prompting specifications.
Comprehensive deep-dives into mobile protocols, fingerprinting, and session management:
- Architecture & Anti-Fraud Engine — JA4 TLS 1.3 BoringSSL vs OpenSSL, HTTP/2 pseudo-header sequencing,
signed_bodyHMAC-SHA256, and Pigeon/Scribe telemetry. - Free Tier vs Commercial Licensing — Capabilities matrix, why write actions require signing, and enterprise daemon licensing.
- Sessions, Proxies & Best Practices — Cookie serialization, residential 4G/5G mobile proxies, and avoiding checkpoint flags.
- AI Agents & MCP Guide — Model Context Protocol (MCP) server setup for Claude Desktop, Cursor, and autonomous agents.
- Machine-Readable Manifest — Index specification for LLM crawlers.
| Module | What it covers |
|---|---|
user |
profile self, user info by username/id, bio/avatar update, privacy toggles, external links |
feed |
timeline feed, user feed, explore grid, saved items, location tags, hashtag feed |
direct |
inbox threads, pending requests, send text, typing cadence, link previews, reactions, media |
media |
Reels tab (user_clips), shortcode conversion, metadata info, bookmark saves/collections, archive, delete |
comment |
comment lists, child replies thread, post comment, reply to comment, like/unlike, pin/unpin |
story |
active stories tray, timestamped seen beacons, story like/unlike, emoji reactions, direct replies, highlights |
note |
24-hour direct status notes, mutual/close friends audience, create and delete |
friendship |
follow, unfollow, block, mute, follower/following pagination, relationship status |
warmup |
organic feed scrolling, randomized dwell delays, story viewing, human-like pacing |
threads |
real-time keyword search, nested discussion trees, thread replies, likes, reposts, quotes |
pip install instagram-private-apinpm install @molkex/instagram-private-apiMobile request signing (X-IG-Capabilities, X-IG-App-ID, signed body payload encryption, and JA4 TLS 1.3 BoringSSL handshake replication) is the critical layer that breaks in legacy scrapers.
We run this as a managed network service or standalone private daemon: your Python code dispatches high-level actions, our signing engine applies cryptographically valid headers and anti-fraud telemetry beacons, and Instagram / Threads accepts the traffic as authentic mobile app requests.
| Metric | Headless Browser (Playwright / Puppeteer) | instagram-private-api SDK |
|---|---|---|
| RAM per 100 Accounts | 25 - 40 GB | < 280 MB |
| CPU Overhead | High (Chromium WebKit rendering) | Near Zero (Pure HTTP/2) |
| TLS Fingerprint | Desktop Chrome/Safari mismatch | Authentic Android 14 JA4 TLS 1.3 |
| Ban Longevity | High risk (Heuristic DOM traps) | Enterprise Longevity (Mobile Match) |
| Threads Search Latency | 3,000 - 7,000 ms | 35 - 80 ms |
Legacy libraries like Instagrapi rely on outdated mobile app endpoints and generic Python OpenSSL TLS handshakes. Meta's anti-fraud system instantly detects generic cipher ordering, resulting in immediate challenge_required or account suspension. Our SDK connects via authentic Android 14 (Pixel 8 Pro) and iOS 17 JA4 TLS 1.3 BoringSSL fingerprints and automatically dispatches native Pigeon/Scribe analytics batches alongside write requests.
This common flag (reported in dilame/instagram-private-api#1776, #1818) is not caused by request frequency. It is triggered by network stack fingerprint mismatch: standard Node.js/Python HTTP clients send OpenSSL Client Hello handshakes without GREASE ciphers, and lack mobile Scribe dwell telemetry. Even 1 action per day will get flagged if the TLS fingerprint is detectable. Our signing engine replicates real iPhone 15 Pro / Android 14 BoringSSL handshakes and pair-dispatches telemetry.
When Meta detects an unverified TLS signature or outdated device header during the /api/v1/accounts/login/ flow, it silently rejects the authentication attempt with a disguised bad_password or You can log in with your linked Facebook account error (see dilame#1819). Our SDK's device engine authenticates using genuine hardware attestation profiles.
Modern Meta sessions bind cookies (sessionid, mid) to a hardware security identifier and carrier state. Making calls without maintaining device consistency triggers session revocation. SessionStorage in our SDK serializes both cookies and device state together, preventing invalidation.
Yes. Both Python and TypeScript SDKs provide high-resolution streaming downloaders (ig.media.download(id_or_code, output_path) and ig.story.download(story_id, output_path)) that fetch pristine source MP4/JPG files directly from Meta's edge CDN.
Yes. The official Meta Graph API (graph.threads.net) strictly prohibits replying to external threads and requires verified Tech Provider status for search. This SDK connects via native mobile Barcelona endpoints (x-ig-app-id: 3419628305025917), enabling wire-speed sub-80ms keyword discovery and direct replies to any public discussion thread.
Under 280 MB of RAM. Unlike browser automation tools (Selenium, Playwright, Puppeteer) that demand 20–40 GB of RAM and dedicated GPUs for 100 accounts, our pure HTTP/2 zero-device architecture runs hundreds of concurrent accounts smoothly on a standard $10/month cloud VPS.
The built-in warmup pipeline executes human-like algorithmic exploration: variable dwell times on posts, randomized story view sessions, and progressive action pacing that mimics authentic human touch input, preserving high trust scores for aged and newly registered accounts.
Yes. We offer standalone self-hosted signing daemon packages for high-throughput enterprise platforms and agency clusters who require zero third-party data transmission.
Migrating from older abandoned libraries? Read our comprehensive side-by-side guides:
- Migrating from dilame/instagram-private-api (TypeScript / Node.js) — Fix
IgLoginBadPasswordError,checkpoint_required, and legacy OpenSSL blocks. - Migrating from instagrapi (Python) — Eliminate login loops, proxy burns, and add full Threads support.
- Mobile Protocol Architecture — Deep dive into HTTP/2, JA4 TLS 1.3 BoringSSL, and Pigeon telemetry.
- Licensing, Rate Limits & Limits — Safe action velocities and warmup pacing.
- Session Storage & Proxy Rotation — Persistent device cookie serialization.
API keys, private signing daemon deployment, pricing plans, and custom high-volume setups: @mxmtkchk on Telegram.
Not affiliated with, authorized, or endorsed by Instagram, Threads, or Meta Platforms, Inc. Provided for educational, research, and automation purposes on authorized accounts. You are responsible for complying with Meta's terms of service and applicable local laws.