📸 InstaHarvest v2

Powerful Instagram Private API — async, anti-detection, Pydantic models, AI Agent

31 sync + 31 async modules • 315+ functions • 161 agent tools • Pydantic models • AI Agent • CI/CD • 6242 tests passed

📖 Documentation: mpython77.github.io/instaharvest_v2

🌟 Why InstaHarvest V2 is Unstoppable

Unlike legacy wrappers that easily get blocked by Instagram's bot detection, InstaHarvest v2 is engineered with an enterprise-grade Resilient Anti-Detect Architecture. It boasts:

• 14-Layer Fallback Strategies: Intelligently auto-pivots between GraphQL, Mobile API, and Web API if an endpoint fails or challenges you, effectively ensuring 100% extraction rates.
• Rotating Proxy Auto-Detection: Uses active ip-checking to instantly identify if your proxies rotate IPs. It autonomously configures aggressive Mobile API endpoints to bypass HTTP 400 Bad Request restrictions standard GraphQL methods suffer from on Dynamic IPs. Check out the examples/ dir for ultra-fast 50+ concurrent profile pagination testing!
• TLS/JA3 Impersonation: Built heavily on curl_cffi, the library perfectly masks Python traffic by cloning Chrome v142 browser footprints.
• No-Cookie Deep Harvesting: Achieve thousands of posts paginations absolutely anonymously using highly-stabilized concurrent routines powered by asyncio.
• Bulletproof Pydantic Execution: 100% static type safety parsing, meaning broken, mismatched, or altered payloads from Instagram API are elegantly downgraded without crashing the scraping chain.

Installation

pip install instaharvest-v2

With extras:

pip install instaharvest-v2[dev]      # pytest, pytest-cov, pytest-asyncio
pip install instaharvest-v2[agent]    # AI providers (Gemini, OpenAI, Claude)
pip install instaharvest-v2[web]      # FastAPI web playground
pip install instaharvest-v2[all]      # everything

Quick Start

With cookies (.env file)

from instaharvest_v2 import Instagram

ig = Instagram.from_env(".env")
user = ig.users.get_by_username("cristiano")
print(user.username)        # cristiano
print(user.followers)       # 650000000
print(user["bio"])           # dict-like access works too

With login

ig = Instagram()
ig.login("username", "password")
ig.auth.save_session("session.json")   # save for next time

Load saved session

ig = Instagram()
ig.auth.load_session("session.json")   # no re-login needed

Async mode (50x faster for bulk)

import asyncio
from instaharvest_v2 import AsyncInstagram

async def main():
    async with AsyncInstagram.from_env(mode="fast") as ig:
        # Parallel — all at once!
        tasks = [ig.users.get_by_username(u) for u in usernames]
        profiles = await asyncio.gather(*tasks)

asyncio.run(main())

Challenge auto-resolver

ig = Instagram(
    challenge_callback=lambda ctx: input(f"Code sent to {ctx.contact_point}: ")
)
# Email/SMS challenges resolved automatically!

Anonymous (no login)

ig = Instagram.anonymous(unlimited=True)
ig.add_proxy("http://user:pass@host:port")  # optional

profile = ig.public.get_profile("cristiano")
posts = ig.public.get_posts("cristiano", max_count=12)
reels = ig.public.get_reels("cristiano", max_count=10)
comments = ig.public.get_comments("ABC123", max_count=20)
similar = ig.public.get_similar_accounts("cristiano")
hashtag = ig.public.get_hashtag_posts("fashion", max_count=10)
location = ig.public.get_location_posts("213385402", max_count=10)

🛰️ Ultra-Fast Parallel Scraping with Rotating Proxies

When using standard proxy services (like Proxy-Seller) that rotate IPs constantly, Instagram blocks standard Public GraphQL requests with HTTP 400. We engineered a specialized architecture leveraging Mobile APIs combined with smart Proxy Auto-Detection to bypass these limits at extreme concurrency.

import asyncio
from instaharvest_v2.proxy_manager import ProxyManager
from instaharvest_v2.async_anon_client import AsyncAnonClient

