From f5aad487ac549e047246cd8fa72396af4f3fb3b4 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 9 Jul 2026 16:07:42 +0530
Subject: [PATCH] docs(web): document Instagram native connector

---
 .../content/docs/connectors/index.mdx         |  2 +-
 .../content/docs/connectors/native/index.mdx  |  7 +-
 .../docs/connectors/native/instagram.mdx      | 77 +++++++++++++++++++
 .../content/docs/connectors/native/meta.json  |  2 +-
 4 files changed, 85 insertions(+), 3 deletions(-)
 create mode 100644 surfsense_web/content/docs/connectors/native/instagram.mdx

diff --git a/surfsense_web/content/docs/connectors/index.mdx b/surfsense_web/content/docs/connectors/index.mdx
index 1ee9209e6..747d278e2 100644
--- a/surfsense_web/content/docs/connectors/index.mdx
+++ b/surfsense_web/content/docs/connectors/index.mdx
@@ -12,7 +12,7 @@ Connectors bring data into SurfSense — either as searchable knowledge or as li
   <Card
     icon={<Zap />}
     title="Native Connectors"
-    description="SurfSense's built-in scraper APIs: Reddit, YouTube, Google Maps, Google Search, and Web Crawl — usable in chat, the API Playground, or via REST"
+    description="SurfSense's built-in scraper APIs: Reddit, YouTube, Instagram, Google Maps, Google Search, and Web Crawl — usable in chat, the API Playground, or via REST"
     href="/docs/connectors/native"
   />
   <Card
diff --git a/surfsense_web/content/docs/connectors/native/index.mdx b/surfsense_web/content/docs/connectors/native/index.mdx
index 5c5d24444..d9a9085a5 100644
--- a/surfsense_web/content/docs/connectors/native/index.mdx
+++ b/surfsense_web/content/docs/connectors/native/index.mdx
@@ -1,6 +1,6 @@
 ---
 title: Native Connectors
-description: SurfSense's built-in scraper APIs for Reddit, YouTube, Google Maps, Google Search, and the web
+description: SurfSense's built-in scraper APIs for Reddit, YouTube, Instagram, Google Maps, Google Search, and the web
 ---
 
 import { Card, Cards } from 'fumadocs-ui/components/card';
@@ -18,6 +18,11 @@ Native connectors are SurfSense's own scraper APIs — built into the platform,
     description="Videos, channels, playlists, subtitles, and comments"
     href="/docs/connectors/native/youtube"
   />
+  <Card
+    title="Instagram"
+    description="Posts, reels, comments, and profile, hashtag, and place details"
+    href="/docs/connectors/native/instagram"
+  />
   <Card
     title="Google Maps"
     description="Places with details, ratings, photos, and reviews"
diff --git a/surfsense_web/content/docs/connectors/native/instagram.mdx b/surfsense_web/content/docs/connectors/native/instagram.mdx
new file mode 100644
index 000000000..f9758662b
--- /dev/null
+++ b/surfsense_web/content/docs/connectors/native/instagram.mdx
@@ -0,0 +1,77 @@
+---
+title: Instagram
+description: Scrape public Instagram posts, reels, comments, and profile/hashtag/place details
+---
+
+The Instagram scraper has three verbs: **scrape** for posts and reels, **comments** for a post's comment threads, and **details** for profile, hashtag, and place metadata. It reads only public, logged-out data — no account, login, or Graph API app required.
+
+## Scrape posts and reels
+
+```bash
+POST /api/v1/workspaces/{workspace_id}/scrapers/instagram/scrape
+```
+
+Give it Instagram URLs (profile, post `/p/`, reel `/reel/`, hashtag `/explore/tags/`, or place `/explore/locations/`) or search queries. Returns structured media items — caption, hashtags, mentions, like and comment counts, media URLs, and owner.
+
+Provide exactly one source: `urls` **or** `search_queries` (never both).
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `urls` | — | Profile, post, reel, hashtag, or place URLs or bare profile IDs (max 20 sources per call) |
+| `search_queries` | — | Discovery keywords (hashtags as plaintext, no `#`); each returns up to `max_per_target` items |
+| `search_type` | `hashtag` | What to discover from `search_queries`: `hashtag`, `profile`, `place`, or `user` |
+| `result_type` | `posts` | Which feed to return: `posts`, `reels`, or `mentions` (`mentions` needs profile URLs) |
+| `newer_than` | — | Only return posts newer than this: `YYYY-MM-DD`, ISO timestamp, or relative (`2 months`), UTC |
+| `skip_pinned_posts` | `false` | Exclude pinned posts in posts mode |
+| `max_per_target` | `10` | Max results per URL or per discovered target |
+| `max_items` | `10` | Max total items across all sources (1–100) |
+
+```bash
+curl -X POST "$BASE_URL/api/v1/workspaces/1/scrapers/instagram/scrape" \
+  -H "Authorization: Bearer $SURFSENSE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "urls": ["https://www.instagram.com/natgeo/"],
+    "result_type": "reels",
+    "max_items": 20
+  }'
+```
+
+Billing is per returned item.
+
+## Fetch comments
+
+```bash
+POST /api/v1/workspaces/{workspace_id}/scrapers/instagram/comments
+```
+
+Give it post or reel URLs; returns comment items with author, text, like and reply counts, and optionally nested replies — useful for gauging sentiment on a specific post.
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `urls` | required | 1–20 post or reel URLs |
+| `max_comments_per_post` | `10` | Max comments per post (Instagram caps at 50) |
+| `include_replies` | `false` | Include nested replies |
+| `newest_first` | `false` | Return newest comments first |
+| `max_items` | `20` | Max total comments across all posts (max 100) |
+
+Billing is per returned comment or reply.
+
+## Fetch details
+
+```bash
+POST /api/v1/workspaces/{workspace_id}/scrapers/instagram/details
+```
+
+Give it profile, hashtag, or place URLs (or search queries) and get entity metadata back: a profile's follower/post counts and bio, a hashtag's post volume and top posts, or a place's coordinates and post count. Each item carries a `detailKind` field marking whether it is a `profile`, `hashtag`, or `place`.
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `urls` | — | Profile, hashtag, or place URLs or bare profile IDs (max 20) |
+| `search_queries` | — | Terms to discover profiles/hashtags/places for (provide these OR urls) |
+| `search_type` | `hashtag` | What to discover from `search_queries`: `hashtag`, `profile`, or `place` |
+| `max_items` | `10` | Max detail items to return |
+
+Billing is per returned item.
+
+For the full input and output JSON schemas and generated code snippets in your language, open **API Playground → Instagram** in your workspace.
diff --git a/surfsense_web/content/docs/connectors/native/meta.json b/surfsense_web/content/docs/connectors/native/meta.json
index 53f991fbc..b6a20a94f 100644
--- a/surfsense_web/content/docs/connectors/native/meta.json
+++ b/surfsense_web/content/docs/connectors/native/meta.json
@@ -1,5 +1,5 @@
 {
 	"title": "Native Connectors",
-	"pages": ["reddit", "youtube", "google-maps", "google-search", "web-crawl"],
+	"pages": ["reddit", "youtube", "instagram", "google-maps", "google-search", "web-crawl"],
 	"defaultOpen": false
 }