# X (Twitter) Lead & Intent Finder — Scored Buying-Intent Leads (`b2b_leads/x-twitter-lead-intent-finder-scored-buying-intent-leads`) Actor Turn X (Twitter) into a scored lead pipeline. Detect buying intent, alternatives, pain points & recommendations in tweets, replies & bios. 0–100 relevance score, 8 sources, author filters, Slack/CRM webhooks & scheduled incremental delivery for B2B/SaaS. - **URL**: https://apify.com/b2b\_leads/x-twitter-lead-intent-finder-scored-buying-intent-leads.md - **Developed by:** [Chidubem Aneke](https://apify.com/b2b_leads) (community) - **Categories:** Lead generation, Social media, AI - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.50 / 1,000 results 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 a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 ## X Real-Time Lead & Intent Finder **Turn X (Twitter) into a warm, scored lead pipeline.** Most "Twitter scrapers" hand you a firehose of tweets and leave the hard part — *who is actually a buyer?* — to you. This Actor does the opposite. It reads tweets, replies, and profile bios the way a good SDR would, looks for **real buying and help intent** about *your* product or category, and returns a clean, deduplicated list of prospects, each scored **0–100** with a transparent breakdown of *why*. Point it at what you sell, tell it where to look, and get back people you can actually reach out to today. --- ### What you get - **Intent-scored leads, not raw tweets.** Every row is a person expressing intent, with the exact phrase and category that triggered it. - **A transparent 0–100 relevance score** built from four signals — intent strength, topic match, recency, and engagement — so you can dial quality up or down with one number. - **Bio-aware matching.** Detects intent in the tweet *and* the author's bio (e.g. "founder evaluating a new CRM"), and tells you where it matched. - **Eight discovery modes** you can mix and match: keyword search, hashtags, mentions, replies, quote-tweets, list timelines, communities, and account timelines. - **Author quality gates** to filter out bots and throwaways (followers, account age, verified/Blue, following-ratio heuristic). - **Incremental runs.** Schedule it and each run only returns *new* leads since last time — no duplicates. - **Real-time delivery** to your CRM, Slack, Zapier, Make, or Google Sheets via webhook, in addition to the dataset. --- ### Who it's for #### B2B / SaaS demand generation Find people asking "what's the best tool for X?" or "any alternative to \?" and reach them while the need is fresh. Filter to `buying_intent` and `alternative_seeking` for the hottest prospects. #### Competitor conquesting Scan **mentions of a competitor**, **replies to their announcements**, and **quote-tweets of their launches**. Catch frustrated or comparison-shopping users at the exact moment they're open to switching. #### Agencies & lead-gen shops Run one configuration per client, schedule it, and pipe scored leads straight into each client's CRM or a shared Slack channel. The per-source incremental cursor means clean daily digests with zero duplicate work. #### Social selling Give founders and reps a daily, ranked shortlist of prospects who are actively asking for what they sell — with the tweet link and a ready-to-read snippet, so they can reply personally. #### Support & success triage Watch mentions and hashtags for pain points ("frustrated with", "not working", "nightmare") about your product and route them to support before they churn or go public. --- ### How scoring works Each lead gets a **0–100 relevance score** with a `scoreBreakdown` you can inspect on every row: | Signal | Max | What it measures | | --- | --- | --- | | **Intent** | 40 | How strong the buying/help signal is (category weight + number of phrases). | | **Topic** | 25 | How many of your topic keywords the tweet/bio matches. | | **Recency** | 20 | How fresh the tweet is — newer intent is warmer. | | **Engagement** | 15 | Log-scaled likes + retweets + replies + quotes (+ views when available). | Optional **author-influence bonus** (`useAuthorInfluence`): nudges higher-follower prospects up the ranking. It's kept out of the core 100 unless you turn it on, then reported as `scoreBreakdown.authorInfluence`. **Choosing `minRelevance`:** - `0` — keep every match (most volume) - `40–55` — balanced quality (recommended starting point) - `60–75` — only strong, on-topic, high-intent leads - `80+` — very strict; fewer but hottest leads --- ### Intent categories Built-in, weighted phrase bags (you can select any subset and add your own): | Category | Weight | Example signals | | --- | --- | --- | | **Buying intent** | 5 | "looking to buy", "pricing", "free trial", "willing to pay" | | **Alternative seeking** | 4 | "alternative to", "switching from", "better than", "vs" | | **Pain point** | 3 | "frustrated with", "too expensive", "nightmare", "sick of" | | **Seeking recommendation** | 3 | "recommend", "best tool for", "what should i use" | | **Problem / help** | 2 | "how do i", "need help", "struggling with", "not working" | Add `customIntentPhrases` for your niche, and choose `matchMode`: `substring`, whole `word`, or full `regex`. The **topic gate** (`requireTopicMatch`, on by default) ensures a lead matches **both** a topic keyword **and** an intent phrase — so you get "looking for a **CRM** recommendation", not every tweet that says "recommend". Use `ignoreKeywords` to drop noise (giveaways, hiring, promos). --- ### Discovery modes Enable any combination: | Mode | What it scans | Great for | | --- | --- | --- | | **Search** | Keyword/phrase queries | Broad demand-gen | | **Hashtags** | One or more hashtags | Topic & event monitoring | | **Mentions** | Tweets mentioning @handles | Conquesting your brand or competitors | | **Replies** | Replies to target tweets/accounts | Catching responders to a competitor | | **Quotes** | Quote-tweets of target tweets/accounts | Reaction-based intent | | **List** | X List timelines | Curated prospect pools | | **Community** | X Community timelines | Niche buyer groups | | **Timeline** | Specific accounts' recent tweets | Named-account monitoring | Everything streams through the **same** intent → topic → score pipeline, is deduplicated within a run, and is memory-light thanks to cursor streaming. --- ### Output One row per lead (`featureType: "lead"`), including: - `leadType` (`tweet` | `reply` | `quote`) and `discoveryMode` - `tweetId`, `tweetUrl`, `text`, `authorUsername`, `authorName`, `createdAt`, `lang` - `engagement` (likes, retweets, replies, quotes, bookmarks, views) - `matchedIntentCategory`, `matchedIntentCategories`, `matchedIntentPhrases` - `matchedTopicKeywords`, `matchedSnippet` (centered on the first match), `matchedIn` (`tweet` | `bio` | `tweet+bio`) - `relevanceScore` and `scoreBreakdown { intent, topic, recency, engagement }` - `authorProfile` when enrichment is on (followers, following, verified/Blue, account age, tweet count, bio, location, following ratio) - `sourceQuery`, `scrapedAt`, and optional `raw` (with `includeRaw`) Unreachable, protected, or deleted targets are reported as `unavailable` rows with a reason — the run never crashes on a bad target. A per-run **summary** is written to the key-value store under `OUTPUT`: sources scanned, tweets examined, leads emitted, upstream request count, and any non-fatal errors. **Dataset views:** Overview, Leads, Buying intent, Alternative-seeking, and By source. --- ### Incremental & delivery - **Per-source cursors** are stored between runs (keyed per query/handle/list/etc.), so scheduled runs only emit tweets newer than last time. Set a manual `sinceId` floor and a `maxLeads` cap as needed. - **Webhook** (`webhookUrl` + `webhookFormat`): every new lead is POSTed to your endpoint *in addition* to being saved to the dataset. Choose `json` (full lead) or `slack` (headline, score, intent, author, topics, tweet link). Delivery failures are ignored so your dataset always fills up. --- ### Quick start 1. Set `topicKeywords` to your product/category/competitors (e.g. `["CRM", "hubspot"]`). 2. Turn on one or more sources and give them inputs (e.g. `sourceSearch` + `searchQueries`). 3. (Optional) Set `minRelevance` to `40` and turn on author gates to raise quality. 4. (Optional) Add a `webhookUrl` to push leads into Slack or your CRM in real time. 5. Run it — or schedule it for a fresh, deduplicated lead digest every day. --- ### Notes - This is a public Actor. You do **not** need to provide any X login, cookies, or personal proxy — just configure what you sell and where to look. - Data volume and freshness depend on public availability at run time. --- ### Contact me Questions, feature requests, or custom lead-gen pipelines? - **Email:** dubem115@gmail.com - **GitHub:** [github.com/DrunkCodes](https://github.com/DrunkCodes) # Actor input Schema ## `topicKeywords` (type: `array`): Your product category, competitor names, or topics a lead must mention (e.g. "CRM", "hubspot", "project management"). By default a lead must match a topic keyword AND an intent phrase. Highly recommended for signal. ## `sourceSearch` (type: `boolean`): Scan tweets returned by X keyword/phrase search using your Search queries below. The best all-round source. ## `searchQueries` (type: `array`): Keyword/phrase queries to run through X search (used when Source: keyword search is on). Example: "best CRM for startups", "hubspot alternative". ## `sourceHashtags` (type: `boolean`): Scan tweets containing the hashtags you list below. ## `hashtags` (type: `array`): One or more hashtags to scan (with or without the leading #). Example: SaaS, startups. ## `sourceMentions` (type: `boolean`): Scan tweets that mention specific @handles — e.g. your brand or a competitor. Great for conquesting. ## `mentionHandles` (type: `array`): Handles to find mentions of (with or without @). Example: hubspot, salesforce. ## `sourceReplies` (type: `boolean`): Scan replies to the target tweets or accounts below. Ideal for catching people responding to a competitor. ## `sourceQuotes` (type: `boolean`): Scan quote-tweets of the target tweets or accounts below. ## `targetTweetsOrAccounts` (type: `array`): Tweet IDs, tweet URLs, or @handles. For a handle, the actor pulls the account's recent tweets and scans their replies/quotes (competitor conquesting). ## `sourceList` (type: `boolean`): Scan tweets from one or more X List timelines listed below. ## `listIds` (type: `array`): Numeric X List IDs to scan (e.g. 1234567890123456789). Find the ID in a list URL: x.com/i/lists/. ## `sourceCommunity` (type: `boolean`): Scan tweets from one or more X Communities listed below. ## `communityIds` (type: `array`): Numeric X Community IDs to scan. Find the ID in a community URL: x.com/i/communities/. ## `sourceTimeline` (type: `boolean`): Scan recent tweets from specific accounts listed below. ## `timelineHandles` (type: `array`): Accounts whose recent tweets you want to scan (with or without @). Example: paulg, levelsio. ## `searchType` (type: `string`): How search / hashtag / mention results are ordered. Latest = most recent (best for fresh leads); Top = most engaged. ## `searchStartDate` (type: `string`): Only keep tweets created on or after this date/time (ISO 8601, e.g. 2026-06-01). Leave blank for no lower bound. ## `searchEndDate` (type: `string`): Only keep tweets created on or before this date/time (ISO 8601). Leave blank for no upper bound. ## `targetAccountTweetLimit` (type: `integer`): When a replies/quotes target is an @account, how many of its recent tweets to pull and scan replies/quotes for (1–100). ## `intentPresets` (type: `array`): Built-in intent categories to detect. Leave empty to use all of them. buying_intent is the strongest signal; problem_help the softest. ## `customIntentPhrases` (type: `array`): Extra phrases (or regex when Match mode is regex) that signal intent, added on top of the selected presets. ## `matchMode` (type: `string`): substring = phrase appears anywhere; word = whole-word match; regex = treat every phrase as a regular expression. ## `caseSensitive` (type: `boolean`): Match intent phrases and custom patterns case-sensitively. Off by default. ## `requireTopicMatch` (type: `boolean`): When on, a lead must match at least one topic keyword AND an intent phrase. Turn off to return any intent match (much noisier). ## `ignoreKeywords` (type: `array`): Skip any tweet that contains one of these words (e.g. giveaway, hiring, airdrop, promo). ## `matchInBio` (type: `boolean`): Run intent and topic detection over the author's profile bio as well as the tweet. Each lead records whether it matched in the tweet, the bio, or both. ## `minRelevance` (type: `integer`): Only return leads scoring at or above this value (0–100). Every lead's score blends four signals: intent strength, topic-keyword matches, recency, and engagement — see scoreBreakdown on each row. Guide: 0 = keep all matches (most volume); 40–55 = balanced quality (good default); 60–75 = only strong, on-topic, high-intent leads; 80+ = very strict, fewer but hottest leads. ## `enrichAuthor` (type: `boolean`): Fetch each lead author's followers, following, verified/blue status, account age, tweet count, bio, and location, and attach it as authorProfile. Auto-enabled when any author gate below is set. ## `minFollowers` (type: `integer`): Drop leads whose author has fewer than this many followers. 0 = no minimum. Enables author enrichment automatically. ## `minAccountAgeDays` (type: `integer`): Drop leads whose author account is younger than this many days (filters throwaways). 0 = no minimum. Enables author enrichment automatically. ## `mustBeVerified` (type: `boolean`): Only return leads from verified or X Premium (Blue) accounts. Enables author enrichment automatically. ## `maxFollowingRatio` (type: `integer`): Drop accounts whose following/followers ratio exceeds this value (accounts that follow far more than follow back are often bots/spam). 0 = disabled. Enables author enrichment automatically. ## `useAuthorInfluence` (type: `boolean`): Give higher-follower prospects a small ranking boost so influential leads rise to the top. Kept out of the core 0–100 score unless enabled; recorded as scoreBreakdown.authorInfluence. ## `language` (type: `string`): Only keep tweets in this language (ISO code, e.g. en, es, de). Leave blank for any language. ## `excludeRetweets` (type: `boolean`): Skip pure retweets — they rarely represent the retweeter's own intent. ## `excludeReplies` (type: `boolean`): Skip tweets that are replies (does not affect the dedicated replies source). ## `includeSensitive` (type: `boolean`): Include tweets flagged as possibly sensitive. Off by default. ## `minLikes` (type: `integer`): Only keep tweets with at least this many likes. 0 = keep everything (recommended for fresh leads, which usually have few likes). ## `minEngagement` (type: `integer`): Only keep tweets whose combined likes + retweets + replies + quotes + views is at least this value. 0 = keep everything. ## `authorAllowlist` (type: `array`): If set, only return leads from these @handles. ## `authorDenylist` (type: `array`): Never return leads from these @handles (e.g. your own accounts, known spammers). ## `maxLeads` (type: `integer`): Stop after emitting this many leads. 0 = unlimited (bounded by the per-source scan cap). ## `sinceId` (type: `string`): Optional tweet ID (snowflake). Only return tweets newer than this ID. Scheduled runs also persist a per-source cursor automatically, so each run only emits new leads. ## `perSourceScanCap` (type: `integer`): Maximum tweets to examine per source entry (per query, hashtag, handle, list, community, or target). Keeps runs memory-light and predictable. ## `webhookUrl` (type: `string`): Optional. Every lead is always saved to the run's dataset — this webhook is an ADDITIONAL real-time push. When set, each new lead is also POSTed here (CRM, Slack incoming webhook, Zapier, Make, Google Sheets). Delivery failures are ignored so the run keeps producing dataset output. ## `webhookFormat` (type: `string`): json = full lead object; slack = Slack-friendly message with headline, score, intent, author, topics, and tweet link. ## `includeRaw` (type: `boolean`): Attach the full raw tweet object under the raw field (larger output). ## `maxRetries` (type: `integer`): How many times to retry a transient upstream error (rate limit / 5xx) before giving up. ## `retryBaseDelayMs` (type: `integer`): Base backoff delay in milliseconds; grows exponentially with each retry. ## `retryMaxDelayMs` (type: `integer`): Maximum backoff delay in milliseconds between retries. ## Actor input object example ```json { "topicKeywords": [ "CRM", "hubspot" ], "sourceSearch": true, "searchQueries": [ "best CRM for startups", "hubspot alternative" ], "sourceHashtags": false, "hashtags": [ "SaaS" ], "sourceMentions": false, "mentionHandles": [ "hubspot" ], "sourceReplies": false, "sourceQuotes": false, "targetTweetsOrAccounts": [ "hubspot" ], "sourceList": false, "listIds": [], "sourceCommunity": false, "communityIds": [], "sourceTimeline": false, "timelineHandles": [], "searchType": "Latest", "searchStartDate": "", "searchEndDate": "", "targetAccountTweetLimit": 10, "intentPresets": [ "buying_intent", "alternative_seeking", "pain_point", "seeking_recommendation", "problem_help" ], "customIntentPhrases": [], "matchMode": "substring", "caseSensitive": false, "requireTopicMatch": true, "ignoreKeywords": [], "matchInBio": true, "minRelevance": 0, "enrichAuthor": false, "minFollowers": 0, "minAccountAgeDays": 0, "mustBeVerified": false, "maxFollowingRatio": 0, "useAuthorInfluence": false, "language": "", "excludeRetweets": true, "excludeReplies": false, "includeSensitive": false, "minLikes": 0, "minEngagement": 0, "authorAllowlist": [], "authorDenylist": [], "maxLeads": 0, "sinceId": "", "perSourceScanCap": 500, "webhookUrl": "", "webhookFormat": "json", "includeRaw": false, "maxRetries": 5, "retryBaseDelayMs": 2000, "retryMaxDelayMs": 30000 } ```` # Actor output Schema ## `allLeads` (type: `string`): Complete dataset with every field for each lead. ## `overview` (type: `string`): Compact table — score, intent, author, topics, snippet, and tweet link. ## `leads` (type: `string`): Full lead detail including intent phrases, topics, engagement, and score breakdown. ## `buyingIntent` (type: `string`): Leads whose strongest matched intent is buying\_intent. ## `alternativeSeeking` (type: `string`): Leads whose strongest matched intent is alternative\_seeking (people evaluating competitors). ## `bySource` (type: `string`): Leads grouped-friendly by discovery mode and source query. ## `runSummary` (type: `string`): Per-run metadata: sources scanned, tweets examined, leads emitted, upstream request count, and non-fatal errors. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "topicKeywords": [ "CRM", "hubspot" ], "searchQueries": [ "best CRM for startups", "hubspot alternative" ], "hashtags": [ "SaaS" ], "mentionHandles": [ "hubspot" ], "targetTweetsOrAccounts": [ "hubspot" ], "listIds": [], "communityIds": [], "timelineHandles": [], "intentPresets": [ "buying_intent", "alternative_seeking", "pain_point", "seeking_recommendation", "problem_help" ], "maxLeads": 0, "perSourceScanCap": 500 }; // Run the Actor and wait for it to finish const run = await client.actor("b2b_leads/x-twitter-lead-intent-finder-scored-buying-intent-leads").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "topicKeywords": [ "CRM", "hubspot", ], "searchQueries": [ "best CRM for startups", "hubspot alternative", ], "hashtags": ["SaaS"], "mentionHandles": ["hubspot"], "targetTweetsOrAccounts": ["hubspot"], "listIds": [], "communityIds": [], "timelineHandles": [], "intentPresets": [ "buying_intent", "alternative_seeking", "pain_point", "seeking_recommendation", "problem_help", ], "maxLeads": 0, "perSourceScanCap": 500, } # Run the Actor and wait for it to finish run = client.actor("b2b_leads/x-twitter-lead-intent-finder-scored-buying-intent-leads").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "topicKeywords": [ "CRM", "hubspot" ], "searchQueries": [ "best CRM for startups", "hubspot alternative" ], "hashtags": [ "SaaS" ], "mentionHandles": [ "hubspot" ], "targetTweetsOrAccounts": [ "hubspot" ], "listIds": [], "communityIds": [], "timelineHandles": [], "intentPresets": [ "buying_intent", "alternative_seeking", "pain_point", "seeking_recommendation", "problem_help" ], "maxLeads": 0, "perSourceScanCap": 500 }' | apify call b2b_leads/x-twitter-lead-intent-finder-scored-buying-intent-leads --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=b2b_leads/x-twitter-lead-intent-finder-scored-buying-intent-leads", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "X (Twitter) Lead & Intent Finder — Scored Buying-Intent Leads", "description": "Turn X (Twitter) into a scored lead pipeline. Detect buying intent, alternatives, pain points & recommendations in tweets, replies & bios. 0–100 relevance score, 8 sources, author filters, Slack/CRM webhooks & scheduled incremental delivery for B2B/SaaS.", "version": "0.0", "x-build-id": "Jp0euGHRzhdbq8xrj" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/b2b_leads~x-twitter-lead-intent-finder-scored-buying-intent-leads/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-b2b_leads-x-twitter-lead-intent-finder-scored-buying-intent-leads", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/b2b_leads~x-twitter-lead-intent-finder-scored-buying-intent-leads/runs": { "post": { "operationId": "runs-sync-b2b_leads-x-twitter-lead-intent-finder-scored-buying-intent-leads", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/b2b_leads~x-twitter-lead-intent-finder-scored-buying-intent-leads/run-sync": { "post": { "operationId": "run-sync-b2b_leads-x-twitter-lead-intent-finder-scored-buying-intent-leads", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "topicKeywords": { "title": "Topic keywords (what you sell)", "type": "array", "description": "Your product category, competitor names, or topics a lead must mention (e.g. \"CRM\", \"hubspot\", \"project management\"). By default a lead must match a topic keyword AND an intent phrase. Highly recommended for signal.", "items": { "type": "string" } }, "sourceSearch": { "title": "Source: keyword search", "type": "boolean", "description": "Scan tweets returned by X keyword/phrase search using your Search queries below. The best all-round source.", "default": true }, "searchQueries": { "title": "Search queries", "type": "array", "description": "Keyword/phrase queries to run through X search (used when Source: keyword search is on). Example: \"best CRM for startups\", \"hubspot alternative\".", "items": { "type": "string" } }, "sourceHashtags": { "title": "Source: hashtags", "type": "boolean", "description": "Scan tweets containing the hashtags you list below.", "default": false }, "hashtags": { "title": "Hashtags", "type": "array", "description": "One or more hashtags to scan (with or without the leading #). Example: SaaS, startups.", "items": { "type": "string" } }, "sourceMentions": { "title": "Source: mentions", "type": "boolean", "description": "Scan tweets that mention specific @handles — e.g. your brand or a competitor. Great for conquesting.", "default": false }, "mentionHandles": { "title": "Mention handles", "type": "array", "description": "Handles to find mentions of (with or without @). Example: hubspot, salesforce.", "items": { "type": "string" } }, "sourceReplies": { "title": "Source: replies", "type": "boolean", "description": "Scan replies to the target tweets or accounts below. Ideal for catching people responding to a competitor.", "default": false }, "sourceQuotes": { "title": "Source: quote tweets", "type": "boolean", "description": "Scan quote-tweets of the target tweets or accounts below.", "default": false }, "targetTweetsOrAccounts": { "title": "Target tweets or accounts (for replies / quotes)", "type": "array", "description": "Tweet IDs, tweet URLs, or @handles. For a handle, the actor pulls the account's recent tweets and scans their replies/quotes (competitor conquesting).", "items": { "type": "string" } }, "sourceList": { "title": "Source: list timelines", "type": "boolean", "description": "Scan tweets from one or more X List timelines listed below.", "default": false }, "listIds": { "title": "List IDs", "type": "array", "description": "Numeric X List IDs to scan (e.g. 1234567890123456789). Find the ID in a list URL: x.com/i/lists/.", "items": { "type": "string" } }, "sourceCommunity": { "title": "Source: communities", "type": "boolean", "description": "Scan tweets from one or more X Communities listed below.", "default": false }, "communityIds": { "title": "Community IDs", "type": "array", "description": "Numeric X Community IDs to scan. Find the ID in a community URL: x.com/i/communities/.", "items": { "type": "string" } }, "sourceTimeline": { "title": "Source: account timelines", "type": "boolean", "description": "Scan recent tweets from specific accounts listed below.", "default": false }, "timelineHandles": { "title": "Timeline handles", "type": "array", "description": "Accounts whose recent tweets you want to scan (with or without @). Example: paulg, levelsio.", "items": { "type": "string" } }, "searchType": { "title": "Search result type", "enum": [ "Latest", "Top" ], "type": "string", "description": "How search / hashtag / mention results are ordered. Latest = most recent (best for fresh leads); Top = most engaged.", "default": "Latest" }, "searchStartDate": { "title": "From date (optional)", "type": "string", "description": "Only keep tweets created on or after this date/time (ISO 8601, e.g. 2026-06-01). Leave blank for no lower bound.", "default": "" }, "searchEndDate": { "title": "To date (optional)", "type": "string", "description": "Only keep tweets created on or before this date/time (ISO 8601). Leave blank for no upper bound.", "default": "" }, "targetAccountTweetLimit": { "title": "Recent tweets per target account", "minimum": 1, "maximum": 100, "type": "integer", "description": "When a replies/quotes target is an @account, how many of its recent tweets to pull and scan replies/quotes for (1–100).", "default": 10 }, "intentPresets": { "title": "Intent categories", "type": "array", "description": "Built-in intent categories to detect. Leave empty to use all of them. buying_intent is the strongest signal; problem_help the softest.", "items": { "type": "string", "enum": [ "buying_intent", "alternative_seeking", "pain_point", "seeking_recommendation", "problem_help" ], "enumTitles": [ "Buying intent", "Alternative seeking", "Pain point", "Seeking recommendation", "Problem / help" ] }, "default": [ "buying_intent", "alternative_seeking", "pain_point", "seeking_recommendation", "problem_help" ] }, "customIntentPhrases": { "title": "Custom intent phrases", "type": "array", "description": "Extra phrases (or regex when Match mode is regex) that signal intent, added on top of the selected presets.", "default": [], "items": { "type": "string" } }, "matchMode": { "title": "Match mode", "enum": [ "substring", "word", "regex" ], "type": "string", "description": "substring = phrase appears anywhere; word = whole-word match; regex = treat every phrase as a regular expression.", "default": "substring" }, "caseSensitive": { "title": "Case-sensitive matching", "type": "boolean", "description": "Match intent phrases and custom patterns case-sensitively. Off by default.", "default": false }, "requireTopicMatch": { "title": "Require a topic keyword match", "type": "boolean", "description": "When on, a lead must match at least one topic keyword AND an intent phrase. Turn off to return any intent match (much noisier).", "default": true }, "ignoreKeywords": { "title": "Ignore keywords", "type": "array", "description": "Skip any tweet that contains one of these words (e.g. giveaway, hiring, airdrop, promo).", "default": [], "items": { "type": "string" } }, "matchInBio": { "title": "Also match the author's bio", "type": "boolean", "description": "Run intent and topic detection over the author's profile bio as well as the tweet. Each lead records whether it matched in the tweet, the bio, or both.", "default": true }, "minRelevance": { "title": "Minimum relevance score", "minimum": 0, "maximum": 100, "type": "integer", "description": "Only return leads scoring at or above this value (0–100). Every lead's score blends four signals: intent strength, topic-keyword matches, recency, and engagement — see scoreBreakdown on each row. Guide: 0 = keep all matches (most volume); 40–55 = balanced quality (good default); 60–75 = only strong, on-topic, high-intent leads; 80+ = very strict, fewer but hottest leads.", "default": 0 }, "enrichAuthor": { "title": "Enrich author profile", "type": "boolean", "description": "Fetch each lead author's followers, following, verified/blue status, account age, tweet count, bio, and location, and attach it as authorProfile. Auto-enabled when any author gate below is set.", "default": false }, "minFollowers": { "title": "Minimum followers", "minimum": 0, "type": "integer", "description": "Drop leads whose author has fewer than this many followers. 0 = no minimum. Enables author enrichment automatically.", "default": 0 }, "minAccountAgeDays": { "title": "Minimum account age (days)", "minimum": 0, "type": "integer", "description": "Drop leads whose author account is younger than this many days (filters throwaways). 0 = no minimum. Enables author enrichment automatically.", "default": 0 }, "mustBeVerified": { "title": "Only verified / Blue accounts", "type": "boolean", "description": "Only return leads from verified or X Premium (Blue) accounts. Enables author enrichment automatically.", "default": false }, "maxFollowingRatio": { "title": "Max following-to-followers ratio (bot heuristic)", "minimum": 0, "type": "integer", "description": "Drop accounts whose following/followers ratio exceeds this value (accounts that follow far more than follow back are often bots/spam). 0 = disabled. Enables author enrichment automatically.", "default": 0 }, "useAuthorInfluence": { "title": "Add author-influence bonus", "type": "boolean", "description": "Give higher-follower prospects a small ranking boost so influential leads rise to the top. Kept out of the core 0–100 score unless enabled; recorded as scoreBreakdown.authorInfluence.", "default": false }, "language": { "title": "Language filter", "type": "string", "description": "Only keep tweets in this language (ISO code, e.g. en, es, de). Leave blank for any language.", "default": "" }, "excludeRetweets": { "title": "Exclude retweets", "type": "boolean", "description": "Skip pure retweets — they rarely represent the retweeter's own intent.", "default": true }, "excludeReplies": { "title": "Exclude replies", "type": "boolean", "description": "Skip tweets that are replies (does not affect the dedicated replies source).", "default": false }, "includeSensitive": { "title": "Include sensitive tweets", "type": "boolean", "description": "Include tweets flagged as possibly sensitive. Off by default.", "default": false }, "minLikes": { "title": "Minimum likes", "minimum": 0, "type": "integer", "description": "Only keep tweets with at least this many likes. 0 = keep everything (recommended for fresh leads, which usually have few likes).", "default": 0 }, "minEngagement": { "title": "Minimum total engagement", "minimum": 0, "type": "integer", "description": "Only keep tweets whose combined likes + retweets + replies + quotes + views is at least this value. 0 = keep everything.", "default": 0 }, "authorAllowlist": { "title": "Author allowlist", "type": "array", "description": "If set, only return leads from these @handles.", "default": [], "items": { "type": "string" } }, "authorDenylist": { "title": "Author denylist", "type": "array", "description": "Never return leads from these @handles (e.g. your own accounts, known spammers).", "default": [], "items": { "type": "string" } }, "maxLeads": { "title": "Max leads", "minimum": 0, "type": "integer", "description": "Stop after emitting this many leads. 0 = unlimited (bounded by the per-source scan cap).", "default": 0 }, "sinceId": { "title": "Since tweet ID (incremental floor)", "type": "string", "description": "Optional tweet ID (snowflake). Only return tweets newer than this ID. Scheduled runs also persist a per-source cursor automatically, so each run only emits new leads.", "default": "" }, "perSourceScanCap": { "title": "Per-source scan cap", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Maximum tweets to examine per source entry (per query, hashtag, handle, list, community, or target). Keeps runs memory-light and predictable.", "default": 1000 }, "webhookUrl": { "title": "Webhook URL", "type": "string", "description": "Optional. Every lead is always saved to the run's dataset — this webhook is an ADDITIONAL real-time push. When set, each new lead is also POSTed here (CRM, Slack incoming webhook, Zapier, Make, Google Sheets). Delivery failures are ignored so the run keeps producing dataset output.", "default": "" }, "webhookFormat": { "title": "Webhook format", "enum": [ "json", "slack" ], "type": "string", "description": "json = full lead object; slack = Slack-friendly message with headline, score, intent, author, topics, and tweet link.", "default": "json" }, "includeRaw": { "title": "Include raw tweet JSON", "type": "boolean", "description": "Attach the full raw tweet object under the raw field (larger output).", "default": false }, "maxRetries": { "title": "Max retries (advanced)", "minimum": 0, "maximum": 20, "type": "integer", "description": "How many times to retry a transient upstream error (rate limit / 5xx) before giving up.", "default": 5 }, "retryBaseDelayMs": { "title": "Retry base delay ms (advanced)", "minimum": 0, "type": "integer", "description": "Base backoff delay in milliseconds; grows exponentially with each retry.", "default": 2000 }, "retryMaxDelayMs": { "title": "Retry max delay ms (advanced)", "minimum": 0, "type": "integer", "description": "Maximum backoff delay in milliseconds between retries.", "default": 30000 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```