async def main():
    pm = ProxyManager()
    pm.add_proxy("http://user:pass@res.proxy-seller.com:10000")
    
    # 1. Automatically detects if the proxy rotates IPs and disables strict cookie checks
    await pm.detect_proxy_type()  
    
    # 2. Control concurrency (e.g. 5) to prevent Proxy-Supplier 503 HTTP Tunnel errors
    client = AsyncAnonClient(proxy_manager=pm, unlimited=True, max_concurrency=5)
    
    # 3. Use Mobile Feed API to paginate seamlessly across all IPs!
    feed = await client.get_user_feed_mobile(user_id="173560420", count=12, max_id=None)
    
asyncio.run(main())

Checkout examples/parallel_proxy_mobile.py for a full 50-profile parallel scraping test!

🔬 API Diagnostics

from instaharvest_v2 import Instagram, run_diagnostics

ig = Instagram.anonymous(unlimited=True)
ig.add_proxy("http://proxy...")
results = run_diagnostics(ig, username="cristiano")  # tests all 41 methods

CLI:

python -m instaharvest_v2 diagnose cristiano --proxy http://...
python -m instaharvest_v2 diagnose cristiano --layer public --sync-only
python -m instaharvest_v2 diagnose cristiano -o ./results/  # JSON output

🎬 Reel / Post Scraping (no login, no cookies!)

ig = Instagram()

# By shortcode (from URL: instagram.com/reel/ABC123/)
post = ig.public.get_post_by_shortcode("ABC123")
print(post["likes"])         # 69603
print(post["video_url"])     # full video download URL
print(post["audio"])         # {'title': 'Original audio', 'artist': '...'}

# By full URL
post = ig.public.get_post_by_url("https://instagram.com/reel/ABC123/")

# Works for ALL types: Reels, Photos, Carousels, Videos
# Returns: video_url, display_url, likes, views, comments, audio, owner, carousel_media

🤖 AI Agent (161 built-in tools)

from instaharvest_v2 import Instagram
from instaharvest_v2.agent import InstaAgent, Permission

ig = Instagram.from_env(".env")
agent = InstaAgent(
    ig=ig,
    provider="gemini",        # 13+ AI providers
    permission=Permission.FULL_ACCESS,
    memory=True,
)

agent.ask("Get @cristiano's last 10 posts and save to CSV")
agent.ask("Compare @nike and @adidas engagement rates")
agent.ask("Find the best posting time for my account")
agent.ask("Show similar accounts to @nike")
agent.ask("Get comments on post ABC123")
agent.ask("Run API diagnostics for @cristiano")

.env Format

SESSION_ID=your_session_id
CSRF_TOKEN=your_csrf_token
DS_USER_ID=your_user_id
MID=optional
IG_DID=optional
DATR=optional
USER_AGENT=optional

API Reference

👤 Users

user = ig.users.get_by_username("cristiano")   # → User model
user = ig.users.get_by_id(123456789)           # → User model
users = ig.users.search("cristiano")           # → List[UserShort]
profile = ig.users.get_full_profile("cristiano")  # merged User
bio = ig.users.parse_bio(user)                 # → BioParsed

📷 Media

media = ig.media.get_info(media_pk)            # → Media model
media = ig.media.get_by_shortcode("ABC123")    # → Media model
likers = ig.media.get_likers(media_pk)         # → List[UserShort]
comments = ig.media.get_comments_parsed(pk)    # → List[Comment]

ig.media.like(media_pk)
ig.media.comment(media_pk, "Nice! 🔥")
ig.media.save(media_pk)
ig.media.edit_caption(media_pk, "New caption")
ig.media.pin_comment(media_pk, comment_pk)

📰 Feed (GraphQL v2 + REST fallback)

# Home feed (GraphQL v2 — fast and reliable)
timeline = ig.feed.get_timeline(count=12)     # → {posts, has_next, end_cursor}
all_tl = ig.feed.get_all_timeline(max=50)     # full pagination

# User posts
ig.feed.get_user_feed(user_pk)                # REST endpoint
posts = ig.feed.get_all_posts(user_pk, max_posts=100, delay=2)

# Reels (GraphQL v2)
reels = ig.feed.get_reels_feed(count=10)      # Trending reels

