brightdata-instagram-scraper 0.1.0__py3-none-any.whl

brightdata_instagram_scraper-0.1.0.dist-info/METADATA

@@ -0,0 +1,542 @@
+Metadata-Version: 2.5
+Name: brightdata-instagram-scraper
+Version: 0.1.0
+Summary: Instagram scraper in Python: profiles, posts, reels and comments as JSON, on the Bright Data Instagram Scraper API (Web Scraper API). No Instagram login, no browser. 5,000 free credits a month.
+Project-URL: Homepage, https://github.com/brightdata/instagram-scraper
+Project-URL: Documentation, https://docs.brightdata.com/products/scrapers/instagram/introduction
+Project-URL: Source, https://github.com/brightdata/instagram-scraper
+Project-URL: Issues, https://github.com/brightdata/instagram-scraper/issues
+Project-URL: Changelog, https://github.com/brightdata/instagram-scraper/blob/main/CHANGELOG.md
+Author: Bright Data
+License: Apache-2.0
+License-File: LICENSE
+Keywords: bright-data,instagram,instagram-api,instagram-scraper,profiles,reels,scraper,web-scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Requires-Dist: brightdata-sdk<3,>=2.5.2
+Requires-Dist: rich<15,>=13
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+[![Scrape Instagram data with the Instagram Scraper API: profiles, posts, reels, search. Collect or discover by URL and username. Start free.](https://raw.githubusercontent.com/brightdata/instagram-scraper/main/.github/banner.png)](https://brightdata.com/products/web-scraper/instagram?utm_source=github&utm_medium=referral&utm_content=instagram-scraper)
+
+# Instagram scraper for Python
+
+Scrape Instagram profiles, posts, reels and comments to JSON with Python. No Instagram login, no access token, no browser.
+Built on the [Bright Data Instagram Scraper API](https://brightdata.com/products/web-scraper/instagram?utm_source=github&utm_medium=referral&utm_content=instagram-scraper). New accounts get 5,000 free credits a month.
+
+[![Live check](https://github.com/brightdata/instagram-scraper/actions/workflows/live.yml/badge.svg)](https://github.com/brightdata/instagram-scraper/actions/workflows/live.yml)
+[![last verified](https://img.shields.io/badge/last%20verified-12%20Nov%202026-brightgreen)](https://github.com/brightdata/instagram-scraper/actions/workflows/live.yml) <!-- verified: rewritten by the daily run -->
+
+[Quickstart](#how-to-scrape-instagram-data-with-python) · [No login](#scrape-instagram-without-login-or-an-access-token) · [CLI](#bulk-instagram-scraper-cli) · [Endpoints](#scrape-instagram-posts-profiles-reels-and-comments) · [Data](#instagram-post-data-fields-json) · [Errors](#instagram-scraper-errors) · [MCP and Claude Code](#instagram-mcp-server-and-claude-code-skill) · [Free credits](#is-this-instagram-scraper-free) · [Docs](https://docs.brightdata.com/products/scrapers/instagram/introduction) · [Support](#support)
+
+Instagram profiles, posts, reels and comments as JSON, in Python. No Instagram
+login, no browser. Built on the
+[Bright Data Instagram Scraper API](https://brightdata.com/products/web-scraper/instagram?utm_source=github&utm_medium=referral&utm_content=instagram-scraper).
+
+Uses the [Bright Data Python SDK](https://github.com/brightdata/sdk-python).
+Full API docs:
+[Instagram Scraper API](https://docs.brightdata.com/products/scrapers/instagram/introduction).
+
+Also here: a one-command CLI for posts, and the
+[Bright Data CLI](#instagram-mcp-server-and-claude-code-skill), which needs no Python at all.
+
+## How to scrape Instagram data with Python
+
+Python 3.10 or newer.
+
+```bash
+pip install brightdata-sdk
+export BRIGHTDATA_API_TOKEN=YOUR_API_KEY
+```
+
+Get a token from the
+[Bright Data control panel](https://brightdata.com/cp/setting/users). A `.env`
+file in the project root works too, as long as the virtualenv is inside the
+project.
+
+Or skip the token. Run `npx -p @brightdata/cli bdata login` once: it opens a
+browser, and from then on the SDK finds the stored credentials on its own, for
+you and for any coding agent working in that terminal. Agents cannot click
+through the login, so do it yourself first. The same CLI scrapes Instagram
+directly; see [Instagram MCP server and Claude Code skill](#instagram-mcp-server-and-claude-code-skill).
+
+No account yet? [Create one](https://brightdata.com/cp/start); new accounts get
+[5,000 free credits a month](https://docs.brightdata.com/general/account/billing-and-pricing/free-tier).
+
+```python
+from brightdata import SyncBrightDataClient
+
+with SyncBrightDataClient(auto_create_zones=False) as client:
+    result = client.search.instagram.posts("https://www.instagram.com/nasa/", num_of_posts=5)
+    for post in result.data:
+        print(post["likes"], post["num_comments"], post["url"])
+```
+
+```
+2437761 4692 https://www.instagram.com/p/Db9IVmrDvQ4/
+104278 902 https://www.instagram.com/reel/DcMXl1IPNtB/
+553843 4101 https://www.instagram.com/p/DcOX3hWFiey/
+39490 324 https://www.instagram.com/reel/Dc4u1yKPj_s/
+119582 1535 https://www.instagram.com/reel/Dc37MPNSAZq/
+```
+
+Expect one to three minutes: the API runs a job and the SDK waits for it. One
+[credit](https://brightdata.com/pricing/web-scraper) per post.
+
+Pass `auto_create_zones=False` every time. Left on, the SDK creates zones on
+startup for Web Unlocker and SERP, two other Bright Data products this scraper
+never touches, and zone creation fails on accounts without a payment method
+([sdk-python#57](https://github.com/brightdata/sdk-python/issues/57)).
+
+## Scrape Instagram without login or an access token
+
+The Instagram Scraper API needs no Instagram account, no Meta access token and
+no Instagram business account. The only credential is a Bright Data API key,
+set as `BRIGHTDATA_API_TOKEN` or stored by `bdata login`.
+
+## Bulk Instagram scraper CLI
+
+The command in this repo runs the Python quickstart for several accounts at
+once and writes one JSON file.
+
+```bash
+pip install git+https://github.com/brightdata/instagram-scraper
+instagram-scraper nasa natgeo
+```
+
+```
+Fetching up to 5 recent posts per account, for: nasa, natgeo
+Usually one to three minutes each. One credit per post, 5,000 free per month.
+asking  @nasa...
+got     @nasa: 5 posts
+asking  @natgeo...
+got     @natgeo: 5 posts
+
+Saved 10 posts as JSON to instagram.json (34 fields per post)
+```
+
+In a terminal the `asking` lines are replaced by this, updating in place, so
+you can see it is working and how long it has been going:
+
+```
+⠹ @nasa 0:01:47
+```
+
+```
+--limit N    posts per account, default 5, minimum 1
+--out PATH   output file, default instagram.json
+```
+
+`python -m instagram_scraper` works too.
+
+Import it instead of running it, for `ok`, `note` and `error` per account
+instead of raw rows. `scrape` never raises for one bad account; check `ok`
+before reading `posts`:
+
+```python
+from instagram_scraper import scrape
+
+for outcome in scrape(["nasa", "zz_not_a_real_account_zz"], limit=1):
+    if outcome.ok:
+        print(f"{outcome.handle}: {len(outcome.posts)} posts")
+    else:
+        print(f"{outcome.handle} failed: {outcome.error}")
+```
+
+```
+nasa: 1 posts
+zz_not_a_real_account_zz failed: Crawler error: Cannot read properties of null (reading 'pk')
+```
+
+An account with nothing recent is a success with no posts. The reason lands in
+`note`, not `error`.
+
+## Scrape Instagram posts, profiles, reels and comments
+
+The command covers one endpoint. The SDK has eight, documented in the
+[Instagram Scraper API docs](https://docs.brightdata.com/products/scrapers/instagram/introduction).
+Every snippet below is complete
+and needs only `brightdata-sdk`: paste it as is. Every one of them runs in Actions each Monday, a smaller check
+runs every other day, and the badge at the top is the latest result.
+
+| you have | want | call |
+| --- | --- | --- |
+| a profile URL | recent posts | `client.search.instagram.posts(url, num_of_posts=5)` |
+| a username | the profile | `client.search.instagram.profiles("nasa")` |
+| a profile URL | the profile | `client.scrape.instagram.profiles(url)` |
+| a profile URL | recent reels | `client.search.instagram.reels(url, num_of_posts=5, timeout=420)` |
+| a profile URL | every reel ever | `client.search.instagram.reels_all(url)`, one credit per reel the account has posted |
+| post URLs | those posts | `client.scrape.instagram.posts([url, url])` |
+| reel URLs | those reels | `client.scrape.instagram.reels([url])` |
+| a post or reel URL | its comments | `client.scrape.instagram.comments(url)`, one credit per comment |
+
+Every one of these is an asynchronous job. The SDK triggers it, polls, and
+returns when it is ready. That is why a call takes one to three minutes, and
+why there is no faster path in Python. The API's
+[synchronous endpoint](https://docs.brightdata.com/api-reference/scrapers/synchronous-requests),
+20 URLs and a one-minute limit, is raw HTTP only.
+
+Error rows, like the empty-window one above, appear because the SDK asks for
+them with `include_errors=true`. The API default is off.
+
+`search` calls return a list in `result.data`. `scrape` calls with one URL
+return one record as a dict, and several as a list.
+
+### Scrape multiple Instagram accounts in one job
+
+A list of URLs is one job, not one per account.
+
+```python
+from brightdata import SyncBrightDataClient
+
+with SyncBrightDataClient(auto_create_zones=False) as client:
+    result = client.search.instagram.posts(
+        ["https://www.instagram.com/nasa/", "https://www.instagram.com/natgeo/"], num_of_posts=1
+    )
+    for post in result.data:
+        print(post["user_posted"], post["url"])
+```
+
+```
+nasa https://www.instagram.com/p/DcOX3hWFiey/
+natgeo https://www.instagram.com/reel/Dbru79IAdH-/
+```
+
+### Trigger now, fetch later
+
+For anything bigger than a few accounts, do not block a process for an hour.
+Trigger, keep the snapshot id, fetch when ready. Snapshots stay downloadable
+for 30 days.
+
+```python
+import time
+
+from brightdata import SyncBrightDataClient
+
+with SyncBrightDataClient(auto_create_zones=False) as client:
+    job = client.scrape.instagram.posts_trigger("https://www.instagram.com/p/Dc1W1uFj-CW/")
+    print("snapshot:", job.snapshot_id)
+    while (status := client.scrape.instagram.posts_status(job.snapshot_id)) not in ("ready", "failed"):
+        time.sleep(5)
+    print("status:", status)
+    record = client.scrape.instagram.posts_fetch(job.snapshot_id)[0]
+    print("fetched:", record["url"], "likes:", record["likes"])
+```
+
+```
+snapshot: sd_mtrapflrzynbfyid9
+status: ready
+fetched: https://www.instagram.com/p/Dc1W1uFj-CW/ likes: 184
+```
+
+### Filter Instagram posts by date
+
+```python
+from brightdata import SyncBrightDataClient
+
+with SyncBrightDataClient(auto_create_zones=False) as client:
+    result = client.search.instagram.posts(
+        "https://www.instagram.com/nasa/",
+        num_of_posts=3,
+        start_date="08-01-2026",   # MM-DD-YYYY
+        end_date="09-07-2026",
+    )
+    for post in result.data:
+        print(post["date_posted"], post["content_type"], post["url"])
+```
+
+```
+2026-08-12T21:28:58.000Z Image https://www.instagram.com/p/Db9IVmrDvQ4/
+2026-08-18T19:37:40.000Z Reel https://www.instagram.com/reel/DcMXl1IPNtB/
+2026-08-19T14:11:47.000Z Image https://www.instagram.com/p/DcOX3hWFiey/
+```
+
+`post_type="Post"` keeps posts only and `post_type="Reels"` keeps reels only,
+both verified. The SDK's docstring says `"Reel"`; that spelling returns an
+error row and no reels ([sdk-python#59](https://github.com/brightdata/sdk-python/issues/59)).
+`posts_to_not_include` takes a list of post IDs.
+
+### Scrape an Instagram profile by username
+
+No URL needed. The record carries the account's followers count and post count.
+
+```python
+from brightdata import SyncBrightDataClient
+
+with SyncBrightDataClient(auto_create_zones=False) as client:
+    profile = client.search.instagram.profiles("nasa").data[0]
+    print(profile["account"], "followers:", profile["followers"], "posts:", profile["posts_count"])
+```
+
+```
+nasa followers: 104387874 posts: 4913
+```
+
+### Scrape comments from an Instagram post or reel
+
+One credit per comment, so check `num_comments` on the post first.
+
+```python
+from brightdata import SyncBrightDataClient
+
+with SyncBrightDataClient(auto_create_zones=False) as client:
+    comments = client.scrape.instagram.comments("https://www.instagram.com/p/Dc1W1uFj-CW/").data
+    print(len(comments), "comments; first:", repr(comments[0]["comment"][:60]))
+```
+
+```
+6 comments; first: 'Those two destroyed jazz'
+```
+
+### Scrape Instagram reels from a profile
+
+Reels discovery is slower. The default 180-second timeout expired; 420 did not.
+
+```python
+from brightdata import SyncBrightDataClient
+
+with SyncBrightDataClient(auto_create_zones=False) as client:
+    reels = client.search.instagram.reels("https://www.instagram.com/nasa/", num_of_posts=2, timeout=420)
+    for reel in reels.data:
+        print(reel["date_posted"], reel["url"])
+```
+
+```
+2026-08-18T19:37:40.000Z https://www.instagram.com/p/DcMXl1IPNtB/
+2026-09-05T01:00:10.000Z https://www.instagram.com/p/Dc4u1yKPj_s/
+```
+
+## Instagram post data fields (JSON)
+
+The fields most people want:
+
+```
+url  date_posted  description  hashtags  likes  num_comments  user_posted
+```
+
+The code hardcodes no field list. Whatever the API returns lands in
+`result.data`, and in the command's file.
+A collaborative post carries the co-author's handle in `user_posted`, so a post
+fetched from nasa can say `nasajohnson`; `coauthor_producers` lists everyone.
+
+<!-- fields:start -->
+<details>
+<summary>All 44 fields, with type and description</summary>
+
+Regenerated every day from the dataset schema, via
+`client.datasets.instagram_posts.get_metadata()`, so it cannot go stale. A
+post carries the fields that apply to it; the sample file has 34
+of these 44.
+
+| field | type | description |
+| --- | --- | --- |
+| `url` | url | The direct URL of the Instagram post |
+| `user_posted` | text | Username of the post creator |
+| `description` | text | Post text description |
+| `hashtags` | array | Hashtags used in the post |
+| `num_comments` | number | Number of comments |
+| `date_posted` | date | Post publication date |
+| `likes` | number | Number of likes on the post |
+| `photos` | array | URLs of attached photos, URLs can be expired due to Instagram policy |
+| `videos` | array | URLs of attached videos, URLs can be expired due to Instagram policy |
+| `location` | array | Geographical location associated with the post |
+| `location_details` | object | Detailed geographical location metadata as returned by Instagram |
+| `latest_comments` | array | Recent comments on the post |
+| `post_id` | text | Unique post identifier |
+| `discovery_input` | object | Discovery input values used to trigger the collection |
+| `has_handshake` | boolean | Indicates if the post has a handshake (collaborative agreement between accounts) |
+| `display_url` | text | Deprecated: previously used as the display URL of the post media |
+| `shortcode` | text | The shortcode of the Instagram post, used in the post URL path |
+| `content_type` | text | The type of content: Posts or Reels |
+| `pk` | text | The primary key of the media content as assigned by Instagram |
+| `content_id` | text | The content ID of the media item |
+| `engagement_score_view` | number | Video view count used as an engagement score metric |
+| `thumbnail` | text | The URL of the post's display image or video thumbnail |
+| `video_view_count` | text | The number of views on the video post |
+| `product_type` | text | The type of product associated with the post, such as 'clips' for Reels |
+| `coauthor_producers` | array | List of co-authors or producers who collaborated on the post |
+| `tagged_users` | array | List of users tagged in the post |
+| `video_play_count` | number | The number of times the video has been played |
+| `followers` | number | Number of followers the post owner has at the time of collection |
+| `posts_count` | number | The total count of posts made by the account at the time of collection |
+| `profile_image_link` | text | URL linking directly to the Instagram profile image of the post owner |
+| `is_verified` | boolean | Indicates whether the post owner's account is verified |
+| `is_paid_partnership` | boolean | Indicates whether the post is a sponsored or paid partnership |
+| `partnership_details` | object | Details of the paid partnership brand associated with the post |
+| `user_posted_id` | text | The Instagram user ID of the account that posted the post |
+| `post_content` | array | List of media items (photos or videos) attached to the post, including carousel items |
+| `audio` | object | Audio track metadata associated with the post or Reel |
+| `profile_url` | url | URL of the Instagram profile that posted the post |
+| `videos_duration` | array | List of video durations for each video attached to the post |
+| `images` | array | List of image objects attached to the post |
+| `alt_text` | text | Accessibility alt text for the post's main image: descriptive text that conveys the meaning of the image for blind or visually impaired users |
+| `photos_number` | number | Total number of photos attached to the post |
+| `audio_url` | url | Direct URL of the audio track used in the post |
+| `thumbnail_array` | array | Deprecated: array of thumbnail URLs for the post media |
+| `country` | text | Some profiles are restricted by location. Please set the country code in Alpha-2 format |
+
+</details>
+<!-- fields:end -->
+
+<details>
+<summary>The start of a real output file, from <code>instagram-scraper nasa --limit 1</code></summary>
+
+```json
+{
+  "generated_at": "2026-08-14T11:01:05.410349+00:00",
+  "handles": [
+    {
+      "handle": "nasa",
+      "posts": [
+        {
+          "url": "https://www.instagram.com/p/Db_SePSltfz/",
+          "user_posted": "nasa",
+          "description": "A dance of darkness and light\n\nThis composite image shows the total solar eclipse from beginning to end, as seen in San Mill\u00e1n de los Caballeros, Spain on Aug. 12, 2026.\n\nWhile eclipses are beautiful and magical to experience, they're also a great opportunity for science. Total solar eclipses are particularly important because they allow scientists to see a part of the Sun\u2019s atmosphere known as the corona. The corona is too faint to see except when the bright light of the Sun is blocked.\n\nStudying the corona is key to answering important questions about how heat and energy are transferred from the Sun out into the solar wind, the constant stream of particles that the Sun spews into the solar system.\n\nCredit: NASA\n\n#NASA #Sun #SolarEclipse #Moon",
+          "hashtags": [
+            "#NASA",
+            "#Sun",
+            "#SolarEclipse",
+            "#Moon"
+          ],
+          "num_comments": 1109,
+          "date_posted": "2026-08-13T17:36:02.000Z",
+          "likes": 627573,
+          "photos": [
+  ...
+```
+
+The whole file, one post with every field, is
+[examples/sample_output.json](https://github.com/brightdata/instagram-scraper/blob/main/examples/sample_output.json).
+
+</details>
+
+## Instagram scraper errors
+
+| you see | what it means |
+| --- | --- |
+| `API token required but not found.` | Exit 2, before any request. Set the token. |
+| `failed  @name: ...` | Exit 1. No such account, usually a typo. The wording varies: "Sorry, this page isn't available." and "Crawler error: Cannot read properties of null" are both this. |
+| `got     @name: 0 posts, the account has no public posts in the period searched` | Exit 0, and correct. The API reports an empty window as an error row. |
+| `failed  @name: timeout` | Exit 1. A request gives up after 180 seconds. Run it again. |
+
+Any failure exits 1, so a run is safe to gate a script on.
+
+From the SDK, the same conditions look like this:
+
+| you see | what it means |
+| --- | --- |
+| `AuthenticationError: Unauthorized (401)` | The token is set but wrong. |
+| `result.success` is `False`, `result.status` is `"timeout"` | The SDK gave up waiting, 180 seconds by default. Pass `timeout=420`, or run it again. |
+| a row in `result.data` with an `error` key | The API's answer for one input: an empty window, or no such account. The other rows are fine. |
+
+## Instagram MCP server and Claude Code skill
+
+No Python, nothing installed. Paste both lines; the first opens a browser
+once, or use `bdata login --device` over SSH and in CI:
+
+```bash
+npx -p @brightdata/cli bdata login
+npx -p @brightdata/cli bdata pipelines run gd_lk5ns7kz21pck8jpis collect_by_url "https://www.instagram.com/p/Db_SePSltfz/"
+```
+
+The CLI runs a scraper by its dataset ID. The four Instagram scrapers each
+take a post, reel or profile URL and return that one record;
+`bdata pipelines search instagram` lists their IDs and methods.
+
+`npx skills add brightdata/skills` teaches Claude Code, Cursor and Codex these
+commands and the docs, so plain language works afterwards. Full guide:
+[Bright Data for your coding agent](https://docs.brightdata.com/quickstart-coding-agent).
+
+No terminal, for a hosted assistant? The
+[Bright Data MCP server](https://github.com/brightdata/brightdata-mcp#which-tool-to-use)
+has the same four Instagram tools, one URL each, in its `social` group, which
+is off unless you ask for it:
+
+    https://mcp.brightdata.com/mcp?token=YOUR_API_TOKEN&groups=social
+
+An agent can also open the account itself, no signup form:
+[agent registration](https://brightdata.com/auth.md). Everything else Bright
+Data connects to, from LangChain to Zapier and n8n:
+[integrations](https://docs.brightdata.com/integrations/introduction).
+
+<details>
+<summary>Every Instagram command the CLI has, each run today</summary>
+
+Four scrapers, each run with `bdata pipelines run <dataset_id> collect_by_url`:
+profiles `gd_l1vikfch901nx3by4`, posts `gd_lk5ns7kz21pck8jpis`, reels
+`gd_lyclm20il4r5helnj` and comments `gd_ltppn085pokosxh13`. Each takes URLs,
+prints JSON, and costs one credit per record. Prefix each command with `npx -p @brightdata/cli`, or install once with
+`npm i -g @brightdata/cli`.
+
+```bash
+bdata pipelines run gd_l1vikfch901nx3by4 collect_by_url "https://www.instagram.com/nasa/" --pretty
+```
+
+1 record, 25 fields, 50 seconds. `"account": "nasa"`, `"followers": 104396028`.
+
+```bash
+bdata pipelines run gd_lk5ns7kz21pck8jpis collect_by_url "https://www.instagram.com/p/Dc1W1uFj-CW/" --format csv -o posts.csv
+```
+
+37 seconds. The CSV header carries the same field names as the table below.
+
+```bash
+bdata pipelines run gd_lyclm20il4r5helnj collect_by_url "https://www.instagram.com/reel/DcMXl1IPNtB/" --pretty
+```
+
+1 record, 25 fields, 23 seconds.
+
+```bash
+bdata pipelines run gd_ltppn085pokosxh13 collect_by_url "https://www.instagram.com/p/Dc1W1uFj-CW/" --pretty
+```
+
+5 records, 11 fields, 9 seconds. One credit per comment, so check the post's
+`num_comments` first.
+
+`bdata pipelines info <dataset_id> <method>` shows a scraper's input fields.
+`bdata pipelines run --help` shows `--format json|csv|ndjson|jsonl`, `-o FILE`,
+`--timeout` and `--async`. CLI 0.4.0 replaced the old
+`bdata pipelines instagram_posts <url>` form with these commands.
+
+</details>
+
+## Is this Instagram scraper free?
+
+New Bright Data accounts get
+[5,000 free credits a month](https://docs.brightdata.com/general/account/billing-and-pricing/free-tier).
+Posts, reels and profiles cost one credit per record, and comments one credit
+per comment, so the free credits cover 5,000 posts a month.
+[Pricing](https://brightdata.com/pricing/web-scraper) lists the rates after that.
+
+## Support
+
+Bugs in this repo:
+[open an issue](https://github.com/brightdata/instagram-scraper/issues), and
+[CONTRIBUTING.md](https://github.com/brightdata/instagram-scraper/blob/main/CONTRIBUTING.md) says what to put in it.
+Anything about the API, your account or your credits:
+[Bright Data support](https://brightdata.zendesk.com/hc/en-us/requests/new).
+
+## License
+
+[Apache 2.0](LICENSE).
+
+## Instagram scraper for Node.js
+
+The same Instagram scraper is available for Node.js: [brightdata/instagram-scraper-node](https://github.com/brightdata/instagram-scraper-node).
+
+## More open source scrapers from Bright Data
+
+Other Python scrapers built the same way, with live-verified examples:
+
+- [TikTok scraper for Python](https://github.com/brightdata/tiktok-scraper)
+- [Facebook scraper for Python](https://github.com/brightdata/facebook-scraper)
+- [YouTube scraper for Python](https://github.com/brightdata/youtube-scraper)

brightdata_instagram_scraper-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+instagram_scraper/__init__.py,sha256=nrzlAaCOQ4q2KXLxiVq_31Mq6uc9mIMEk-QFNN6bNUU,211
+instagram_scraper/__main__.py,sha256=OUqE_4OEa6hww5fHWLjatCBXV5GtQfHgsFwZqcB84GI,3029
+instagram_scraper/scrape.py,sha256=EQBmdr_D2KKKg3c3T4nkmROnGvQUpX6cFNhuJ73EkQI,6280
+brightdata_instagram_scraper-0.1.0.dist-info/METADATA,sha256=C_uPSHDVn558LPaszPpMYl_Xa4nRmCRzVJsZ11DaIzo,24471
+brightdata_instagram_scraper-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+brightdata_instagram_scraper-0.1.0.dist-info/entry_points.txt,sha256=N-LIuQgN2Xsoq-OoV0b2BSz1LMvebOXesWUVAAim14k,70
+brightdata_instagram_scraper-0.1.0.dist-info/licenses/LICENSE,sha256=yVuuHRzgI17MzTVgt3LsHvuX80innw--CmNPDCzO_iw,11358
+brightdata_instagram_scraper-0.1.0.dist-info/RECORD,,

brightdata_instagram_scraper-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

brightdata_instagram_scraper-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+instagram-scraper = instagram_scraper.__main__:main

brightdata_instagram_scraper-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

instagram_scraper/__init__.py

@@ -0,0 +1,6 @@
+"""An Instagram scraper on Bright Data's Scraper API."""
+
+from .scrape import Outcome, rows, scrape, scrape_handle, write
+
+__all__ = ["Outcome", "rows", "scrape", "scrape_handle", "write"]
+__version__ = "0.1.0"

instagram_scraper/__main__.py

@@ -0,0 +1,73 @@
+"""instagram-scraper nasa natgeo, or python -m instagram_scraper nasa natgeo"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from brightdata import BrightDataError
+from rich.progress import Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
+
+from .scrape import client_context, scrape_handle, write
+
+#: The SDK's own advice lists a Python parameter. A command has no such thing.
+NO_TOKEN = (
+    "API token required but not found.\n"
+    "  export BRIGHTDATA_API_TOKEN=YOUR_API_KEY   token: https://brightdata.com/cp/setting/users\n"
+    "  or run once: npx -p @brightdata/cli bdata login"
+)
+
+#: A spinner and a running clock, so a minute of waiting looks alive.
+WAITING = (SpinnerColumn(), TextColumn("{task.description}"), TimeElapsedColumn())
+
+
+def positive(value: str) -> int:
+    """Reject a limit the API would charge for and not honour."""
+    number = int(value)
+    if number < 1:
+        raise argparse.ArgumentTypeError(f"{value} is not 1 or more")
+    return number
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="instagram-scraper",
+        description="Scrape recent Instagram posts for one or more handles.",
+    )
+    parser.add_argument("handles", nargs="+", help="handles, with or without the @")
+    parser.add_argument("--limit", type=positive, default=5, help="posts per handle, default 5")
+    parser.add_argument("--out", default="instagram.json", help="output file, default %(default)s")
+    args = parser.parse_args(argv)
+
+    print(
+        f"Fetching up to {args.limit} recent posts per account, for: {', '.join(args.handles)}\n"
+        "Usually one to three minutes each. One credit per post, 5,000 free per month.",
+        flush=True,  # piped, an unflushed header would print after the error below
+    )
+
+    outcomes = []
+    try:
+        with client_context() as client, Progress(*WAITING, transient=True) as bar:
+            for handle in args.handles:
+                if not bar.console.is_terminal:
+                    print(f"asking  @{handle}...", flush=True)  # a log wants a line, not a spinner
+                task = bar.add_task(f"@{handle}")
+                outcome = scrape_handle(client, handle, args.limit)
+                bar.remove_task(task)
+                # markup off: an API message with brackets in it is not markup
+                bar.console.print(outcome.line(), markup=False, highlight=False)
+                outcomes.append(outcome)
+    except BrightDataError as exc:
+        # Almost always a missing token, which reads as a crash under a traceback.
+        print(NO_TOKEN if "token required" in str(exc) else exc, file=sys.stderr)
+        return 2
+
+    path = write(outcomes, args.out)
+    posts = [post for outcome in outcomes for post in outcome.posts]
+    fields = f" ({len(posts[0])} fields per post)" if posts else ""
+    print(f"Saved {len(posts)} posts as JSON to {path}{fields}")
+    return 0 if all(o.ok for o in outcomes) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

instagram_scraper/scrape.py

@@ -0,0 +1,170 @@
+"""Get a creator's recent Instagram posts by handle.
+
+    handle -> search.instagram.posts -> full post records
+
+No second collection step. Discovery returns the complete record: 34 fields on
+2026-08-14, against 33 from collecting the same post afterwards. The extra call
+cost a record per post, added 75 seconds, and dropped every reel.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable
+from contextlib import nullcontext
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+from brightdata import SyncBrightDataClient
+
+#: An empty date window comes back as an error row, not an empty list. Match on
+#: the message: a dead page carries the same error_code.
+EMPTY_WINDOW = "There are no public posts in the profile for the specified period"
+
+_HANDLE = re.compile(r"^[A-Za-z0-9._]{1,30}$")
+
+
+def clean_handle(handle: str) -> str:
+    """Accept nasa, @nasa, or a profile URL. Reject anything else.
+
+    A URL counts only when its host is instagram.com or a subdomain of it, so
+    https://evil.com/instagram.com/nasa is rejected rather than read as nasa.
+    """
+    cleaned = (handle or "").strip().lstrip("@")
+    if "/" in cleaned:
+        url = urlsplit(cleaned if "://" in cleaned else f"https://{cleaned}")
+        host = (url.hostname or "").lower()
+        if host != "instagram.com" and not host.endswith(".instagram.com"):
+            raise ValueError(f"{handle!r} is not an Instagram handle")
+        segments = [part for part in url.path.split("/") if part]
+        cleaned = segments[0] if segments else ""
+    if not _HANDLE.match(cleaned):
+        raise ValueError(f"{handle!r} is not an Instagram handle")
+    return cleaned
+
+
+def profile_url(handle: str) -> str:
+    return f"https://www.instagram.com/{clean_handle(handle)}/"
+
+
+def rows(result: Any) -> list[dict[str, Any]]:
+    """Flatten a ScrapeResult, or a list of them, into plain dicts."""
+    if isinstance(result, list):
+        return [row for item in result for row in rows(item)]
+    data = getattr(result, "data", result)
+    if isinstance(data, dict):
+        data = [data]
+    if not isinstance(data, list):
+        return []
+    return [row for row in data if isinstance(row, dict)]
+
+
+def envelope_error(result: Any) -> str | None:
+    """A failed or timed out request carries no rows to explain itself.
+
+    Without this check the run prints "0 posts", which reads like a creator with
+    nothing recent rather than a request that never came back.
+    """
+    if getattr(result, "success", True):
+        return None
+    return str(getattr(result, "error", None) or getattr(result, "status", "request failed"))
+
+
+def split(result: Any) -> tuple[list[dict[str, Any]], list[str], list[str]]:
+    """Sort rows into records, empty-window notes, and real errors."""
+    records: list[dict[str, Any]] = []
+    notes: list[str] = []
+    errors: list[str] = []
+    for row in rows(result):
+        error = row.get("error")
+        if not error:
+            records.append(row)
+        elif EMPTY_WINDOW in str(error):
+            notes.append("the account has no public posts in the period searched")
+        else:
+            errors.append(str(error))
+    return records, notes, errors
+
+
+@dataclass
+class Outcome:
+    """What happened to one handle."""
+
+    handle: str
+    posts: list[dict[str, Any]] = field(default_factory=list)
+    error: str | None = None
+    note: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None
+
+    def line(self) -> str:
+        """One line a reader can understand without having read the source."""
+        if not self.ok:
+            return f"failed  @{self.handle}: {self.error}"
+        tail = f", {self.note}" if self.note else ""
+        return f"got     @{self.handle}: {len(self.posts)} posts{tail}"
+
+
+def scrape_handle(client: Any, handle: str, limit: int = 5) -> Outcome:
+    """Fetch one handle. Never raises: a failure becomes an Outcome."""
+    try:
+        name = clean_handle(handle)
+    except ValueError as exc:
+        return Outcome(handle=str(handle), error=str(exc))
+
+    outcome = Outcome(handle=name)
+    try:
+        result = client.search.instagram.posts(profile_url(name), num_of_posts=limit)
+        failed = envelope_error(result)
+        if failed:
+            outcome.error = failed
+            return outcome
+        found, notes, errors = split(result)
+        outcome.note = "; ".join(dict.fromkeys(notes))
+        if errors:
+            outcome.error = "; ".join(errors)
+        else:
+            outcome.posts = found
+    except Exception as exc:  # one bad handle must not end the run
+        outcome.error = f"{type(exc).__name__}: {exc}"
+    return outcome
+
+
+def client_context(client: Any = None) -> Any:
+    """The client passed in, or one we open and own.
+
+    SyncBrightDataClient builds its event loop in __enter__, so it must be
+    entered. An unentered client fails with an AttributeError about
+    run_until_complete. Callers wanting progress hold this open and drive
+    scrape_handle themselves, as the CLI does.
+    """
+    # auto_create_zones defaults to True: the SDK tries to create a Web Unlocker
+    # zone on startup, which this scraper never uses. Creating a zone needs a
+    # payment method, so leaving it on breaks the first run for free accounts.
+    return nullcontext(client) if client is not None else SyncBrightDataClient(
+        auto_create_zones=False
+    )
+
+
+def scrape(handles: Iterable[str], limit: int = 5, client: Any = None) -> list[Outcome]:
+    """Run every handle and return one Outcome each, in order."""
+    with client_context(client) as opened:
+        return [scrape_handle(opened, handle, limit) for handle in handles]
+
+
+def write(outcomes: list[Outcome], path: str | Path) -> Path:
+    """Write one JSON file: when it ran, and the posts found per handle."""
+    document = {
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "handles": [{"handle": o.handle, "posts": o.posts} for o in outcomes],
+    }
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
+    return target