herascrape: Instagram API client for Python

herascrape is the official Python client for the herascrape Instagram API. It is an Instagram scraper API that reads Instagram's private API for you and hands back Instagram's own JSON: profiles, followers, posts, reels, comments, hashtags, locations, audio, stories and search. You do not manage Instagram accounts, devices or proxies.

from herascrape import Client

client = Client(api_key="hs_live_xxxxxxxx")

user = client.user_by_username(username="instagram")
print(user["username"], user["follower_count"])

for follower in client.iter_user_followers(user["pk"], max_items=100):
    print(follower["username"])

• 37 endpoints, one method each, plus lazy iter_* paginators for the lists.
• Sync (Client) and async (AsyncClient) with the same surface.
• Typed exception hierarchy: NotFoundError, PrivateAccountError, RateLimitError and the rest.
• Retries with backoff, Retry-After handling and a client-side rate limiter.
• Typed package (py.typed), Python 3.10+, one dependency: httpx.

Documentation: herascrape.com/docs.

Install

pip install herascrape

Authentication

Create a key in the dashboard; the client sends it in the x-api-key header. Pass it to the constructor:

from herascrape import Client

client = Client(api_key="hs_live_xxxxxxxx")

Or leave it out and the client reads HERASCRAPE_API_KEY from the environment. With no key in either place, constructing a client raises AuthenticationError. Keep keys out of source control.

Billing is per successful call, and failed calls are not billed. See pricing.

Usage

Every method returns the response data as a plain dict, exactly as Instagram sent it. Check an endpoint's What comes back section in the docs before mapping fields.

from herascrape import Client

client = Client()

# Profiles: look a username up once, then use the numeric pk.
user = client.user_by_username(username="instagram")
page = client.user_followers(user["pk"])
print(len(page["items"]), page["has_more"], page["next_cursor"])

# Pagination: iter_* walks the pages lazily.
for reel in client.iter_user_reels(user["pk"], max_items=50):
    print(reel["code"])

# Search: session UUIDs are generated for you.
for hit in client.search_users(query="nike")["items"]:
    print(hit["pk"], hit["username"])

# Posts take a pk or a shortcode.
post = client.post("B4XpqViUFUI")
print(post["like_count"], post["comment_count"])

# Convert between a media pk and its shortcode.
print(client.resolve_media(code="B4XpqViUFUI"))

List responses carry items, next_cursor and has_more. post_comments and user_posts keep Instagram's own paging shape, so page those by hand; see the docs.

Async

import asyncio

from herascrape import AsyncClient


async def main() -> None:
    async with AsyncClient() as client:
        user = await client.user_by_username(username="instagram")
        async for follower in client.iter_user_followers(
            user["pk"], max_items=100
        ):
            print(follower["username"])


asyncio.run(main())

Errors

Every exception inherits from HerascrapeError. API errors are HerascrapeAPIError subclasses carrying status_code, error_code, detail and request_id.

from herascrape import Client, PrivateAccountError, ProfileNotFoundError

client = Client()

try:
    followers = client.user_followers("25025320")
except PrivateAccountError:
    print("private account")
except ProfileNotFoundError:
    print("no such profile")

Retries and rate limiting

The client retries connection errors and timeouts, 429, 502, 503 and invalid_cursor up to max_retries times (default 3), backing off from 0.5 s to 8 s with jitter. A 429 with a Retry-After header waits that long, capped at 300 s. It also throttles requests on the client with a token bucket that defaults to 50 requests per second. Match it to your key's limit:

from herascrape import Client, RateLimit

client = Client(rate_limit=RateLimit(rate=10, period="s"))
client = Client(rate_limit=None)  # no client-side limit

Other constructor options: timeout (seconds, default 10), max_retries, and base_url (default https://api.herascrape.com).

Endpoints

All 37 endpoints are GETs. The full table with paths is in the repository README.

Coming from HikerAPI? The migration guide maps each path to its herascrape equivalent.

Disclaimer

herascrape is not affiliated with, authorized, maintained, or endorsed by Instagram or Meta. Instagram is a trademark of Meta Platforms, Inc. You are responsible for using the data in line with applicable law and Instagram's terms.

License

MIT