# Saved/Liked/Tag
ig.feed.get_saved()                           # Saved collections
ig.feed.get_liked()                           # Liked posts
ig.feed.get_tag_feed("fashion")               # By hashtag
ig.feed.get_location_feed(location_pk)        # By location

📖 Stories

ig.stories.get_tray()
ig.stories.get_user_stories(user_pk)
ig.stories.mark_seen(story_pks)
ig.stories.get_highlights_tray(user_pk)
ig.stories.create_highlight("My Highlight", story_pks)
ig.stories.react_to_story(story_pk, "🔥")

🤝 Friendships

ig.friendships.follow(user_pk)
ig.friendships.unfollow(user_pk)
followers = ig.friendships.get_all_followers(user_pk)  # → List[UserShort]
following = ig.friendships.get_all_following(user_pk)  # → List[UserShort]
ig.friendships.block(user_pk)
ig.friendships.remove_follower(user_pk)
ig.friendships.mute(user_pk)
ig.friendships.restrict(user_pk)
ig.friendships.add_close_friend(user_pk)
ig.friendships.get_mutual_followers(user_pk)

💬 Direct Messages

ig.direct.get_inbox()
ig.direct.send_text(thread_id, "Hello!")
ig.direct.send_media(thread_id, media_pk)
ig.direct.create_thread([user_pk1, user_pk2])
ig.direct.send_link(thread_id, "https://example.com")
ig.direct.send_reaction(thread_id, item_id, "❤️")

📤 Upload

ig.upload.post_photo("photo.jpg", caption="My post")
ig.upload.post_video("video.mp4", caption="My reel")
ig.upload.post_story_photo("story.jpg")
ig.upload.post_reel("reel.mp4", caption="Trending")
ig.upload.post_carousel(["img1.jpg", "img2.jpg"], caption="Album")
ig.upload.delete_media(media_pk)

📥 Download

ig.download.download_media(media_pk)
ig.download.download_stories(user_pk)
ig.download.download_highlights(user_pk)
ig.download.download_profile_pic(username="cristiano")
ig.download.download_user_posts(user_pk, max_posts=50)
ig.download.download_by_url("https://instagram.com/p/ABC123/")

🔍 Search

ig.search.top_search("query")
users = ig.search.search_users("cristiano")    # → List[UserShort]
ig.search.search_hashtags("fashion")
ig.search.search_places("New York")

⚙️ Account

ig.account.get_current_user()
ig.account.edit_profile(full_name="New Name")
ig.account.set_private()
ig.account.set_public()
ig.account.get_blocked_users()
ig.account.get_login_activity()

🔐 Auth

ig.login("username", "password")
ig.auth.save_session("session.json")
ig.auth.load_session("session.json")
ig.auth.validate_session()
ig.auth.logout()

🌐 Public Anonymous API (23 methods, no login!)

ig = Instagram.anonymous(unlimited=True)

# Profile
ig.public.get_profile("cristiano")      # Full profile data (35+ fields)
ig.public.get_user_id("cristiano")      # → 173560420
ig.public.get_profile_pic_url("cristiano")  # HD profile pic URL
ig.public.is_public("cristiano")        # → True
ig.public.exists("cristiano")           # → True
ig.public.search("cristiano")           # Search users
ig.public.get_similar_accounts("cristiano")  # Similar accounts

# Content
ig.public.get_posts("cristiano", max_count=12)      # Recent posts
ig.public.get_all_posts("cristiano", max_count=50)   # All posts
ig.public.get_feed(user_id, max_count=12)            # Feed by user_id
ig.public.get_reels("cristiano", max_count=10)       # Reels
ig.public.get_comments("ABC123", max_count=20)       # Post comments
ig.public.get_highlights("cristiano")                 # Story highlights
ig.public.get_post_by_shortcode("ABC123")            # Single post
ig.public.get_post_by_url("https://instagram.com/p/ABC123/")
ig.public.get_media(media_id)                         # Media by ID
ig.public.get_media_urls("ABC123")                    # Download URLs

# Hashtag & Location
ig.public.get_hashtag_posts("fashion", max_count=10)
ig.public.get_hashtag_posts_v2("fashion", max_count=10)
ig.public.get_location_posts("213385402", max_count=10)

