brightdata-instagram-scraper 0.1.0__tar.gz

brightdata_instagram_scraper-0.1.0/.env.example

@@ -0,0 +1,3 @@
+# Copy to .env in the project root. The SDK finds it when the virtualenv is inside the project.
+# Token: https://brightdata.com/cp/setting/users
+BRIGHTDATA_API_TOKEN=

brightdata_instagram_scraper-0.1.0/.github/scripts/readme_blocks.py

@@ -0,0 +1,138 @@
+"""The README's code blocks, as the live check runs them.
+
+    python readme_blocks.py list           # JSON matrix for the block jobs (ONLY filters)
+    python readme_blocks.py run N          # run block N with the real token, one retry
+    python readme_blocks.py cli-syntax     # every README CLI line with a dummy key
+
+One parser for all three, so the list and the runner can never disagree on
+what block N is.
+"""
+
+import json
+import os
+import pathlib
+import re
+import subprocess
+import sys
+import time
+
+README = pathlib.Path(__file__).resolve().parents[2] / "README.md"
+SKIP = ("pip install", "export ", "npm i", "npm install",
+        "npx -p @brightdata/cli bdata login", "bdata login")
+CLI = os.environ.get("BDATA_CLI", "")  # the pinned CLI version; empty means whatever is installed
+
+
+def blocks():
+    readme = README.read_text(encoding="utf-8")
+    # never execute anything inside the generated field table: its text comes from
+    # the API, and a fence in a description must not become a command
+    readme = re.sub(r"<!-- fields:start -->.*?<!-- fields:end -->", "", readme, flags=re.S)
+    found, heading, seen = [], "README", {}
+    for m in re.finditer(r"^#{2,3} ([^\n]+)$|```(python|bash)\n(.*?)```", readme, re.M | re.S):
+        if m.group(1):
+            heading = m.group(1).strip()  # a block is named after its section, not its first line
+            continue
+        lang, code = m.group(2), m.group(3)
+        lines = [line for line in code.splitlines()
+                 if line.strip() and not line.strip().startswith("#")]
+        if lang == "bash":
+            lines = [line for line in lines if not line.startswith(SKIP)]
+            if not lines:
+                continue
+            code = "\n".join(lines)
+        seen[heading] = seen.get(heading, 0) + 1
+        title = heading if seen[heading] == 1 else f"{heading} ({seen[heading]})"
+        found.append({"lang": lang, "title": title[:50], "code": code})
+    return found
+
+
+def cli_lines(code, key):
+    """The CLI cannot open a browser here, so the key goes in by flag, and an
+    unpinned npx is held to the version the job installed."""
+    out = []
+    for line in code.splitlines():
+        if CLI:
+            line = line.replace("npx -p @brightdata/cli ", f"npx -p @brightdata/cli@{CLI} ")
+        if "bdata pipelines" in line:
+            line += f" -k {key}"
+        out.append(line)
+    return "\n".join(out)
+
+
+def list_blocks():
+    wanted = {int(n) for n in os.environ.get("ONLY", "").split(",") if n.strip()}
+    out = [{"n": i + 1, "lang": b["lang"], "title": b["title"]}
+           for i, b in enumerate(blocks()) if not wanted or i + 1 in wanted]
+    print("blocks=" + json.dumps(out))
+
+
+def run_block(n):
+    b = blocks()[n - 1]
+    if b["lang"] == "bash":
+        # only the shell ever sees the key's value
+        argv = ["bash", "-e", "-c", cli_lines(b["code"], '"$BRIGHTDATA_API_TOKEN"')]
+    else:
+        argv = [sys.executable, "-c", b["code"]]
+    secret = os.environ.get("BRIGHTDATA_API_TOKEN", "")
+    for _attempt in (1, 2):
+        started = time.time()
+        try:
+            run = subprocess.run(argv, capture_output=True, text=True, timeout=480)
+        except subprocess.TimeoutExpired:
+            run = subprocess.CompletedProcess(
+                argv, 1, "", "block timeout: no result within 8 minutes")
+        secs = round(time.time() - started)
+        out, err = run.stdout.strip(), run.stderr.strip()
+        if secret:  # summaries are not secret-masked the way logs are
+            out, err = out.replace(secret, "***"), err.replace(secret, "***")
+        ok = run.returncode == 0 and bool(out if b["lang"] == "python" else out or err)
+        if ok or ((out or err) and "timeout" not in (out + err).lower()):
+            break
+        time.sleep(30)  # the API timed out or answered with nothing at all; one retry
+    if ok:
+        shown = (out.splitlines() or [""])[:1]
+    else:
+        # the last few lines: a CLI error often puts the cause above its hint
+        shown = (err.splitlines() or out.splitlines() or ["no output"])[-6:]
+    body = "\n".join("    " + line[:160] for line in shown)
+    state = "ok" if ok else "FAILED"
+    print(f"\n`{b['title']}`: {state} in {secs}s (exit {run.returncode})\n\n{body}")
+    sys.exit(0 if ok else 1)
+
+
+def cli_syntax():
+    """Run every README CLI line with a key the API rejects. A line the CLI
+    still understands reaches the API and gets a 401; a line it no longer
+    understands fails before that. Free, and needs no secret."""
+    failed = 0
+    print("| block | CLI line | result |\n| --- | --- | --- |")
+    for i, b in enumerate(blocks(), 1):
+        if b["lang"] != "bash":
+            continue
+        for line in b["code"].splitlines():
+            if "bdata pipelines" not in line:
+                continue
+            run = subprocess.run(["bash", "-c", cli_lines(line, "invalid-key-for-syntax-check")],
+                                 capture_output=True, text=True, timeout=120)
+            text = run.stdout + run.stderr
+            ok = "401" in text or "Invalid credentials" in text
+            last = (run.stderr.strip().splitlines() or run.stdout.strip().splitlines()
+                    or ["no output"])
+            why = "reached the API" if ok else " / ".join(x.strip() for x in last[-3:])[:200]
+            print(f"| {i} | `{line[:90]}` | {'ok' if ok else 'FAILED'}: {why.replace('|', '/')} |")
+            if not ok:
+                failed = 1
+                print(f"::error::README block {i}: the CLI rejects `{line}`", file=sys.stderr)
+    sys.exit(failed)
+
+
+if __name__ == "__main__":
+    mode = sys.argv[1] if len(sys.argv) > 1 else ""
+    if mode == "list":
+        list_blocks()
+    elif mode == "run":
+        run_block(int(sys.argv[2]))
+    elif mode == "cli-syntax":
+        cli_syntax()
+    else:
+        sys.exit(__doc__)

