# Threads Search Scraper with engagement metrics (`entrogix_works/threads-search-scraper`) Actor

Search Meta Threads and get posts with computed engagement metrics and a distribution summary. Unofficial; not affiliated with Meta.

- **URL**: https://apify.com/entrogix\_works/threads-search-scraper.md
- **Developed by:** [Entrogix Works](https://apify.com/entrogix_works) (community)
- **Categories:** Social media
- **Stats:** 2 total users, 1 monthly users, 94.7% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$4.00 / 1,000 post scrapeds

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Threads Search Scraper — with engagement metrics

Search Meta Threads by keyword and get back structured posts **with engagement already computed**, plus a summary that tells you whether the conversation is driven by a few viral posts or spread evenly.

Most Threads scrapers hand you a raw dump of posts and leave you to work out what actually landed. This one ranks and quantifies it for you.

### What you get per post

| Field | Example |
|---|---|
| `username`, `isVerified` | `underthedesknews`, `true` |
| `text` | plain-text post body, HTML stripped |
| `likeCount`, `replyCount`, `repostCount` | `1273`, `12`, `28` |
| `totalEngagement`, `weightedScore` | `1313`, `1449` |
| `replyRatio`, `repostRatio` | `0.009`, `0.021` |
| `postedAt`, `language` | ISO 8601 timestamp, `en` |
| `url`, `postId`, `code` | direct link to the post |

`weightedScore` counts replies 3× and reposts 5× against a like, because they cost the reader more effort — it surfaces posts that actually moved people, not just ones that scrolled past a lot of thumbs.

`replyRatio` is useful on its own: a high value means the post started an argument rather than earning agreement.

### Summary (key-value store, `ENGAGEMENT_SUMMARY`)

- `totalPosts`, `totalEngagement`, `medianEngagement`, `maxEngagement`
- **`topShare`** — what fraction of all engagement the top 10% of posts captured. Close to 1 means a couple of viral posts dominate the topic; low means broad participation.
- `verifiedShare` — how much of the conversation comes from verified accounts
- `languages` — language breakdown of the results

### Input

```json
{
  "queries": ["ai", "machine learning"],
  "serpType": "top",
  "maxItemsPerQuery": 50
}
```

Each keyword is searched separately and tagged in the output via `searchQuery`.

### Scope and limits — please read

**Threads returns roughly 20 posts per search without infinite scrolling, and this Actor does not scroll.** Setting `maxItemsPerQuery` above that will not produce more posts for a single keyword. To collect a larger sample, pass **several related keywords** rather than raising the limit.

This is a deliberate design choice: it reads only what Threads serves publicly on the search page, without logging in and without driving a browser session. That keeps runs fast and cheap, and it keeps the Actor within what the site returns to any anonymous visitor.

It reads **public search results only**. It does not log in, does not access profiles that require authentication, and does not target private accounts.

**Display names are deliberately not returned.** You get the `@handle` and whether the account is verified, but not the profile's real-name field. Engagement analysis does not need it, and leaving it out keeps the output free of a field that is often a person's actual name. If you need to attribute a post, the `url` takes you to the source.

### Pricing

Pay per result — you are charged only for posts actually delivered to your dataset. Duplicate posts (Threads sometimes repeats results) are removed **before** charging, so you never pay twice for the same post.

### Disclaimer

**This is an unofficial tool and is not affiliated with, endorsed by, or sponsored by Meta or Threads.** "Threads" and "Meta" are trademarks of their respective owners and are used here only to describe what this Actor reads. You are responsible for ensuring your use of the collected data complies with applicable law and with Meta's terms.

# Actor input Schema

## `queries` (type: `array`):

One or more keywords or hashtags. Each is searched separately. Because Threads returns roughly 20 posts per search without scrolling, use several related keywords to collect more.

## `serpType` (type: `string`):

How Threads should rank the results.

## `maxItemsPerQuery` (type: `integer`):

Upper bound per keyword. Threads returns about 20 per search, so higher values rarely change the result.

## `minIntervalMs` (type: `integer`):

Politeness delay between searches.

## `useProxy` (type: `boolean`):

Off by default — this target was measured to work 5/5 without a proxy. Turn on only if you hit blocks.

## `proxyType` (type: `string`):

Used only when Use Apify Proxy is on. DATACENTER is far cheaper than RESIDENTIAL and was measured to work here.

## Actor input object example

```json
{
  "queries": [
    "ai",
    "openclaude"
  ],
  "serpType": "default",
  "maxItemsPerQuery": 50,
  "minIntervalMs": 2000,
  "useProxy": false,
  "proxyType": "DATACENTER"
}
```

# 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 = {
    "queries": [
        "ai",
        "openclaude"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("entrogix_works/threads-search-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 = { "queries": [
        "ai",
        "openclaude",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("entrogix_works/threads-search-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 '{
  "queries": [
    "ai",
    "openclaude"
  ]
}' |
apify call entrogix_works/threads-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,entrogix_works/threads-search-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/4Gfel657I7B2eh3jk/builds/woylwYJaQysteeKxF/openapi.json