# Bulk operations
ig.public.bulk_profiles(["nike", "adidas"], workers=4)
ig.public.bulk_feeds([user_id1, user_id2], max_count=12, workers=4)

More Core Modules

ig.hashtags.get_info("fashion")        # Hashtag info
ig.insights.get_account_summary()      # Analytics
ig.notifications.get_activity()        # Notifications
ig.graphql.get_followers(user_pk)      # GraphQL queries
ig.location.search("New York")         # Location search
ig.collections.get_list()              # Saved collections

🔬 GraphQL API v2 (Modern doc_id Transport)

Direct access to Instagram's modern GraphQL endpoints with verified doc_ids. All methods use POST /graphql/query — faster and more reliable than REST.

# 👤 Profile — mini profile info (fast and lightweight)
card = ig.graphql.get_hover_card(user_id="173560420", username="cristiano")
print(card["follower_count"])    # 650000000
print(card["biography"])         # bio text
print(card["is_verified"])       # True
print(card["mutual_followers"])  # [{username, pk, ...}]

# 🔗 Similar accounts (80+ !)
suggested = ig.graphql.get_suggested_users(user_id="173560420")
for user in suggested["users"]:
    print(f"@{user['username']} | {user['full_name']}")
# → @messi, @neymar, @ronaldo, ... (~80 similar accounts)

# 📷 User posts (GraphQL — with pagination)
data = ig.graphql.get_user_posts_v2("cristiano")
for post in data["posts"]:
    print(f"{post['shortcode']} | ❤️{post['like_count']} | {post['caption'][:50]}")

# 💬 Comments (GraphQL v2)
data = ig.graphql.get_comments_v2(media_pk="3843229444966511752", count=20)
for c in data["comments"]:
    print(f"@{c['user']['username']}: {c['text'][:50]} | ❤️{c['like_count']}")

# ❤️ Like a post (mutation)
result = ig.graphql.like_media(media_id="3843229444966511752")
print(result["success"])  # True

# 📺 Home timeline (GraphQL v2 — root + pagination)
timeline = ig.graphql.get_timeline_v2(count=12)
for post in timeline["posts"]:
    print(f"@{post['user']['username']} | {post['product_type']} | ❤️{post['like_count']}")

# 🎬 Trending reels
reels = ig.graphql.get_reels_trending_v2(count=10)
for reel in reels["posts"]:
    print(f"@{reel['user']['username']} | ❤️{reel['like_count']}")

# 🔖 Saved collections
saved = ig.graphql.get_saved_v2()
for col in saved["posts"]:
    print(f"{col['collection_name']} | {col['media_count']} items")

Available doc_ids (16 verified):

🛠️ Advanced Tools

📊 Analytics

report = ig.analytics.engagement_rate("cristiano")
times = ig.analytics.best_posting_times("nike")
analysis = ig.analytics.content_analysis("adidas")
summary = ig.analytics.profile_summary("messi")
result = ig.analytics.compare(["nike", "adidas", "puma"])

📤 Export (CSV / JSON)

ig.export.followers_to_csv("nike", "followers.csv", max_count=5000)
ig.export.following_to_csv("nike", "following.csv")
ig.export.post_likers("media_pk", "likers.csv")
ig.export.to_json("cristiano", "profile.json", include_posts=True)

🌱 Growth Engine

ig.growth.follow_users_of("competitor", count=20)
ig.growth.unfollow_non_followers(max_count=50)
non_followers = ig.growth.get_non_followers()
fans = ig.growth.get_fans()
ig.growth.add_whitelist(["friend1", "friend2"])

🤖 Automation

ig.automation.comment_on_hashtag("fashion", templates=["Nice! 🔥", "Love it! ❤️"])
ig.automation.auto_like_feed(count=20)
ig.automation.auto_like_hashtag("travel", count=30)
ig.automation.watch_stories("target_user")

📅 Scheduler

ig.scheduler.post_at("2026-03-01 09:00", photo="post.jpg", caption="Scheduled!")
ig.scheduler.story_at("2026-03-01 12:00", photo="story.jpg")
ig.scheduler.reel_at("2026-03-01 18:00", video="reel.mp4", caption="Reel time!")
ig.scheduler.start()  # Background worker

👁️ Account Monitor