brightdata_instagram_scraper-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,130 @@
+# Runs by itself on every push and pull request.
+# Never calls the Instagram API, so it needs no token and costs nothing.
+name: Tests (automatic, no API calls, free)
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:  # a Run workflow button, to re-run the tests without a commit
+
+permissions:
+  contents: read
+
+concurrency:  # a newer push to the same branch or PR replaces the run still going
+  group: ci-${{ github.event_name }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  tests:
+    name: Run the tests and the code style check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Install the package and its test tools
+        run: pip install -e ".[dev]"
+      - name: Check code style with ruff
+        run: ruff check .
+      - name: Run the tests
+        run: pytest
+      - name: README headings are well formed
+        # A section rewrite once produced "## The data## The data" and shipped;
+        # a heading with a second run of hashes mid-line is never intended.
+        run: |
+          if grep -nE '^#+ .*#{2,} ' README.md; then
+            echo "::error::malformed heading in README.md"; exit 1
+          fi
+
+  # These install steps shipped broken once, because they were only ever run
+  # from a working copy that already had the package. This job follows the
+  # README on an empty machine and stops where the tool asks for a token, which
+  # proves the clone, the install and the command without spending money.
+  coldstart:
+    name: Follow the README from scratch on an empty machine
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7
+        with:
+          python-version: "3.12"
+      - name: Copy the install steps out of the README and run them
+        run: |
+          set -o pipefail
+          python - <<'PY' > "$RUNNER_TEMP/quickstart.sh"
+          import os
+          import pathlib
+          import re
+          import sys
+
+          readme = pathlib.Path("README.md").read_text(encoding="utf-8")
+
+          def section(title):
+              return readme.split(f"## {title}", 1)[1].split("\n## ", 1)[0]
+
+          def block(text, lang):
+              return re.search(r"```" + lang + r"\n(.*?)```", text, re.S).group(1)
+
+          quick = section("How to scrape Instagram data with Python")
+          install, snippet = block(quick, "bash"), block(quick, "python")
+          command = block(section("Bulk Instagram scraper CLI"), "bash")
+          for required, where in (("pip install brightdata-sdk", install),
+                                  ("SyncBrightDataClient", snippet),
+                                  ("instagram-scraper", command)):
+              if required not in where:
+                  sys.exit(f"the README no longer contains {required!r} where the cold start expects it")
+
+          steps = ["# --- Quickstart: the SDK path ---"]
+          steps += [l for l in install.splitlines() if l.startswith("pip install")]
+          pathlib.Path(os.environ["RUNNER_TEMP"], "quickstart_snippet.py").write_text(snippet, encoding="utf-8")
+          steps += [
+              "set +e",
+              "python quickstart_snippet.py > out.txt 2> err.txt",
+              "code=$?",
+              "set -e",
+              'test "$code" != "0" || { echo "the snippet ran without a token?"; cat out.txt; exit 1; }',
+              'grep -qi token err.txt || { echo "no token message"; cat err.txt; exit 1; }',
+              'echo "Quickstart: installs, and stops at the token, as documented."',
+              "# --- Or run it as a command: the CLI path ---",
+          ]
+          for line in command.splitlines():
+              if line.startswith("instagram-scraper"):
+                  continue  # run below, so the exit code can be checked
+              if line.startswith("pip install"):
+                  # The repository is public, so this installs the exact line a
+                  # reader pastes. On a private fork the URL is unreachable, and
+                  # the check falls back to the checkout on its own.
+                  url = line.split("git+", 1)[1].strip() if "git+" in line else ""
+                  line = "\n".join([
+                      f'repo="{url}"',
+                      'code=$(curl -s -o /dev/null -w "%{http_code}" "$repo" || echo 000)',
+                      'if [ "$code" = "200" ]; then',
+                      f'  echo "$repo is public: installing the exact README line"',
+                      f'  {line}',
+                      "else",
+                      '  echo "NOTE: $repo returns HTTP $code, so it is not public yet."',
+                      '  echo "Installing from this checkout instead."',
+                      '  pip install "$GITHUB_WORKSPACE"',
+                      "fi",
+                  ])
+              steps.append(line)
+          steps += [
+              "set +e",
+              "instagram-scraper nasa --limit 1 > out.txt 2> err.txt",
+              "code=$?",
+              "set -e",
+              'test "$code" = "2" || { echo "expected exit 2, got $code"; cat err.txt; exit 1; }',
+              'grep -qi token err.txt || { echo "no token message"; cat err.txt; exit 1; }',
+              'echo "Success: a new user can follow both README paths from scratch."',
+          ]
+          print("\n".join(steps))
+          PY
+          echo "--- these commands came out of README.md ---"
+          cat "$RUNNER_TEMP/quickstart.sh"
+          echo "--- running them on this empty machine ---"
+          cd "$RUNNER_TEMP" && bash -e "$RUNNER_TEMP/quickstart.sh"

brightdata_instagram_scraper-0.1.0/.github/workflows/live.yml

@@ -0,0 +1,395 @@
+# The only workflow that calls the real API. Needs the BRIGHTDATA_API_TOKEN
+# secret and spends about one credit per post.
+#
+# Four ways it runs:
+#   on every push to main: one post from nasa and the README's links, one
+#     credit and about three minutes, so a broken commit shows up at once.
+#     A newer push cancels a run still going for an older commit.
+#   by hand, from the Actions tab, to scrape whatever accounts you choose
+#   every day at 06:00 UTC except Monday: one post from nasa, the async
+#     path, and the field table, about two credits
+#   every Monday at 06:00 UTC: the same, plus every code block in the README,
+#     about 35 credits and 30 minutes
+#
+# Every run also checks, for free and with no secret, that the newest Bright
+# Data CLI still accepts every CLI line in the README. Readers run `npx -p
+# @brightdata/cli`, which is always the newest release, while the jobs that hold
+# the secret run the version pinned in BDATA_CLI below. CLI 0.4.0 removed the
+# README's commands and only the Monday run noticed; this check sees it the
+# same day. When it warns about a new release, bump BDATA_CLI.
+#
+# A slow day at the API shows up as a red run. Rerun it before reading more
+# into it.
+#
+# The daily and Monday runs end by rewriting the "last verified" badge line at
+# the top of README.md with today's date, and committing it if it changed. Push
+# runs never do this, so your own push is never followed by a bot commit. Only
+# the main repository commits; a copy of the repository just runs the checks.
+name: Live check
+
+run-name: "${{ github.event.schedule == '0 6 * * 1' && 'Weekly check: does every README block still work?' || github.event_name == 'schedule' && 'Daily check: is anything broken?' || github.event_name == 'push' && format('Push check: {0}', github.event.head_commit.message) || format('Scrape {0}, {1} posts each', inputs.handles, inputs.limit) }}"
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * 0,2-6"  # daily smoke, every day except Monday
+    - cron: "0 6 * * 1"    # Monday: the whole README
+  workflow_dispatch:
+    inputs:
+      handles:
+        description: Instagram handles, separated by spaces. No @ needed.
+        default: nasa natgeo
+      limit:
+        description: How many recent posts to fetch for each handle
+        default: "2"
+      validate:
+        description: Also run every README block, as the Monday run does
+        type: boolean
+        default: false
+      only:
+        description: Block numbers to run, comma separated, for a cheap check. Empty means all.
+        default: ""
+
+permissions:
+  contents: write  # the daily check commits the regenerated field table
+
+env:
+  BDATA_CLI: "0.4.0"  # pinned for the jobs that hold the API secret; bump after cli-syntax passes
+
+concurrency:
+  group: live-${{ github.event_name }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'push' }}  # only the newest commit matters
+
+jobs:
+  scrape:
+    name: Fetch the posts and attach them to this run
+    runs-on: ubuntu-latest
+    timeout-minutes: 20  # fetch, async path, table; the README blocks have their own jobs
+    env:
+      BRIGHTDATA_API_TOKEN: ${{ secrets.BRIGHTDATA_API_TOKEN }}
+      # On the daily schedule there are no inputs, so fall back to one cheap post.
+      HANDLES: ${{ inputs.handles || 'nasa' }}
+      LIMIT: ${{ inputs.limit || '1' }}
+      # the async path and the field table run on every scheduled run and on request
+      CHECK: ${{ github.event_name == 'schedule' || inputs.validate }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Install the package
+        run: pip install -e .
+
+      - name: Do the README's links still resolve?
+        run: |
+          public=$(curl -s -o /dev/null -w '%{http_code}' https://github.com/brightdata/instagram-scraper)
+          failed=0
+          for url in $(grep -ohE 'https?://[^ )>"`]+' README.md AGENTS.md | sed 's/[.,]$//' | sort -u); do
+            case "$url" in
+              *instagram.com/*) continue ;;  # rate-limits runners; the weekly README run fetches these posts anyway
+              *zendesk.com/*) continue ;;    # answers 403 to anything that is not a browser
+              *mcp.brightdata.com/*) continue ;;  # carries a placeholder token; nothing to check without a real one
+              *github.com/brightdata/instagram-scraper*) [ "$public" = "200" ] || continue ;;  # unreachable on a private fork
+            esac
+            code=$(curl -s -o /dev/null -L --retry 3 --max-time 30 -A "Mozilla/5.0" -w '%{http_code}' "$url" || echo 000)
+            case "$code" in
+              200) echo "200 $url" ;;
+              # A 5xx after curl's retries is the server having a bad minute,
+              # not a dead link: GitHub answered 502 for an issue page once.
+              5??) echo "::warning::$code $url (server error, link not judged)" ;;
+              *) echo "::error::$code $url"; failed=1 ;;
+            esac
+          done
+          [ "$failed" = 0 ] || exit 1
+      - name: Fetch the posts from Instagram
+        run: |
+          test -n "$BRIGHTDATA_API_TOKEN" || {
+            echo "No API token. Add BRIGHTDATA_API_TOKEN under" >&2
+            echo "Settings, Secrets and variables, Actions, then start this again." >&2
+            exit 1
+          }
+          # One retry, only on an API timeout. A slow day is not a broken build.
+          set +e
+          python -m instagram_scraper $HANDLES --limit "$LIMIT" 2>&1 | tee run.log
+          code=${PIPESTATUS[0]}
+          if [ "$code" != "0" ] && grep -q "timeout" run.log; then
+            echo "::warning::The API timed out. Waiting 30s and trying once more."
+            sleep 30
+            python -m instagram_scraper $HANDLES --limit "$LIMIT" 2>&1 | tee run.log
+            code=${PIPESTATUS[0]}
+          fi
+          exit "$code"
+
+      - name: Show what was found
+        if: always()
+        run: |
+          set -o pipefail
+          test -f instagram.json || exit 0
+          python - <<'PY' | tee -a "$GITHUB_STEP_SUMMARY"
+          import json
+
+          doc = json.load(open("instagram.json"))
+          print(f"Run at {doc['generated_at']}\n")
+          print("| handle | posts | fields | newest post |")
+          print("| --- | --- | --- | --- |")
+          for entry in doc["handles"]:
+              posts = entry["posts"]
+              newest = max(posts, key=lambda p: p.get("date_posted") or "", default=None)
+              print(
+                  f"| {entry['handle']} | {len(posts)} | {len(posts[0]) if posts else 0} "
+                  f"| {newest.get('url') if newest else '-'} |"
+              )
+          for entry in doc["handles"]:
+              if not entry["posts"]:
+                  continue
+              print(f"\n### {entry['handle']}\n")
+              print("| date_posted | url | likes | comments |")
+              print("| --- | --- | --- | --- |")
+              for post in entry["posts"]:
+                  print(
+                      f"| {post.get('date_posted')} | {post.get('url')} "
+                      f"| {post.get('likes')} | {post.get('num_comments')} |"
+                  )
+          first = next((p for e in doc["handles"] for p in e["posts"]), None)
+          if first:
+              print("\n<details><summary>First record in full</summary>\n")
+              print("```json")
+              print(json.dumps(first, indent=2, ensure_ascii=False))
+              print("```\n")
+              print("</details>")
+          PY
+
+      # The two daily checks. Discovery is already covered by the step above.
+      - name: Does the async trigger, status, fetch path still work?
+        if: env.CHECK == 'true'
+        run: |
+          python - <<'PY' | tee -a "$GITHUB_STEP_SUMMARY"
+          import time
+
+          from brightdata import SyncBrightDataClient
+
+          url = "https://www.instagram.com/p/Db_SePSltfz/"
+          with SyncBrightDataClient(auto_create_zones=False) as c:
+              job = c.scrape.instagram.posts_trigger(url)
+              sid = job.snapshot_id
+              for _ in range(72):  # up to 6 minutes
+                  status = c.scrape.instagram.posts_status(sid)
+                  if status in ("ready", "failed", "canceled"):
+                      break
+                  time.sleep(5)
+              assert status == "ready", f"snapshot {sid} ended as {status}"
+              rows = c.scrape.instagram.posts_fetch(sid)
+              rows = rows if isinstance(rows, list) else [rows]
+              assert rows and rows[0].get("url"), "fetch returned no record"
+          print(f"\nAsync path ok: trigger, status, fetch returned {len(rows)} record(s).")
+          PY
+
+      - name: Regenerate the README field table from the live schema
+        if: always() && env.CHECK == 'true' && github.repository == 'brightdata/instagram-scraper' && github.ref == 'refs/heads/main'
+        run: |
+          python - <<'PY' | tee -a "$GITHUB_STEP_SUMMARY"
+          import json
+          import pathlib
+          import re
+
+          from brightdata import SyncBrightDataClient
+
+          readme = pathlib.Path("README.md")
+          text = readme.read_text(encoding="utf-8")
+          start, end = "<!-- fields:start -->", "<!-- fields:end -->"
+          assert start in text and end in text, "README field-table markers are missing"
+
+          with SyncBrightDataClient(auto_create_zones=False) as c:
+              fields = c.datasets.instagram_posts.get_metadata().fields
+          sample = json.load(open("examples/sample_output.json"))["handles"][0]["posts"][0]
+
+          rows = ["| field | type | description |", "| --- | --- | --- |"]
+          for name, spec in fields.items():
+              desc = (spec.description or "").replace(" — ", ": ").replace("—", ":")
+              desc = " ".join(desc.split()).replace("`", "'").replace("|", "/")  # no fences, no table breaks
+              rows.append(f"| `{name}` | {spec.type} | {desc} |")
+          block = "\n".join([
+              start,
+              "<details>",
+              f"<summary>All {len(fields)} 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",
+              f"post carries the fields that apply to it; the sample file has {len(sample)}",
+              f"of these {len(fields)}.",
+              "",
+              *rows,
+              "",
+              "</details>",
+              end,
+          ])
+          new = re.sub(re.escape(start) + r".*?" + re.escape(end), lambda _: block, text, flags=re.S)
+          readme.write_text(new, encoding="utf-8")
+          state = "updated" if new != text else "already current"
+          print(f"\nSchema: {len(fields)} fields. README table {state}.")
+          PY
+          if git diff --quiet README.md; then
+            echo "Nothing to commit."
+            exit 0
+          fi
+          # Never commit a README the tests would reject.
+          pip install -q -e ".[dev]" && pytest -q
+          git config user.name "anil-bd"
+          git config user.email "210667061+anil-bd@users.noreply.github.com"
+          git add README.md
+          git commit -m "Regenerate the field table from the live schema (automated daily check)"
+          git pull --rebase origin main
+          git push
+          echo "Committed the regenerated table."
+
+      - name: Attach instagram.json so you can download it
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
+        if: always()
+        with:
+          name: instagram-json
+          path: instagram.json
+          if-no-files-found: warn
+
+  # Every code block in the README, each in its own job, all at once. Mondays,
+  # and on request. Wall clock is the slowest block, about five minutes,
+  # instead of the sum of all fourteen.
+  plan:
+    name: List the README blocks
+    if: github.event.schedule == '0 6 * * 1' || inputs.validate == true
+    runs-on: ubuntu-latest
+    outputs:
+      blocks: ${{ steps.list.outputs.blocks }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+      - id: list
+        env:
+          ONLY: ${{ inputs.only }}
+        run: python .github/scripts/readme_blocks.py list >> "$GITHUB_OUTPUT"
+
+  block:
+    name: "${{ matrix.n }}. ${{ matrix.title }}"
+    needs: plan
+    runs-on: ubuntu-latest
+    timeout-minutes: 10  # the SDK gives up at 3 minutes, reels at 7; past this is stuck
+    strategy:
+      fail-fast: false
+      matrix:
+        include: ${{ fromJson(needs.plan.outputs.blocks) }}
+    env:
+      BRIGHTDATA_API_TOKEN: ${{ secrets.BRIGHTDATA_API_TOKEN }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Install the package and, for CLI blocks, the Bright Data CLI
+        env:
+          LANG_: ${{ matrix.lang }}
+        run: |
+          pip install -e .
+          if [ "$LANG_" = "bash" ]; then npm i -g "@brightdata/cli@$BDATA_CLI"; fi
+      - name: Run block ${{ matrix.n }} exactly as the README shows it
+        env:
+          N: ${{ matrix.n }}
+        run: |
+          set -o pipefail  # without this, tee's exit code hides a failing block
+          python .github/scripts/readme_blocks.py run "$N" | tee -a "$GITHUB_STEP_SUMMARY"
+
+  cli-syntax:
+    name: Does the newest CLI still accept the README's commands?
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    # no secret here on purpose: this job runs whatever npm calls latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+      - name: Install the newest CLI, as a reader's npx would
+        run: |
+          npm i -g @brightdata/cli@latest
+          latest=$(bdata --version)
+          echo "Newest CLI: $latest. Pinned for the live jobs: $BDATA_CLI."
+          if [ "$latest" != "$BDATA_CLI" ]; then
+            echo "::warning::@brightdata/cli $latest is out; the live jobs still pin $BDATA_CLI. Bump BDATA_CLI in live.yml once this job passes."
+          fi
+      - name: Run each README CLI line with a key the API rejects
+        env:
+          BDATA_CLI: ""  # use the newest, not the pin
+        run: |
+          set -o pipefail
+          python3 .github/scripts/readme_blocks.py cli-syntax | tee -a "$GITHUB_STEP_SUMMARY"
+
+  badge:
+    name: Put today's date on the README's "last verified" badge
+    needs: [scrape, plan, block, cli-syntax]
+    # scheduled and manual runs on main only, and only in the main repository: a
+    # push is never followed by a bot commit, a copy never diverges from the
+    # original, and a manual run on a branch never tries to push main
+    if: always() && !cancelled() && github.event_name != 'push' && github.repository == 'brightdata/instagram-scraper' && github.ref == 'refs/heads/main'
+    permissions:
+      contents: write  # commits the badge line
+      actions: read    # counts this run's job results
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+      - name: Rewrite one badge line, commit only if it changed
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # Two states: red only when every check in this run failed. One passing
+          # check keeps the badge green; the run itself still shows which failed.
+          read -r passed failed < <(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID/attempts/$GITHUB_RUN_ATTEMPT/jobs?per_page=100" \
+            --jq '[.jobs[] | select((.name | startswith("Put today") or startswith("Open or update") or . == "List the README blocks") | not)] as $j | "\([$j[] | select(.conclusion == "success")] | length) \([$j[] | select(.conclusion == "failure")] | length)"') || true
+          echo "checks passed: ${passed:-0}, failed: ${failed:-0}"
+          if [ "${passed:-0}" -gt 0 ]; then
+            label="last verified"; color="brightgreen"
+          else
+            label="last check failed"; color="red"
+          fi
+          today=$(date -u +'%-d %b %Y')
+          line="[![${label}](https://img.shields.io/badge/${label// /%20}-${today// /%20}-${color})](https://github.com/brightdata/instagram-scraper/actions/workflows/live.yml) <!-- verified: rewritten by the daily run -->"
+          python3 - "$line" <<'PY'
+          import pathlib, re, sys
+          p = pathlib.Path("README.md"); t = p.read_text(encoding="utf-8")
+          new, n = re.subn(r"^\[!\[last [^\]]*\]\(https://img\.shields\.io/badge/[^)]*\)\]\([^)]*\) <!-- verified:[^\n]*$", sys.argv[1], t, count=1, flags=re.M)
+          if n != 1:
+              sys.exit("the badge line is missing from README.md")
+          p.write_text(new, encoding="utf-8")
+          PY
+          if git diff --quiet; then echo "badge already shows $today"; exit 0; fi
+          git config user.name "anil-bd"
+          git config user.email "210667061+anil-bd@users.noreply.github.com"
+          git commit -qam "${label^} $today (automated daily check)"
+          git pull -q --rebase origin main
+          git push -q origin main
+          echo "badge now shows: $label, $today"
+
+  # A red scheduled run used to show only as a red badge. Open one issue and keep
+  # adding to it, so a failure reaches the people watching the repository.
+  alert:
+    name: Open or update the live-check issue
+    needs: [scrape, block, cli-syntax]
+    if: failure() && github.event_name == 'schedule' && github.repository == 'brightdata/instagram-scraper'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      issues: write
+    steps:
+      - env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RUN: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          RESULTS: "scrape ${{ needs.scrape.result }}, README blocks ${{ needs.block.result }}, CLI syntax ${{ needs.cli-syntax.result }}"
+        run: |
+          title="Live check is failing"
+          body="$(date -u +'%-d %b %Y'): $RESULTS. $RUN"
+          n=$(gh issue list --state open --search "\"$title\" in:title" --json number --jq '.[0].number')
+          if [ -n "$n" ]; then
+            gh issue comment "$n" --body "$body"
+          else
+            gh issue create --title "$title" --body "$body"
+          fi