Metadata-Version: 2.4
Name: instagram-hindsight
Version: 0.1.1
Summary: Guest-session Instagram scraper for public profiles, posts, and reels
Project-URL: Homepage, https://github.com/gautham-fyi/instagram-hindsight
Project-URL: Repository, https://github.com/gautham-fyi/instagram-hindsight
Project-URL: Issues, https://github.com/gautham-fyi/instagram-hindsight/issues
Project-URL: Documentation, https://github.com/gautham-fyi/instagram-hindsight#readme
Author-email: gautham-fyi <315128611+gautham-fyi@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: graphql,guest-session,instagram,reels,scraper
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.9
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# instagram-hindsight

[![PyPI](https://img.shields.io/pypi/v/instagram-hindsight.svg)](https://pypi.org/project/instagram-hindsight/)
[![Python](https://img.shields.io/pypi/pyversions/instagram-hindsight.svg)](https://pypi.org/project/instagram-hindsight/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![GitHub](https://img.shields.io/badge/GitHub-gautham--fyi%2Finstagram--hindsight-181717?logo=github)](https://github.com/gautham-fyi/instagram-hindsight)

```text
$ pip install instagram-hindsight

$ instagram-hindsight profile
```

**instagram-hindsight** scrapes public Instagram profiles using a guest web session — no Instagram login required.

- fetches public profile metadata (followers, bio, verification, …),
- paginates posts via Instagram’s web GraphQL timeline,
- paginates reels via the clips API,
- normalizes likes, comments, views, captions, and permalinks,
- optionally routes traffic through a proxy,
- on HTTP 401/403 during pagination, opens a new guest session and retries the same page.

```text
instagram-hindsight [--max-pages N] [--posts-only | --reels-only]
                    [--proxy PROXY_URL] [-o OUTPUT.json]
                    profile
```

---

## Install

From [PyPI](https://pypi.org/project/instagram-hindsight/):

```bash
pip install instagram-hindsight
```

From a local checkout:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

Requires **Python 3.9+**.

---

## Command-line usage

Scrape a public profile (profile JSON, posts, and reels):

```bash
instagram-hindsight instagram
```

Limit pagination depth (each “page” is typically ~12 items):

```bash
instagram-hindsight instagram --max-pages 5
```

Posts only or reels only:

```bash
instagram-hindsight nasa --posts-only
instagram-hindsight nasa --reels-only
```

Use a proxy (or set `PROXY_URL`):

```bash
instagram-hindsight instagram --proxy "http://user:pass@host:port"
```

### Proxy tips

Free / shared datacenter proxies almost always get **HTTP 429** (Too Many Requests) on Instagram’s guest endpoints — even when a guest session cookie is obtained successfully. For reliable scrapes, use **rotating residential proxies**.

| Proxy type | Typical result |
|------------|----------------|
| None (direct) | Works for light use; rate-limits quickly |
| Free / shared datacenter | Session may open; profile/media calls return **429** |
| Rotating residential | Best reliability for pagination and retries |

You can also pass a pool to the Python client (`proxy_pool=[...]`); on auth failures the client opens a new guest session and may pick another proxy from the pool.

Write to a specific file:

```bash
instagram-hindsight instagram -o out.json --max-pages 2
```

Equivalent module form:

```bash
python -m instagram_hindsight instagram --max-pages 2 -v
```

---

## Python API

One-shot helper:

```python
from instagram_hindsight import scrape_account

data = scrape_account("instagram", max_pages=2)
print(data["profile"]["followers_count"])
print(len(data["posts"]), len(data["reels"]))
```

Reusable client:

```python
from instagram_hindsight import InstagramGuestClient

client = InstagramGuestClient(
    proxy="http://user:pass@host:port",  # optional
    max_pages=10,
    delay=1.0,
)
data = client.scrape_account("nasa", include_posts=True, include_reels=True)
```

Lower-level building blocks are also exported:

```python
from instagram_hindsight import (
    get_guest_session,
    fetch_profile,
    fetch_all_media,
    fetch_reels_only,
)
```

### Return shape

```python
{
  "profile": {
    "username": "...",
    "user_id": "...",
    "followers_count": 0,
    "following_count": 0,
    "posts_count": 0,
    "biography": "...",
    "is_private": False,
    "is_verified": False,
    # ...
  },
  "posts": [
    {
      "id": "...",
      "shortcode": "...",
      "type": "image" | "carousel" | "video",
      "likes": 0,
      "comments": 0,
      "views": None,
      "caption": "...",
      "link": "https://www.instagram.com/p/...",
      "date": "2026-01-01T00:00:00+00:00",
    },
    # ...
  ],
  "reels": [
    {
      "id": "...",
      "shortcode": "...",
      "type": "reel",
      "likes": 0,
      "comments": 0,
      "views": 0,
      "shares": 0,
      "link": "https://www.instagram.com/reel/...",
      # ...
    },
    # ...
  ],
}
```

---

## How it works

instagram-hindsight does **not** use the official Meta Graph API and does **not** require `--login`.

It opens an anonymous guest session against Instagram’s website, then calls public web endpoints:

| Data     | Endpoint                                      |
|----------|-----------------------------------------------|
| Profile  | `/api/v1/users/web_profile_info/`             |
| Posts    | `/graphql/query/` (timeline media)            |
| Reels    | `/api/v1/clips/user/`                         |

Sessions are short-lived cookie jars (`csrftoken` + guest headers). They are not persisted to disk. If a page returns **401/403**, a new guest session is created and that page is retried (with or without a proxy).

Private profiles are **not** supported.

---

## Contributing

This is an open-source project. Issues and pull requests that improve reliability, docs, or packaging are welcome.

Suggested local setup:

```bash
pip install -e ".[dev]"
python -m instagram_hindsight instagram --max-pages 1 -v
python -m build
```

---

## Disclaimer

**instagram-hindsight** is in no way affiliated with, authorized, maintained, or endorsed by Instagram, Meta Platforms, Inc., or any of their affiliates or subsidiaries. This is an independent and unofficial project. Use at your own risk.

Automated access to Instagram may violate Instagram’s Terms of Use. You are solely responsible for how you use this software and for complying with applicable laws and third-party terms.

instagram-hindsight is licensed under the MIT License. See [LICENSE](LICENSE) for details.