watcher = ig.monitor.watch("cristiano")
watcher.on_new_post(lambda data: print("New post!"))
watcher.on_follower_change(lambda old, new: print(f"{old} → {new}"))
watcher.on_bio_change(lambda old, new: print(f"Bio changed!"))
ig.monitor.start(interval=300)  # Check every 5 min

📥 Bulk Download

ig.bulk_download.all_posts("cristiano", output_dir="./downloads")
ig.bulk_download.all_stories("cristiano", output_dir="./downloads")
ig.bulk_download.everything("cristiano", output_dir="./downloads")

🔬 Hashtag Research

analysis = ig.hashtag_research.analyze("python")
related = ig.hashtag_research.related("python", count=30)
suggestions = ig.hashtag_research.suggest("coding", count=20, mix="balanced")
comparison = ig.hashtag_research.compare(["python", "javascript", "rust"])

🗃️ Data Pipeline (SQLite / JSONL)

ig.pipeline.to_sqlite("cristiano", "data.db", include_posts=True, include_followers=True)
ig.pipeline.to_jsonl("cristiano", "data.jsonl", max_posts=100)

🧠 AI Hashtag Suggester

result = ig.ai_suggest.hashtags_from_caption("Beautiful sunset at the beach")
profile_tags = ig.ai_suggest.hashtags_for_profile("cristiano")
captions = ig.ai_suggest.caption_ideas("travel", style="casual", count=5)

👥 Audience Finder

lookalike = ig.audience.find_lookalike("competitor", count=50)
overlap = ig.audience.overlap("account_a", "account_b")
insights = ig.audience.insights("my_account")

💬 Comment Manager

comments = ig.comment_manager.get_comments(media_pk, sort="top")
ig.comment_manager.auto_reply(media_pk, keyword="price?", reply="DM us!")
ig.comment_manager.delete_spam(media_pk)
sentiment = ig.comment_manager.sentiment(media_pk)

🧪 A/B Testing

test = ig.ab_test.create("Caption Test", variants={
    "A": {"caption": "Short and sweet"},
    "B": {"caption": "Long detailed caption with hashtags #test"},
})
ig.ab_test.record(test["id"], "A", likes=100, comments=20)
ig.ab_test.record(test["id"], "B", likes=150, comments=30)
result = ig.ab_test.results(test["id"])
print(f"Winner: {result['winner']}")

Pydantic Models

All API methods return typed Pydantic models with dict-like access:

user = ig.users.get_by_username("cristiano")

# Typed attributes
print(user.username)          # "cristiano"
print(user.follower_count)    # 650000000

# Dict-like access (backward compatible)
print(user["username"])       # "cristiano"

# Convert to dict
data = user.to_dict()

# Extra fields preserved (API changes won't break)
print(user.some_new_field)    # works!

Available models: User, UserShort, Media, Comment, Story, Highlight, DirectThread, DirectMessage, Location, Hashtag, Notification

Features

Speed Modes (Async)

# 🐢 SAFE  — 5 concurrent, human delays
async with AsyncInstagram.from_env(mode="safe") as ig: ...

# ⚡ FAST  — 15 concurrent, moderate delays
async with AsyncInstagram.from_env(mode="fast") as ig: ...

# 🚀 TURBO — 50 concurrent, minimal delays (proxy required)
async with AsyncInstagram.from_env(mode="turbo") as ig: ...

Testing & Quality

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=instaharvest_v2 --cov-report=term-missing

Current status:

• ✅ 6242 tests passed (43 skipped)
• 📊 ~86.4% code coverage

Project Structure

