# X Twitter Tweet Scraper (`simoit/x-twitter-search-tweets-scrapper`) Actor

Scrape X / Twitter tweets by keyword, URL, conversation ID, author, date, engagement, and media filters. Export structured tweet data for monitoring, research, and automation.

- **URL**: https://apify.com/simoit/x-twitter-search-tweets-scrapper.md
- **Developed by:** [simoit](https://apify.com/simoit) (community)
- **Categories:** Social media, Developer tools, Automation
- **Stats:** 44 total users, 7 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.15 / 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.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## X Twitter Tweet Scraper

![SIMO IT logo](https://simoit.tech/favicon.ico)

Scrape X/Twitter tweets by keyword, advanced search query, search URL, author, date range, engagement threshold, media type, verified-account filter, or collect replies for specific tweet IDs. The Actor returns structured tweet records for brand monitoring, campaign research, market analysis, reporting, and automation workflows.

### What this Actor does

- finds tweets by simple keyword phrases or full X/Twitter advanced search queries
- collects tweets from X/Twitter search URLs
- collects replies for specific posts with `tweetIds` or tweet URLs
- filters by author, reply target, mentioned users, date range, language, hashtags, and exact phrases
- filters by minimum likes, retweets, replies, image posts, video posts, or verified users
- supports `latest` and `top` sorting
- paginates results and lets you cap output with `maxItems`

### Common use cases

- monitor brand, product, executive, or competitor mentions
- collect tweets for campaign hashtags and launches
- track high-engagement posts in a market or topic
- build social listening and sentiment-analysis datasets
- collect replies and reactions from a specific post
- export tweet datasets for BI, LLM enrichment, classification, or alerts

### Output

The dataset contains matching tweet records with tweet text, URL, timestamp, author details, engagement counters, hashtags, links, media, conversation IDs, and other fields when available.

#### Example output

```json
{
  "id": 1891042203344556600,
  "id_str": "1891042203344556600",
  "url": "https://x.com/openai/status/1891042203344556600",
  "date": "2026-02-20T08:30:00+00:00",
  "lang": "en",
  "rawContent": "We shipped a new update today.",
  "replyCount": 42,
  "retweetCount": 310,
  "likeCount": 1520,
  "quoteCount": 18,
  "bookmarkedCount": 0,
  "conversationId": 1891042203344556600,
  "conversationIdStr": "1891042203344556600",
  "hashtags": ["AI", "OpenAI"],
  "cashtags": [],
  "mentionedUsers": [],
  "links": [],
  "viewCount": 120034,
  "user": {
    "id": 4398626122,
    "id_str": "4398626122",
    "url": "https://x.com/openai",
    "username": "openai",
    "displayname": "OpenAI",
    "followersCount": 5500000,
    "friendsCount": 12,
    "verified": true
  },
  "media": {
    "photos": [],
    "videos": [],
    "animated": []
  },
  "_type": "snscrape.modules.twitter.Tweet"
}
```

### How to use

1. Open the Actor on Apify.
2. Choose `Search tweets` for keyword/query collection or `Replies for specific tweets` for tweet reply collection.
3. For search, enter `searchTerms` for a simple search, `rawQuery` for advanced X/Twitter search syntax, or `startUrls` for search URLs. For replies, enter `tweetIds` or `tweetUrls`.
4. Add optional filters such as author, date range, engagement thresholds, language, hashtags, media type, or verified users for search runs.
5. Set `maxItems` and `limit` to control output size. The Actor automatically increases the effective page count when `maxItems` needs more pages than `maxPages`.
6. Run the Actor and use the dataset from Apify exports, API, integrations, or scheduled tasks.

No scraping infrastructure setup is required.

Need a custom plan, custom limits, or a tailored data workflow? Contact `contact@simoit.tech`.

### Input

- `inputTargetType` (string, optional, default: `search`): `search` for keyword/query collection or `tweet_replies` for replies to specific tweets.
- `searchTerms` (string, optional): Main search phrase (or multiple comma/newline terms). Use this or `rawQuery`; avoid duplicating the same query in both.
- `rawQuery` (string, optional): Full X/Twitter advanced search string used as-is. Can be used on its own.
- `conversationIds` (string, optional): Advanced search compatibility field. Internally converted to `conversation_id:<id>` search queries. For real tweet replies, use `tweetIds` with `inputTargetType: "tweet_replies"`.
- `tweetIds` (string, optional): Tweet IDs or tweet URLs (comma/newline). Used with `inputTargetType: "tweet_replies"` to call the tweet replies endpoint.
- `tweetUrls` (string, optional): X/Twitter status URLs (comma/newline). Used with `inputTargetType: "tweet_replies"`.
- `startUrls` (string, optional): X/Twitter search URLs (`x.com` / `twitter.com`), comma-separated or new lines.
- `sort` (string, optional, default: `latest`): `latest` or `top`.
- `fromUsers` (string, optional): Comma-separated usernames for `from:` filter.
- `toUsers` (string, optional): Comma-separated usernames for `to:` filter.
- `mentioningUsers` (string, optional): Comma-separated usernames to be mentioned.
- `startDate` (string, optional): Start date. Accepts `YYYY-MM-DD`, `D/M/YYYY`, or `M/D/YYYY`.
- `endDate` (string, optional): End date. Accepts `YYYY-MM-DD`, `D/M/YYYY`, or `M/D/YYYY`.
- `minimumLikes` (integer, optional): Minimum likes threshold.
- `minimumRetweets` (integer, optional): Minimum retweets threshold.
- `minimumReplies` (integer, optional): Minimum replies threshold.
- `onlyImage` (boolean, optional, default: `false`): Return only image tweets.
- `onlyVideo` (boolean, optional, default: `false`): Return only video tweets.
- `onlyVerifiedUsers` (boolean, optional, default: `false`): Return only verified-account tweets.
- `includeReplies` (boolean, optional, default: `true`): Include replies.
- `includeRetweets` (boolean, optional, default: `true`): Include retweets.
- `withinRadius` (string, optional): Geo filter, format: `lat,lon,radius` (for example `52.23,21.01,10km`).
- `page` (integer, optional, default: `1`): Starting page number.
- `limit` (integer, optional, default: `20`, max: `100`): Records per page.
- `maxPages` (integer, optional, default: `1`): Minimum number of pages to fetch. If `maxItems` requires more pages, the Actor automatically increases the effective page count.
- `maxItems` (integer, optional): Hard cap for total output records.

Legacy compatibility:

- The Actor still accepts aliases such as `author`, `inReplyTo`, `mentioning`, `start`, `end`, `since`, `until`, and `minimumFavorites`.
- Those aliases are supported for backward compatibility, but they are intentionally not exposed in the public input UI.

#### Filters and pagination

- search target: `rawQuery`, `searchTerms`, `conversationIds`, `startUrls`
- tweet replies target: `inputTargetType: "tweet_replies"` with `tweetIds` or `tweetUrls`
- advanced query helpers: `rawQuery`, `exactPhrase`, `excludeTerms`, `hashtags`, `language`
- author/mention filters: `fromUsers`/`author`, `toUsers`/`inReplyTo`, `mentioningUsers`/`mentioning`
- date filters: `startDate`/`start`/`since`, `endDate`/`end`/`until`
  accepted formats: `YYYY-MM-DD`, `D/M/YYYY`, and `M/D/YYYY`
- quality filters: `minimumLikes`/`minimumFavorites`, `minimumRetweets`, `minimumReplies`
- media/account filters: `onlyImage`, `onlyVideo`, `onlyVerifiedUsers`
- inclusion switches: `includeReplies`, `includeRetweets`
- geo filter: `withinRadius`
- page controls: `page`, `limit`, `maxPages`, `maxItems`

#### Example input

```json
{
  "searchTerms": "open source ai agents",
  "exactPhrase": "agent memory",
  "excludeTerms": "spam,fake",
  "hashtags": "ai,agents",
  "language": "en",
  "sort": "latest",
  "fromUsers": "openai,apify",
  "startDate": "2026-02-01",
  "endDate": "2026-02-20",
  "minimumLikes": 10,
  "includeReplies": true,
  "onlyVideo": false,
  "maxItems": 50
}
```

Collect replies for one post:

```json
{
  "inputTargetType": "tweet_replies",
  "tweetIds": "2070555273467687257",
  "page": 1,
  "limit": 100,
  "maxItems": 300
}
```

### Suggested Apify task presets

These are reusable task ideas you can create from this Actor. They are suggested presets, not separate Actors.

| Task | Input preset | Expected output |
| --- | --- | --- |
| Brand monitoring by keyword | `searchTerms`, `language`, `maxItems`, optional `minimumLikes` | Recent tweets mentioning a brand, product, or executive |
| Campaign hashtag analysis | `hashtags`, `startDate`, `endDate`, `sort: latest` | Tweets from a campaign window with engagement counters |
| Competitor mention tracking | `searchTerms`, `fromUsers` or `mentioningUsers`, `maxItems` | Mentions and conversations around competitor accounts |
| Tweet replies monitoring | `inputTargetType: tweet_replies`, `tweetIds`, `maxItems` | Replies for one or more specific posts |
| High-engagement tweet discovery | `searchTerms`, `sort: top`, `minimumLikes`, `minimumRetweets` | Strong-performing tweets for a topic or market |
| Video tweet collection | `searchTerms`, `onlyVideo: true`, `maxItems` | Video posts matching a query |

### Related Actors

- Need tweets from one specific profile instead of broad search results? Use [Profile Scraper](https://apify.com/simoit/x-twitter-profile-scrapper).
- Need account metadata, followers, or following instead of tweets? Use [User Scraper](https://apify.com/simoit/x-twitter-user-scrapper).
- Need posts from a curated X list? Use [List Scraper](https://apify.com/simoit/x-twitter-list-scraper).
- Need preset or country-level trend feeds before drilling into tweets? Use [Trends Scraper](https://apify.com/simoit/x-twitter-preset-trends-scrapper) or [Global Trending Scraper](https://apify.com/simoit/x-twitter-trends-scrapper).

### About SIMO IT

SIMO IT delivers practical scraping and automation tools that help teams extract value from social platforms faster.

### FAQ

**Is this an official X/Twitter API?**\
No. This is an Apify Actor for collecting X/Twitter data. It is not an official X/Twitter API, and you are responsible for using the data in a compliant way.

**Can I export tweets as JSON or CSV?**\
Yes. Results are stored in the Apify dataset, so you can use Apify exports such as JSON, CSV, Excel, XML, RSS, or HTML table where supported by your Apify workflow.

**Can I run this Actor by API, schedule it, or integrate it with other tools?**\
Yes. You can run it manually, call it through the Apify API, create reusable Apify tasks, schedule recurring runs, and connect dataset output to Apify integrations or your own workflows.

**Which input should I use first?**\
Use `searchTerms` for simple keyword searches, `rawQuery` for advanced X/Twitter search syntax, and `startUrls` when you already have search URLs. Use `inputTargetType: "tweet_replies"` with `tweetIds` or `tweetUrls` when you want replies for a specific post.

**Can I collect more than one page of results?**\
Yes. Use `page`, `limit`, and `maxPages` for pagination. Use `maxItems` as the simplest hard cap for total dataset records. If `maxItems` needs more pages than `maxPages`, the Actor automatically increases the effective page count.

**How do I control output size and cost?**\
Use narrower queries, date ranges, author filters, engagement filters, `limit`, `maxPages`, and `maxItems`. For most runs, start with `maxItems` and increase it only when the output quality is confirmed.

**Can I narrow results to high-quality tweets only?**\
Yes. Use engagement filters like `minimumLikes`, `minimumRetweets`, and `minimumReplies`, or use `sort: top`.

**Can I include or exclude replies and retweets?**\
Yes. Use `includeReplies` and `includeRetweets`.

**What are the practical limitations?**\
Results depend on X/Twitter availability, the query, selected filters, date range, and pagination settings. Very broad or very old searches can return fewer useful records than focused queries.

**Does this Actor support legacy alias fields?**\
Yes. It supports aliases like `author`, `inReplyTo`, `mentioning`, `start`/`end`, `since`/`until`, and `minimumFavorites`.

# Actor input Schema

## `inputTargetType` (type: `string`):

Choose Search tweets for keyword/query collection, or Replies for specific tweets to collect replies with the TweetDetail endpoint.

## `searchTerms` (type: `string`):

Search phrase or multiple queries (comma/newline). Use this or Raw query. Do not duplicate the same logic in both fields.

## `rawQuery` (type: `string`):

Advanced X query string used as-is. Can be used on its own. If provided together with Search terms, it overrides the composed search query.

## `exactPhrase` (type: `string`):

Exact phrase emitted as a quoted Twitter search phrase.

## `excludeTerms` (type: `string`):

CSV terms to exclude, emitted as -term operators.

## `hashtags` (type: `string`):

CSV hashtags, emitted as #tag operators.

## `language` (type: `string`):

Language filter, emitted as lang:xx.

## `conversationIds` (type: `string`):

Advanced search compatibility field. Converted to conversation\_id:<id> search queries. For real tweet replies, use Tweet IDs with Replies for specific tweets mode.

## `tweetIds` (type: `string`):

Tweet IDs or tweet URLs, comma-separated or new lines. The Actor calls /tweets/{id}/replies for each ID.

## `tweetUrls` (type: `string`):

Optional x.com/twitter.com status URLs, comma-separated or new lines. Used only for Replies for specific tweets mode.

## `startUrls` (type: `string`):

Optional X/Twitter search URLs (comma-separated or new lines). Search URLs infer query.

## `sort` (type: `string`):

Result sorting mode.

## `fromUsers` (type: `string`):

CSV usernames for from: filter.

## `toUsers` (type: `string`):

CSV usernames for to: filter.

## `mentioningUsers` (type: `string`):

CSV usernames that should be mentioned.

## `startDate` (type: `string`):

Start date. Accepts YYYY-MM-DD, D/M/YYYY, or M/D/YYYY and is normalized automatically.

## `endDate` (type: `string`):

End date. Accepts YYYY-MM-DD, D/M/YYYY, or M/D/YYYY and is normalized automatically.

## `minimumLikes` (type: `integer`):

Minimum likes count.

## `minimumRetweets` (type: `integer`):

Minimum retweets count.

## `minimumReplies` (type: `integer`):

Minimum replies count.

## `onlyImage` (type: `boolean`):

Only tweets with images.

## `onlyVideo` (type: `boolean`):

Only tweets with videos.

## `onlyVerifiedUsers` (type: `boolean`):

Only tweets from verified accounts.

## `includeReplies` (type: `boolean`):

Include reply tweets.

## `includeRetweets` (type: `boolean`):

Include retweets.

## `withinRadius` (type: `string`):

Geocode in lat,lon,radius format (for example 52.23,21.01,10km).

## `page` (type: `integer`):

Starting page number.

## `limit` (type: `integer`):

Items per page.

## `maxPages` (type: `integer`):

Minimum number of pages to fetch. If Max items needs more pages, the Actor automatically increases the effective page count.

## `maxItems` (type: `integer`):

Maximum number of output items to push.

## Actor input object example

```json
{
  "inputTargetType": "search",
  "searchTerms": "openai",
  "sort": "latest",
  "onlyImage": false,
  "onlyVideo": false,
  "onlyVerifiedUsers": false,
  "includeReplies": true,
  "includeRetweets": true,
  "page": 1,
  "limit": 10,
  "maxPages": 1,
  "maxItems": 10
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `runReport` (type: `string`):

No description

## `userErrorReport` (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 = {
    "inputTargetType": "search",
    "searchTerms": "openai",
    "limit": 10,
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("simoit/x-twitter-search-tweets-scrapper").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 = {
    "inputTargetType": "search",
    "searchTerms": "openai",
    "limit": 10,
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("simoit/x-twitter-search-tweets-scrapper").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 '{
  "inputTargetType": "search",
  "searchTerms": "openai",
  "limit": 10,
  "maxItems": 10
}' |
apify call simoit/x-twitter-search-tweets-scrapper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=simoit/x-twitter-search-tweets-scrapper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/zJGj64wsNBGP7tUW1/builds/tbRH3gc7aSHidLyo6/openapi.json