# Threads Scraper — Profiles, Posts, Search & Replies (`foxlabs/threads-scraper`) Actor

Scrape Meta Threads profiles, user posts, keyword search results and post replies with no login or API key. Extracts followers, verified badges, unwrapped bio links and emails, likes, replies, reposts, quotes, media URLs and engagement metrics.

- **URL**: https://apify.com/foxlabs/threads-scraper.md
- **Developed by:** [Berkan Kaplan](https://apify.com/foxlabs) (community)
- **Categories:** Social media, Lead generation
- **Features:** Limited permissions
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 threads posts

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

<p align="center">
  <img src="https://img.shields.io/badge/Pay--Per--Event-Transparent_Pricing-00C853?style=for-the-badge" alt="Pay-Per-Event" />&nbsp;
  <img src="https://img.shields.io/badge/No_Login_Required-Zero_Keys_%26_Cookies-2962FF?style=for-the-badge" alt="No Login Required" />&nbsp;
  <img src="https://img.shields.io/badge/AI_Agent_Ready-MCP_%26_x402-7C4DFF?style=for-the-badge" alt="MCP & x402 Ready" />&nbsp;
  <img src="https://img.shields.io/badge/Dual_Runtime-Batch_%2B_Standby_API-FF6D00?style=for-the-badge" alt="Batch + Standby API" />
</p>

## Threads Scraper — Profiles, Posts, Search & Replies 🚀

**foXLabs Social & Creator Series:** [Instagram Profile](https://apify.com/foxlabs/instagram-profile-scraper) · [Instagram Posts](https://apify.com/foxlabs/instagram-post-scraper) · [Facebook Page Posts](https://apify.com/foxlabs/facebook-page-posts-scraper) · [Telegram Channel Scraper](https://apify.com/foxlabs/telegram-channel-scraper) · [X (Twitter) Profile](https://apify.com/foxlabs/x-profile-scraper) · [Bluesky Creator Intelligence](https://apify.com/foxlabs/bluesky-creator-intelligence) · [YouTube Channel Email Scraper](https://apify.com/foxlabs/youtube-channel-email-scraper)

🎉 Turn public Meta Threads accounts, keyword conversations and post reply threads into clean, structured intelligence — with **no login, no cookies, no Meta API key and no headless browser**. Extract enriched creator profiles (followers, verification badges, unwrapped biography links, public contact emails, cross-platform social handles and measured engagement rates), multi-page user timelines, Top/Recent keyword search feeds and direct post replies in one unified schema.

Built for influencer & creator marketing teams, social-listening pipelines, brand & PR monitors, equity/trend researchers and autonomous AI agents.

### 🔍 What is the Threads Scraper — and when should you use it?

Meta's official Threads API only allows authenticated developers to read and publish on **their own** Threads account — it provides no public third-party profile lookup, no unauthenticated topic search across Threads, and no way to audit audience replies on public announcements without OAuth review. At the same time, external URLs in Threads biographies are wrapped behind `l.threads.com/?u=…` tracking redirects, and profile pages display only a handful of recent posts before paginating.

This Actor handles discovery, enrichment and pagination end-to-end in a single run:

- **Public creator profiles & contact leads** (`usernames`) — resolves `@handle` or `threads.com/@handle` URLs, captures exact follower counts, verification status, HD avatars, unwrapped external `bioLinks`, extracted `bioEmails` and cross-platform `bioSocials` (`instagram.com`, `x.com`, `youtube.com`, `tiktok.com`, `linkedin.com`, `substack.com`, `linktr.ee`), and computes `avgLikes`, `avgReplies`, `avgReposts` and `engagementRatePct` across sampled non-reply posts.
- **Multi-page user timelines** (`usernames` with `accountMode: "postsAndProfiles"` or `"postsOnly"`) — paginates past the initial page of posts up to `maxPostsPerSource` (`1`–`500` per handle) and stops early automatically when `postedAfter` is reached.
- **Keyword & topic search** (`searchQueries`) — searches public Threads discussions in either **Top** (`"default"`) or **Newest** (`"recent"`) order with automatic cursor pagination.
- **Post details & clean direct replies** (`postUrls`) — extracts the target post (`rowType: "post"`) together with its direct reply thread (`rowType: "reply"`), while stripping unrelated "recommended posts" clutter so every row belongs to the conversation you asked for.

**Use it when you need:** creator partnership vetting with real engagement rates and unwrapped contact links; scheduled monitoring of executive, competitor or brand accounts on Threads; live keyword/product-mention feeds; or audience reply sentiment analysis on viral Threads announcements.

**Use something else when:** you need **private accounts**, **follower/following member rosters**, or **private impression analytics**. Meta keeps private timelines and follower lists behind login, and public Threads feeds omit exact per-post impression counters (`viewCount` is emitted honestly as `null` rather than a fake `0`). For Instagram profiles or posts from the same creators, pair this Actor with [Instagram Profile Scraper](https://apify.com/foxlabs/instagram-profile-scraper) and [Instagram Post Scraper](https://apify.com/foxlabs/instagram-post-scraper).

### 🤖 Use with AI agents (MCP, Claude, Cursor & x402)

**Already connected to the Apify MCP server?** Ask your assistant to call `foxlabs/threads-scraper` directly.

- **Hosted MCP URL (zero install):** `https://mcp.apify.com?tools=foxlabs/threads-scraper`
- **Local stdio config (Claude Desktop, Cursor, Cline, Windsurf):**

```json
{
  "mcpServers": {
    "threads-scraper": {
      "command": "npx",
      "args": ["-y", "@apify/actors-mcp-server", "--tools", "foxlabs/threads-scraper"],
      "env": { "APIFY_TOKEN": "YOUR_APIFY_TOKEN" }
    }
  }
}
```

**Your agent can pay for its own runs.** This Actor uses transparent pay-per-event billing and supports agentic micropayments, allowing autonomous agents with a wallet to discover, invoke and settle runs over **x402 (USDC on Base)** or **Skyfire** as well as standard Apify API tokens. Billing is identical either way: per delivered `profile` or `post` row, with diagnostic `status` rows free.

Copy-paste prompt for Claude, ChatGPT, Cursor or any MCP-enabled agent:

```text
Use the Apify Actor `foxlabs/threads-scraper` to collect public Meta Threads creator profiles, timeline posts, keyword searches or post replies.

Input fields:
- `usernames`: array of handles or URLs (e.g. ["zuck", "@mosseri", "https://www.threads.com/@natgeo"])
- `searchQueries`: array of keywords or phrases (e.g. ["ai agents", "claude code"])
- `postUrls`: array of Threads post URLs to extract the target post + direct replies
- `accountMode`: "postsAndProfiles" (default) | "postsOnly" | "profilesOnly"
- `searchSort`: "default" (Top) | "recent" (Newest)
- `maxPostsPerSource`: integer 1..500 (default 25)
- `maxRepliesPerPost`: integer 1..200 (default 25)
- `maxResults`: overall row cap across the run (default 100; 0 = unlimited)
- `minLikes`: minimum like count filter on posts/replies (default 0)
- `postedAfter`: optional ISO lower date string YYYY-MM-DD
- `postedBefore`: optional ISO upper date string YYYY-MM-DD

Start with:
{"usernames":["zuck","mosseri"],"accountMode":"postsAndProfiles","maxPostsPerSource":10,"maxResults":25}
```

**Things you can ask your AI agent:**

- *"Compare @zuck and @mosseri's recent Threads engagement rates, average replies and top-liked posts from this month."*
- *"Pull the 40 newest Threads posts mentioning 'Claude Code' with at least 5 likes and summarize developer sentiment."*
- *"Fetch the direct replies on this Threads product launch URL and group user feature requests by theme."*

The machine-readable Actor summary, MCP metadata and schema live at `https://apify.com/foxlabs/threads-scraper.md`.

### 📋 Overview

Everything needed to turn public Threads handles, topic searches and post discussions into clean tabular or JSON records — with zero accounts, zero browser overhead and deterministic deduplication.

| Property | Details |
|---|---|
| **Public data source** | Public Meta Threads web profiles, search feeds & post threads (`threads.com` / `threads.net`) |
| **Authentication required** | None — zero login, cookies, session tokens or Meta developer keys |
| **Container footprint** | Lightweight `256 MB` HTTP runtime (fast cold start, minimal compute footprint) |
| **Output row types (`rowType`)** | `profile` (`$0.003`), `post` / `reply` (`$0.0015`), `status` (`$0.00` diagnostic rows) |
| **Deduplication & restart safety** | Deterministic `rowKey` (`profile:<userId>`, `post:<postId>`) — zero duplicate rows or double charges on container migration |
| **Execution modes** | Standard Batch Dataset runs + synchronous Standby HTTP API (`/profiles`, `/posts`, `/search`, `/replies`) |

**Why teams pick this Actor:**

- 📧 **Unwrapped bio links & creator contacts** — strips `l.threads.com` tracking wrappers and surfaces plain-text emails (`bioEmails`) plus 8+ cross-platform social links (`bioSocials`).
- 📈 **Computed creator engagement benchmarks** — delivers `avgLikes`, `avgReplies`, `avgReposts` and `engagementRatePct` right on every `profile` row.
- 🧹 **Zero recommendation pollution on replies** — isolates direct replies to your target post and discards unrelated "suggested threads" appended at the bottom of post pages.
- 🛡️ **Strict `null` vs. `0` data hygiene** — hidden like counts (`likesHidden: true`) and unexposed public impression counters emit `null` rather than misleading zeros.
- 💰 **Predictable pay-per-event economics** — pay only for delivered profiles and posts; filtered-out items and invalid-handle `status` notes cost `$0.00`.

### ✨ Key Features

- 👤 **Rich Creator Profile Enrichment** — Extracts `userId`, `username`, `fullName`, `biography`, `followersCount`, `isVerified`, `isPrivate`, `profilePicUrl`, `hdProfilePicUrl`, unwrapped `bioLinks`, `bioEmails`, `bioSocials`, and sampled engagement metrics (`recentPostsSampled`, `avgLikes`, `avgReplies`, `avgReposts`, `engagementRatePct`).
- 📜 **Deep Timeline Pagination** — Paginates cleanly beyond the first ~10 visible timeline posts up to `maxPostsPerSource` (`1`–`500` per handle), automatically halting once non-pinned posts cross your `postedAfter` date cut-off.
- 🔎 **Top & Chronological Keyword Search** — Collects public Threads posts for any keyword, brand name, ticker or hashtag in either relevance (`searchSort: "default"`) or chronological (`searchSort: "recent"`) order.
- 💬 **Direct Post & Reply Thread Extraction** — Accepts `/post/CODE` and `/t/CODE` links on both `threads.com` and `threads.net`, emitting the root post (`rowType: "post"`) followed by paginated direct replies (`rowType: "reply"`).
- 🖼️ **Complete Media & Quoted-Post Metadata** — Captures single images, multi-slide carousels (`imageUrls`), MP4 `videoUrls`, voice notes (`audioUrl`), `mediaType` (`text`, `image`, `video`, `carousel`, `audio`), `accessibilityCaption` and structured `quotedPost` objects.
- 📊 **Spreadsheet-Ready Companion Columns** — Provides pipe/comma-joined `*Text` companion fields (`bioLinksText`, `bioEmailsText`, `bioSocialsText`, `imageUrlsText`, `videoUrlsText`) alongside arrays so CSV and Excel exports open cleanly without raw JSON brackets.

### 🎬 Quick Start (API & Standby HTTP)

**1. Synchronous Batch API call (returns clean JSON items directly):**

```bash
curl -X POST "https://api.apify.com/v2/acts/foxlabs~threads-scraper/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["zuck","mosseri"],"accountMode":"postsAndProfiles","maxPostsPerSource":10,"maxResults":25}'
```

**2. Real-time Standby HTTP API (sub-second warm container queries):**

```bash
## Fetch creator profiles on demand
curl "https://foxlabs--threads-scraper.apify.actor/profiles?usernames=zuck,mosseri&token=YOUR_APIFY_TOKEN"

## Search newest Threads posts for a keyword
curl "https://foxlabs--threads-scraper.apify.actor/search?q=openai&sort=recent&max=20&token=YOUR_APIFY_TOKEN"
```

### 🚀 Getting Started (3 steps)

1. **Choose your targets** — Enter handles or profile URLs in **Usernames** (`zuck`, `@mosseri`, `https://www.threads.com/@natgeo`), keywords in **Search queries**, or post links in **Post URLs**. You can combine all three in a single run.
2. **Set mode, depth & filters** — Pick `accountMode` (`postsAndProfiles`, `postsOnly`, or `profilesOnly`), cap volume with `maxPostsPerSource` and `maxResults`, and optionally set `minLikes` or `postedAfter` (`YYYY-MM-DD`).
3. **Run & export** — Click **Start** and download your dataset as JSON, CSV, Excel, Parquet or XML, or stream it into your warehouse via the Apify Dataset API.

### 📥 Input & Filters

```json
{
  "usernames": ["zuck", "https://www.threads.com/@mosseri"],
  "searchQueries": ["ai agents"],
  "postUrls": ["https://www.threads.com/@zuck/post/DfihFPxkaZ1"],
  "accountMode": "postsAndProfiles",
  "searchSort": "recent",
  "maxPostsPerSource": 20,
  "maxRepliesPerPost": 15,
  "maxResults": 100,
  "minLikes": 5,
  "postedAfter": "2026-01-01",
  "postedBefore": "2026-12-31"
}
```

| Field | Type | Default | Description |
|---|---|---|---|
| `usernames` | `array<string>` | Prefill `["zuck", "mosseri"]` | Public Threads handles (`zuck`, `@mosseri`) or profile URLs (`https://www.threads.com/@natgeo`, `threads.net/@openai`). |
| `searchQueries` | `array<string>` | `[]` | Keywords, brand names, tickers or hashtags to search across public Threads posts. |
| `postUrls` | `array<string>` | `[]` | Direct Threads post URLs (`/post/CODE` or `/t/CODE`) to collect the target post plus its direct replies. |
| `accountMode` | `string` | `"postsAndProfiles"` | Controls output for `usernames`: `"postsAndProfiles"` (1 profile row + up to `maxPostsPerSource` posts), `"postsOnly"`, or `"profilesOnly"`. |
| `searchSort` | `string` | `"default"` | Sort order for `searchQueries`: `"default"` (Top / highest relevance) or `"recent"` (newest posts first). |
| `maxPostsPerSource` | `integer` | `25` | Maximum timeline or search posts collected per handle or per search query (`1`–`500`; prefill `10`). |
| `maxRepliesPerPost` | `integer` | `25` | Maximum direct reply rows collected per URL in `postUrls` (`1`–`200`). |
| `maxResults` | `integer` | `100` | Overall ceiling on total billable rows delivered across the entire run (`0` = unlimited; prefill `25`). |
| `minLikes` | `integer` | `0` | Keep only post and reply rows where `likeCount >= minLikes` (`0` keeps all posts, including hidden-like posts). |
| `postedAfter` | `string` | `""` | Optional ISO-8601 lower date cut-off (`YYYY-MM-DD`). Skips older posts and stops profile pagination once non-pinned posts pass this date. |
| `postedBefore` | `string` | `""` | Optional ISO-8601 upper date cut-off (`YYYY-MM-DD`). Skips posts published after the end of this date for exact historical window queries. |
| `proxyConfiguration` | `object` | `{"useApifyProxy": true}` | Managed automatically via Apify Proxy. No custom proxy setup is needed. |

**Copy-paste input recipes:**

- **Creator outreach & engagement scorecard (`profilesOnly`):**
  `{"usernames":["mosseri","mkbhd","natgeo","openai"],"accountMode":"profilesOnly","maxResults":50}`
- **Chronological brand/keyword listening (`searchQueries` only):**
  `{"usernames":[],"searchQueries":["claude code","apify"],"searchSort":"recent","minLikes":3,"maxPostsPerSource":40,"maxResults":80}`
- **Viral announcement reply audit (`postUrls` only):**
  `{"usernames":[],"postUrls":["https://www.threads.com/@zuck/post/DfihFPxkaZ1"],"maxRepliesPerPost":50,"maxResults":55}`

### 📤 Output Schema & Real Sample Record

Every row in the default Dataset carries deterministic `rowKey`, `rowType`, `sourceType`, `input`, `url` and `scrapedAt` fields. Invalid handles, deleted URLs or empty inputs emit a free `rowType: "status"` diagnostic row with an explanatory message so no target in your batch ever vanishes silently.

#### Profile rows (`rowType: "profile"`)

| Field | Type | Description |
|---|---|---|
| `rowKey` | `string` | Deterministic unique key `profile:<userId>` |
| `userId` / `username` / `fullName` | `string` | Numeric Meta account ID, normalized handle and display name |
| `biography` / `text` | `string \| null` | Full profile biography text |
| `followersCount` | `integer \| null` | Public follower count reported by Threads |
| `isVerified` / `isPrivate` | `boolean \| null` | Meta verified badge and private-account status flag |
| `profilePicUrl` / `hdProfilePicUrl` | `string \| null` | Standard and high-resolution CDN avatar URLs |
| `bioLinks` / `bioLinksText` | `array` / `string` | Unwrapped external websites (`l.threads.com` redirects decoded) |
| `bioEmails` / `bioEmailsText` | `array` / `string` | Lowercased public contact email addresses parsed from the biography |
| `bioSocials` / `bioSocialsText` | `array` / `string` | Cross-platform social links (`instagram.com`, `x.com`, `youtube.com`, `tiktok.com`, `linkedin.com`, `substack.com`, etc.) |
| `recentPostsSampled` | `integer` | Count of recent non-reply posts sampled to compute engagement averages |
| `avgLikes` / `avgReplies` / `avgReposts` | `number \| null` | Mean likes, direct replies and reposts per sampled post |
| `engagementRatePct` | `number \| null` | `((avgLikes + avgReplies + avgReposts) / followersCount) * 100`, rounded to 3 decimals |

#### Post & Reply rows (`rowType: "post"` | `"reply"`)

| Field | Type | Description |
|---|---|---|
| `rowKey` | `string` | Deterministic unique key `post:<postId>` |
| `postId` / `code` / `url` | `string` | Numeric post ID, shortcode (`DfihFPxkaZ1`) and canonical `threads.com` permalink |
| `publishedAt` | `string \| null` | Exact UTC ISO-8601 publication timestamp |
| `text` / `language` | `string` / `string \| null` | Post body text and ISO language code |
| `hashtags` / `mentions` / `externalUrls` | `array<string>` | Extracted `#hashtags`, `@mentions` (text + tagged users), and unwrapped external outbound URLs |
| `topicTag` / `replyControl` / `fediverseEnabled` | `string \| null` / `boolean \| null` | Threads topic tag badge, reply audience permission (`"everyone"`, `"accounts_you_follow"`), and ActivityPub fediverse sharing flag |
| `likeCount` / `replyCount` / `repostCount` / `quoteCount` / `reshareCount` | `integer \| null` | Public engagement counters (`null` when hidden or unexposed, never fake `0`) |
| `viewCount` | `integer \| null` | Public impression count when exposed (`null` on logged-out Threads feeds) |
| `likesHidden` / `isPinned` / `isReply` / `isPaidPartnership` / `captionIsEdited` | `boolean` | Post state flags |
| `replyToUsername` | `string \| null` | Parent author handle when `isReply` is `true` |
| `mediaType` / `mediaWidth` / `mediaHeight` / `carouselCount` | `string` / `integer \| null` | `"text"`, `"image"`, `"video"`, `"carousel"`, or `"audio"`, pixel dimensions, and slide count |
| `imageUrls` / `videoUrls` / `audioUrl` | `array` / `string \| null` | Direct CDN media URLs (plus `imageUrlsText` and `videoUrlsText` for CSV) |
| `hasAudio` / `audioTitle` / `audioArtist` / `pollOptions` | `boolean` / `string \| null` / `array` | Audio/music metadata and interactive poll tally objects (`{ text, count }`) |
| `accessibilityCaption` | `string \| null` | Alt-text / image accessibility description when present |
| `quotedPost` | `object \| null` | Embedded quoted post (`postId`, `code`, `authorUsername`, `text`, `publishedAt`) |
| `authorId` / `authorUsername` / `authorFullName` / `authorVerified` / `authorProfilePicUrl` | `string` / `boolean` | Post author metadata |

#### Real sample records (from live platform run `vtoF6H62LvqSreNZR`, 2026-11-14)

```json
{
  "rowKey": "profile:63055343223",
  "rowType": "profile",
  "sourceType": "profile",
  "input": "zuck",
  "userId": "63055343223",
  "username": "zuck",
  "fullName": "Mark Zuckerberg",
  "text": "Mostly superintelligence and MMA takes",
  "biography": "Mostly superintelligence and MMA takes",
  "followersCount": 5777528,
  "isVerified": true,
  "isPrivate": false,
  "profilePicUrl": "https://scontent-dfw5-2.cdninstagram.com/v/t51.82787-19/825322135_17989325280103224_1252773933700107438_n.jpg?stp=dst-jpg_s150x150_tt6",
  "hdProfilePicUrl": "https://scontent-dfw5-2.cdninstagram.com/v/t51.82787-19/825322135_17989325280103224_1252773933700107438_n.jpg?stp=dst-jpg_s640x640_tt6",
  "bioLinks": [],
  "bioLinksText": "",
  "bioEmails": [],
  "bioEmailsText": "",
  "bioSocials": [],
  "bioSocialsText": "",
  "recentPostsSampled": 4,
  "avgLikes": 2485,
  "avgReplies": 532.8,
  "avgReposts": 104.3,
  "engagementRatePct": 0.054,
  "url": "https://www.threads.com/@zuck",
  "scrapedAt": "2026-11-14T05:02:18.045Z"
}
```

```json
{
  "rowKey": "post:4026926512892651125",
  "rowType": "post",
  "sourceType": "user_posts",
  "input": "zuck",
  "postId": "4026926512892651125",
  "code": "DfihFPxkaZ1",
  "url": "https://www.threads.com/@zuck/post/DfihFPxkaZ1",
  "publishedAt": "2026-11-09T23:31:10.000Z",
  "text": "Pavlova with Muse helping on our quest to go beyond beginner baking recipes!",
  "language": "en",
  "isPinned": false,
  "isReply": false,
  "replyToUsername": null,
  "isPaidPartnership": false,
  "captionIsEdited": false,
  "likesHidden": false,
  "likeCount": 1378,
  "replyCount": 180,
  "repostCount": 47,
  "quoteCount": 9,
  "reshareCount": 30,
  "viewCount": null,
  "mediaType": "carousel",
  "imageUrls": [
    "https://scontent-dfw5-2.cdninstagram.com/v/t51.82787-15/900924821_17996711844103224_7104678187536730142_n.webp"
  ],
  "imageUrlsText": "https://scontent-dfw5-2.cdninstagram.com/v/t51.82787-15/900924821_17996711844103224_7104678187536730142_n.webp",
  "videoUrls": [],
  "videoUrlsText": "",
  "audioUrl": null,
  "accessibilityCaption": null,
  "quotedPost": null,
  "authorId": "63055343223",
  "authorUsername": "zuck",
  "authorFullName": "Mark Zuckerberg",
  "authorVerified": true,
  "authorProfilePicUrl": "https://scontent-dfw5-2.cdninstagram.com/v/t51.82787-19/825322135_17989325280103224_1252773933700107438_n.jpg",
  "scrapedAt": "2026-11-14T05:02:18.046Z"
}
```

Every completed batch run also writes a structured `SOURCE_REPORT` JSON object to the default Key-Value Store summarizing per-target status, request counts and delivered row totals.

### 🧪 Data Quality — Measured

Verified on the Apify platform across QA and production D+0 runs (`vwXQIhcKrVlzSQW8X`, `vtoF6H62LvqSreNZR`, `PnNtbfygESLfJBWxT` on 2026-11-13 and 2026-11-14):

- **100% row uniqueness:** Every delivered record is deduplicated by `rowKey` (`profile:<userId>` and `post:<postId>`). In prefill run `vwXQIhcKrVlzSQW8X` (`22` rows: `2` profiles + `20` posts), `22 / 22` keys were unique (`0` duplicates).
- **Core field completeness:** `userId`, `username`, `followersCount`, `isVerified`, `hdProfilePicUrl` and `engagementRatePct` populated on `100%` of public profile rows; `postId`, `code`, `url`, `publishedAt`, `mediaType`, `authorId` and `authorUsername` populated on `100%` of post and reply rows.
- **Zero suggested-feed contamination:** On post detail pages, Threads appends unrelated "recommended threads" below direct replies; our parser isolates direct reply nodes only, verified during QA before promotion.
- **Exact billing alignment:** In live D+0 billing verification (`vtoF6H62LvqSreNZR` delivering `1` profile + `4` posts, and empty-input run `PnNtbfygESLfJBWxT` delivering `1` `status` row), settled `chargedEventCounts` matched expected billable counts `100%` (`{profile: 1, post: 4}` and `{profile: 0, post: 0}`).

### ⏱️ Performance — Measured

Measured on the Apify platform at the default **`256 MB`** memory tier:

- **Prefill batch (`2` profiles + `20` timeline posts, run `vwXQIhcKrVlzSQW8X`):** completed in **`17.1 seconds`** end-to-end with zero browser startup delay.
- **Lightweight memory footprint:** Runs comfortably inside `256 MB` RAM because all profile, timeline, search and reply requests execute over pure HTTP rather than Chromium.
- **Container migration resilience:** On startup, the Actor reads any `rowKey` values already stored in the run's default Dataset and skips them automatically, preventing duplicate rows or duplicate charges if a long batch migrates across servers.

### 💼 Use Cases

1. **Influencer & Creator Vetting (`profilesOnly` or `postsAndProfiles`)**
   - *Input:* `{"usernames":["mosseri","mkbhd","natgeo"],"accountMode":"profilesOnly","maxResults":50}`
   - *Output:* One enriched lead row per creator with `followersCount`, `engagementRatePct`, `avgLikes`, unwrapped `bioLinks`, `bioEmails` and `bioSocials`.
   - *Business action:* Rank sponsorship candidates by real audience engagement instead of raw follower counts and push verified bio links/emails directly into Clay, HubSpot or Apollo.

2. **Real-Time Brand, Competitor & Launch Monitoring (`searchQueries`)**
   - *Input:* `{"usernames":[],"searchQueries":["apify","claude code"],"searchSort":"recent","minLikes":3,"maxPostsPerSource":50,"maxResults":100}`
   - *Output:* Chronological public Threads posts mentioning your product or competitors with author handles, verification badges and engagement metrics.
   - *Business action:* Route high-velocity product mentions into Slack or Zendesk within minutes of publication.

3. **Viral Post Reply & Customer Voice Analysis (`postUrls`)**
   - *Input:* `{"usernames":[],"postUrls":["https://www.threads.com/@zuck/post/DfihFPxkaZ1"],"maxRepliesPerPost":60,"maxResults":65}`
   - *Output:* The root announcement (`rowType: "post"`) plus clean direct audience replies (`rowType: "reply"`).
   - *Business action:* Feed audience replies to an LLM to cluster feature requests, pricing objections and sentiment themes.

4. **Executive & Competitor Content Cadence Tracking (`postedAfter`)**
   - *Input:* `{"usernames":["zuck","mosseri","sama"],"accountMode":"postsOnly","postedAfter":"2026-11-01","maxPostsPerSource":100,"maxResults":300}`
   - *Output:* Every non-reply post published since your date cut-off with media types, carousels, quoted posts and engagement totals.
   - *Business action:* Benchmark posting frequency, media format mix (`text` vs. `carousel` vs. `video`) and message resonance over time.

### 🔗 Integrations (Node.js, Python, n8n, Make & Clay)

#### JavaScript / Node.js (`apify-client`)

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('foxlabs/threads-scraper').call({
    usernames: ['zuck', 'mosseri'],
    accountMode: 'postsAndProfiles',
    maxPostsPerSource: 20,
    maxResults: 50,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(`Fetched ${items.length} Threads rows`, items[0]);
```

#### Python (`apify-client` v3)

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("foxlabs/threads-scraper").call(
    run_input={
        "usernames": ["zuck", "mosseri"],
        "accountMode": "postsAndProfiles",
        "maxPostsPerSource": 20,
        "maxResults": 50,
    }
)

for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item["rowType"], item.get("username") or item.get("authorUsername"), item["url"])
```

*(Written for `apify-client` v3 where `call()` returns a `Run` object exposing `run.default_dataset_id`; on `apify-client` v1/v2 use `run["defaultDatasetId"]`.)*

#### n8n, Make, Zapier & Clay

- **Scheduled pipelines (n8n / Make / Zapier):** Trigger on a daily or hourly schedule → run `foxlabs/threads-scraper` with `postedAfter` set to yesterday's ISO date → filter `rowType === "post"` → append new mentions to Google Sheets, Airtable, Notion, Slack or BigQuery.
- **Clay lead enrichment:** Call the Standby `/profiles?usernames={{handle}}` HTTP endpoint directly from a Clay HTTP API column to enrich creator lists with `followersCount`, `engagementRatePct`, unwrapped `bioLinks` and `bioEmails` in real time.

### 📊 Pricing (Pay-Per-Event)

This Actor uses transparent **Pay-Per-Event (PPE)** pricing — no monthly subscription, no hidden proxy add-ons:

| Event Name | Trigger | Price per Item | Price per 1,000 |
|---|---|---|---|
| `profile` | Once per unique `rowType: "profile"` record delivered | **$0.0030** | **$3.00 / 1,000** |
| `post` | Once per unique `rowType: "post"` or `rowType: "reply"` record delivered | **$0.0015** | **$1.50 / 1,000** |
| `status` *(diagnostic)* | Invalid handle, deleted URL, or zero-match filter note | **$0.00 (Free)** | **$0.00** |

**Worked cost examples:**

- **50 creator profiles** (`accountMode: "profilesOnly"`): `50 × $0.003` = **$0.15**
- **10 accounts × (1 profile + 25 posts each):** `10 × $0.003 + 250 × $0.0015` = **$0.405**
- **1,000 keyword search posts** (`searchQueries`): `1,000 × $0.0015` = **$1.50**

**Billing guarantees:**

- **Proxy traffic is included:** Apify Proxy usage happens inside our execution environment and is covered by the per-event price above.
- **Duplicates & filtered posts are free:** Posts excluded by `minLikes` or `postedAfter`, duplicate posts across overlapping queries, and `rowType: "status"` rows are **never charged**.
- **Exact spend cap support:** Set **Maximum cost per run** in Apify Console or API options; the Actor checks remaining budget via Apify's `ChargingManager` before emitting each batch and halts cleanly at your ceiling. *(Note: if Apify applies its platform `apify-actor-start` fee on your plan, that platform start event applies when a run starts, including runs that return zero billable rows.)*

### ❓ Frequently Asked Questions (FAQ)

#### Do I need a Meta, Instagram or Threads account, cookies, or API key to use this Actor?

No. The Actor collects publicly visible Meta Threads profiles, timelines, keyword search feeds and post reply pages completely keylessly on our infrastructure. You never supply login credentials, session cookies, developer tokens or external proxies, eliminating any risk of account lockouts or rate-limit bans on your own social accounts.

#### How is this different from Meta's official Threads API?

Meta's official Threads API is built for first-party publishing and analytics on accounts you own and authenticate via OAuth; it does not allow open lookup of arbitrary third-party public creators, unauthenticated topic searches across Threads, or reading replies on third-party public threads. This Actor extracts publicly rendered web data across any public handle, keyword phrase or post URL without OAuth app review.

#### How many timeline posts can I collect from a single Threads handle?

While initial Threads profile pages display roughly 10 recent posts on first load, setting `maxPostsPerSource` above 10 instructs the Actor to paginate deeper through the account's public timeline up to `500` posts per handle per run. Collection stops automatically as soon as `maxPostsPerSource`, `maxResults`, or your `postedAfter` date boundary is reached, or when Meta's public logged-out pagination window ends.

#### Why is `viewCount` (`null`) empty on standard Threads post rows?

On logged-out public Threads pages, Meta exposes exact `likeCount`, `replyCount`, `repostCount`, `quoteCount` and `reshareCount` counters, but omits public per-post impression numbers. Rather than writing misleading `0` values that would corrupt your engagement averages, the Actor strictly emits `viewCount: null` whenever public impression counts are unavailable, and flags hidden like counters explicitly via `likesHidden: true`.

#### How are `avgLikes` and `engagementRatePct` calculated on profile rows?

When processing each handle in `usernames`, the Actor samples recent non-reply posts loaded from that creator's timeline (`recentPostsSampled` — typically ~10 posts in `profilesOnly` mode or up to `maxPostsPerSource` in `postsAndProfiles` mode). It calculates the arithmetic mean of likes, direct replies and reposts across those sampled posts, then computes `((avgLikes + avgReplies + avgReposts) / followersCount) * 100` rounded to three decimal places.

#### Does the Actor unwrap `l.threads.com` redirect links and extract creator emails?

Yes. External websites listed in a creator's Threads profile or biography are normally wrapped inside `https://l.threads.com/?u=…` or `https://l.instagram.com/?u=…` tracking redirects; the Actor automatically strips those wrappers and outputs clean destination URLs in `bioLinks`. Any email addresses or cross-platform social profile links (`instagram.com`, `x.com`, `youtube.com`, `tiktok.com`, `linkedin.com`, `substack.com`, `linktr.ee`) written in plain text in the biography are also parsed into `bioEmails` and `bioSocials`.

#### How do I run only `searchQueries` or only `postUrls` without scraping the prefilled usernames?

In the Apify Console Input tab, clear the prefilled `usernames` array before clicking Start. When calling the Actor via REST API, SDK, n8n or MCP, explicitly pass `"usernames": []` alongside your `"searchQueries"` or `"postUrls"` list (for example: `{"usernames": [], "searchQueries": ["openai"], "maxResults": 30}`).

#### Are legacy `threads.net` URLs and `/t/` shortlinks supported alongside `threads.com`?

Yes. Meta migrated Threads' primary domain from `threads.net` to `threads.com`, and public links in the wild still use both domains as well as both `/@handle/post/CODE` and `/t/CODE` URL patterns. Input normalization accepts `@handle`, bare handles, `threads.com`, and `threads.net` profile and post URLs interchangeably and canonicalizes output links to `https://www.threads.com/...`.

#### What happens if one username or post URL in a 100-target batch is invalid or deleted?

A single typo, suspended handle or deleted post URL never crashes your entire batch. Following clean status handling, the Actor writes one free `rowType: "status"` diagnostic record identifying the exact input string that could not be resolved, charges `$0.00` for that row, and continues scraping all remaining valid targets in your input list.

#### How do I run incremental daily monitoring without paying for old posts again?

Set `postedAfter` to your last run's date (`YYYY-MM-DD`, such as yesterday's date) and schedule the Actor on Apify Schedules or via n8n/Make. For user timelines, once pagination encounters non-pinned posts older than `postedAfter` (pinned posts at the top of a profile are checked safely without prematurely stopping pagination), the Actor halts further requests for that handle immediately, saving both run time and event charges.

#### What is the difference between Batch mode and Standby HTTP mode?

Batch mode (`POST /v2/acts/foxlabs~threads-scraper/runs`) is ideal for scraping dozens or hundreds of handles, searches and reply threads asynchronously into a persistent Apify Dataset (`JSON`, `CSV`, `Excel`, `Parquet`). Standby HTTP mode keeps a warm lightweight HTTP server ready at `foxlabs--threads-scraper.apify.actor` (`/profiles`, `/posts`, `/search`, `/replies`) so AI agents, Clay tables and interactive apps can fetch small real-time JSON responses in seconds.

#### What happens if Apify migrates or restarts the container mid-run?

At startup, the Actor inspects the default Dataset of the current run, loads every `rowKey` (`profile:<userId>` and `post:<postId>`) already written before the restart, and skips delivering or charging those items again. Combined with deterministic `rowKey` deduplication across overlapping search queries, every unique profile or post in a run is billed at most once.

### 🐛 Troubleshooting

- **Dataset contains only a `rowType: "status"` row saying `"Empty input"`:** You passed explicit empty arrays (`{"usernames": []}`) without supplying any `searchQueries` or `postUrls`. Add at least one handle, search keyword, or post URL.
- **Fewer posts returned than `maxPostsPerSource`:** Check whether `maxResults` (overall run cap, default `100`), `minLikes`, or `postedAfter` filtered or capped results early, or inspect `SOURCE_REPORT` in the Key-Value Store to see how many public posts the account actually has.
- **Private account (`isPrivate: true`) returned `profile` row but zero `post` rows:** Private Threads accounts expose their public header card (`followersCount`, `biography`, `isPrivate: true`) to logged-out visitors, but timeline posts are hidden behind approved follower login.
- **Invalid `postedAfter` format message:** Ensure `postedAfter` uses strict `YYYY-MM-DD` ISO date syntax (for example `"2026-11-01"`).
- **Run stopped cleanly before reaching `maxResults` with budget note:** Your Apify **Maximum cost per run** cap was reached; raise the run's spend cap if you want deeper pagination.

### 🚧 What It Does Not Do

- Does **not** access private Threads timelines (`isPrivate: true`), direct messages, or restricted age-gated profiles that require an authenticated Instagram/Threads login.
- Does **not** scrape follower or following member lists (Meta requires an authenticated session to view follower rosters).
- Does **not** fabricate view/impression counts (`viewCount` is `null` where Meta's public logged-out payload omits impressions).

### ⚠️ Trademark Notice

This Actor is an independent data-collection tool built by **foXLabs** and is not affiliated with, endorsed by, or sponsored by Meta Platforms, Inc., Instagram, or Threads. All product and company names are trademarks of their respective owners and are used solely to describe compatibility with publicly accessible web pages.

### ⚖️ Is It Legal to Scrape Public Threads Data?

This Actor reads only publicly available Threads profiles, posts and replies that Meta serves to any unauthenticated visitor on the open web — with no login, no cookie injection, and no bypassing of private account controls. Publicly visible biographies and posts may still contain personal data (such as creator names or business contact emails) protected under GDPR, CCPA and similar privacy frameworks. Always ensure you have a lawful basis for downstream storage, outreach or processing, and respect applicable laws and platform terms.

### 🤝 Support, Custom Data & Contact

- 🌐 **Website & full portfolio:** [data.foxlabs.com.tr](https://data.foxlabs.com.tr)
- 📧 **Custom data & enterprise inquiries:** info@foxlabs.com.tr
- 🐛 **Bug reports & feature requests:** open an issue in the Actor's **Issues** tab on Apify Store (include your Run ID)
- 🧰 **Browse all foXLabs Actors:** [apify.com/foxlabs](https://apify.com/foxlabs)

### Changelog

#### 0.1.4 — 2026-11-14

- Added `postedBefore` (`YYYY-MM-DD`) upper date cutoff filter alongside `postedAfter` and expanded dataset output from 56 to 69 fields (`hashtags`, `mentions`, `externalUrls`, `topicTag`, `replyControl`, `fediverseEnabled`, `mediaWidth`, `mediaHeight`, `carouselCount`, `hasAudio`, `audioTitle`, `audioArtist`, `pollOptions`).

#### 0.1.3 — 2026-11-14

- Upgraded documentation to full SIÁN standard with MCP & x402 AI agent configuration, Standby HTTP endpoint examples, measured platform QA benchmarks, worked pay-per-event cost examples, and expanded 12-question FAQ.

#### 0.1 — 2026-11-13

- Initial release of `foxlabs/threads-scraper` supporting public creator profiles (`bioLinks`, `bioEmails`, `bioSocials`, `engagementRatePct`), multi-page user timelines, Top/Recent keyword search, clean post + direct reply extraction, restart-safe `rowKey` deduplication, and Batch + Standby HTTP modes.

# Changelog

This Actor's version history is a separate document: https://apify.com/foxlabs/threads-scraper/changelog.md

# Actor input Schema

## `usernames` (type: `array`):

Threads handles (with or without @, such as zuck or @mosseri) or full profile URLs (https://www.threads.com/@natgeo). Leave empty if you only want keyword search or post replies.

## `searchQueries` (type: `array`):

Optional keywords, phrases or hashtags to search on Threads (for example: openai, "ai agents", #buildinpublic). Returns public posts matching each query.

## `postUrls` (type: `array`):

Optional Threads post URLs (for example: https://www.threads.com/@zuck/post/DfihFPxkaZ1) to extract the target post together with its direct replies.

## `accountMode` (type: `string`):

Choose whether usernames emit both profile summary rows and post rows, only posts, or only enriched profile rows.

## `searchSort` (type: `string`):

Applies when Search queries are given: Top (relevance/engagement) or Recent (newest posts).

## `maxPostsPerSource` (type: `integer`):

Maximum posts to collect per account or per search query. Profile timelines paginate automatically via Threads GraphQL.

## `maxRepliesPerPost` (type: `integer`):

Maximum reply rows to extract for each URL in Post URLs.

## `maxResults` (type: `integer`):

Hard ceiling on total delivered rows across the entire run to control spend. Set 0 for no overall cap.

## `minLikes` (type: `integer`):

Only keep post/reply rows with at least this many likes (0 = keep all).

## `postedAfter` (type: `string`):

Optional ISO date filter (such as 2026-01-01). Posts older than this date are skipped and profile pagination stops once older non-pinned posts are reached.

## `postedBefore` (type: `string`):

Optional ISO upper date filter (such as 2026-12-31). Posts newer than the end of this date are skipped.

## `proxyConfiguration` (type: `object`):

Uses Apify Proxy automatically (starts on free datacenter sessions and escalates if rate-limited). No setup needed.

## Actor input object example

```json
{
  "usernames": [
    "zuck",
    "mosseri"
  ],
  "accountMode": "postsAndProfiles",
  "searchSort": "default",
  "maxPostsPerSource": 10,
  "maxRepliesPerPost": 25,
  "maxResults": 25,
  "minLikes": 0,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "usernames": [
        "zuck",
        "mosseri"
    ],
    "maxPostsPerSource": 10,
    "maxResults": 25
};

// Run the Actor and wait for it to finish
const run = await client.actor("foxlabs/threads-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "usernames": [
        "zuck",
        "mosseri",
    ],
    "maxPostsPerSource": 10,
    "maxResults": 25,
}

# Run the Actor and wait for it to finish
run = client.actor("foxlabs/threads-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "usernames": [
    "zuck",
    "mosseri"
  ],
  "maxPostsPerSource": 10,
  "maxResults": 25
}' |
apify call foxlabs/threads-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,foxlabs/threads-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/wqtgKmJq2dVHaqEct/builds/eMEz6K3jAAFGrnYfK/openapi.json