instaharvest_v2/
├── instagram.py           # Main class (sync)
├── async_instagram.py     # Main class (async)
├── client.py              # HTTP client (curl_cffi)
├── async_client.py        # Async HTTP client
├── anon_client.py         # Anonymous scraping client (sync)
├── async_anon_client.py   # Anonymous scraping client (async)
├── diagnostics.py         # API diagnostics (41 methods, sync+async)
├── parsers.py             # Shared parser functions (8 standalone)
├── challenge.py           # Challenge auto-resolver
├── anti_detect.py         # Anti-detection system
├── smart_rotation.py      # Multi-signal rotation coordinator
├── session_manager.py     # Session auto-refresh
├── proxy_manager.py       # Proxy rotation
├── rate_limiter.py        # Rate limiting
├── multi_account.py       # Multi-account manager
├── exceptions.py          # Error classes
├── models/                # Pydantic models
│   ├── user.py            # User, UserShort, BioParsed
│   ├── media.py           # Media, Caption
│   ├── comment.py         # Comment
│   ├── story.py           # Story, Highlight
│   ├── direct.py          # DirectThread, DirectMessage
│   ├── location.py        # Location
│   ├── notification.py    # Notification models
│   └── public_data.py     # PublicProfile, PublicPost
├── api/                   # API modules (31 sync + 31 async)
│   ├── users.py           # User profiles
│   ├── media.py           # Post interactions
│   ├── feed.py            # User feeds
│   ├── friendships.py     # Follow/unfollow
│   ├── search.py          # Search
│   ├── stories.py         # Stories & highlights
│   ├── direct.py          # Direct messages
│   ├── upload.py          # Photo/video upload
│   ├── download.py        # Media downloads
│   ├── auth.py            # Login/logout
│   ├── analytics.py       # Engagement analytics
│   ├── export.py          # CSV/JSON export
│   ├── growth.py          # Smart follow/unfollow
│   ├── automation.py      # Bot framework
│   ├── scheduler.py       # Post scheduling
│   ├── monitor.py         # Account monitoring
│   ├── bulk_download.py   # Bulk media download
│   ├── hashtag_research.py # Hashtag analysis
│   ├── pipeline.py        # Data pipeline (SQLite/JSONL)
│   ├── ai_suggest.py      # AI hashtag/caption
│   ├── audience.py        # Lookalike audience
│   ├── comment_manager.py # Comment management
│   ├── ab_test.py         # A/B testing
│   ├── public_data.py     # Public data analytics
│   ├── discover.py        # Similar user discovery
│   └── async_*.py         # All 33 async mirrors
├── agent/                 # AI Agent system
│   ├── core.py            # InstaAgent main class
│   ├── providers/         # AI providers (13: Gemini, OpenAI, Claude, etc.)
│   ├── tools/             # 161 built-in tools
│   │   ├── instagram_tools.py  # Instagram tools (profile, posts, reels, comments)
│   │   ├── media_tools.py      # Media & social tools (download, follow, like)
│   │   ├── file_tools.py       # File I/O tools
│   │   ├── system_tools.py     # File management, sessions, system info
│   │   ├── analysis_tools.py   # Data analysis & charts
│   │   ├── network_tools.py    # HTTP, search, DM
│   │   ├── auth_tools.py       # Login, validate, logout
│   │   ├── analytics_tools.py  # Analytics, insights, audience, A/B test
│   │   ├── automation_tools.py # Automation, scheduler, monitor
│   │   ├── pipeline_tools.py   # Pipeline, bulk download, AI suggest
│   │   └── utility_tools.py    # JSON, CSV, calculate, merge, download
│   ├── memory.py          # Conversation memory
│   ├── templates.py       # 10 task templates
│   ├── tui.py             # Terminal UI (Rich)
│   ├── web.py             # Web UI (FastAPI)
│   ├── webhook.py         # Notifications (Telegram, Discord)
│   ├── cost_tracker.py    # Token usage & pricing
│   └── vision.py          # Multimodal image analysis
tests/                     # 6242 tests
docs/                      # MkDocs documentation
.github/workflows/         # CI/CD pipeline

CI/CD

GitHub Actions pipeline (.github/workflows/ci.yml):

⚠️ Legal Disclaimer

This library is an unofficial, third-party tool designed for educational and research purposes only. It is not affiliated with, authorized, maintained, sponsored, or endorsed by Instagram or Meta Platforms, Inc.

By using this software, you agree that:

1. You are solely responsible for any actions you take using this library.
2. The authors and maintainers are NOT responsible or liable for any bans, blocks, suspensions, or other penalties applied to your Instagram accounts or IP addresses.
3. You will use this tool in compliance with Instagram's Terms of Service and all applicable local laws.

Use at your own risk. The software is provided "AS IS", without warranty of any kind.

License

MIT License. See LICENSE for details.