# X (Twitter) Advanced Search Scraper & API (`arjun_code/x-twitter-advanced-search-scraper`) Actor

Run up to 25 advanced X/Twitter searches by keywords, hashtags, accounts, dates, media, and engagement. Export structured posts, authors, metrics, media, Cards, quotes, reposts, and X Articles—no login, cookies, API key, or proxy setup.

- **URL**: https://apify.com/arjun\_code/x-twitter-advanced-search-scraper.md
- **Developed by:** [Arjun AI](https://apify.com/arjun_code) (community)
- **Categories:** Social media, Lead generation
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.40 / 1,000 x post 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/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

Turn X advanced search into structured datasets for social listening, competitor research, lead discovery, and content analysis. Run up to 25 searches by keywords, phrases, hashtags, accounts, or native X operators, then narrow the results by date, language, post type, media, and engagement.

Export rich post and author data—including videos, Cards, reposts, quotes, and X Articles—without providing an X login, cookies, API key, or proxy configuration.

### What can this Actor do?

- Search by ordinary keywords or complete native X search expressions.
- Match an exact phrase or any of several words and phrases.
- Include or exclude hashtags, cashtags, and accounts.
- Find posts from, replying to, or mentioning specific X accounts.
- Choose Latest or Top results.
- Filter by language, UTC date range, post type, media type, and minimum engagement.
- Process up to 25 separate searches in one run.
- Follow X result pages automatically and remove duplicate post IDs within each search.
- Export JSON, CSV, Excel, XML, or RSS from the Apify Dataset.

### Common use cases

- Monitor public discussion around products, companies, industries, and events.
- Find posts from competitors, customers, journalists, creators, or researchers.
- Build market-research, media-monitoring, and social-listening datasets.
- Discover high-engagement posts with minimum likes, reposts, or replies.
- Collect image, video, link, quote-post, reply, or repost datasets.

### How to use

1. Add at least one search condition. The easiest option is **Search terms or X queries**.
2. Choose **Latest posts** or **Top posts**.
3. Set **Posts to save per search**. Enter `0` only when you want the Actor to continue until X stops providing result pages.
4. Optionally add account, date, language, post-type, media, or engagement filters.
5. Start the Actor and open the Dataset to preview or export the results.

#### Input example in Apify Console

[![Advanced X/Twitter search input configured in Apify Console](https://raw.githubusercontent.com/arjun-go-go/apify-actor-assets/main/x-twitter-advanced-search-scraper/x-twitter-advanced-search-input.png)](https://raw.githubusercontent.com/arjun-go-go/apify-actor-assets/main/x-twitter-advanced-search-scraper/x-twitter-advanced-search-input.png)

### Input

The Apify Console opens with a small ready-to-run example: `AI agents`, Latest results, 5 posts, and English. When a field is omitted through the API, the runtime default shown below applies instead.

| Field | Purpose | API default / Console prefill |
| --- | --- | --- |
| `searchQueries` | One keyword search or native X search expression per line. Every line runs independently. | Empty / `AI agents` |
| `exactPhrase` | Match one phrase in the same word order. Can start a search by itself. | Empty |
| `anyWords` | Match any one entered word or phrase using OR logic. | Empty |
| `hashtags` / `cashtags` | Match any entered hashtag or stock/crypto symbol. Either field can start a search. | Empty |
| `excludeWords` / `excludeHashtags` | Remove posts containing the entered terms. These refine another search. | Empty |
| `fromUsers` | Posts written by any entered account. Can start a search by itself. | Empty |
| `toUsers` | Replies to any entered account. Can start a search by itself. | Empty |
| `mentionUsers` | Posts mentioning any entered account. Can start a search by itself. | Empty |
| `excludeFromUsers` | Exclude posts written by the entered accounts. | Empty |
| `searchMode` | X's Latest or Top result order. | `Latest` |
| `maxPostsPerQuery` | Maximum saved posts for each search. Use `0` to follow all result pages available from X. | `100` / `5` |
| `language` | Limit results to a language classified by X. | Any language / English |
| `startDate` / `endDate` | Inclusive UTC calendar-date range. | Empty |
| `postType` | Any, original posts, replies, reposts, or quote posts. | Any |
| `mediaType` | Any content, any media, images, videos, or links. | Any |
| `minLikes` / `minRetweets` / `minReplies` | Minimum engagement thresholds applied by X search. | `0` |

Different filters use AND logic. Multiple entries inside an OR-style field such as `anyWords`, `hashtags`, or `fromUsers` can match any one value.

Example input:

```json
{
  "searchQueries": ["AI agents"],
  "searchMode": "Latest",
  "maxPostsPerQuery": 5,
  "language": "en"
}
```

### Output

Each successful Dataset item represents one public X post. Important field groups include:

[![Advanced X/Twitter search results in the Apify Dataset](https://raw.githubusercontent.com/arjun-go-go/apify-actor-assets/main/x-twitter-advanced-search-scraper/x-twitter-advanced-search-output.png)](https://raw.githubusercontent.com/arjun-go-go/apify-actor-assets/main/x-twitter-advanced-search-scraper/x-twitter-advanced-search-output.png)

| Group | Fields |
| --- | --- |
| Search context | `status`, `search_query`, `compiled_query`, `search_mode`, `result_position` |
| Post | `tweet_id`, `tweet_url`, `post_type`, `created_at`, `text`, `language` |
| Engagement | `reply_count`, `retweet_count`, `quote_count`, `like_count`, `view_count` |
| Author | `author_username`, `author_name`, `author_profile_url`, `author_followers_count`, verification fields |
| Relationships | `reply_to_name`, `retweeter`, `retweeted_post`, `quoted_post` |
| Rich content | `media`, `media_types`, `card`, `is_article`, `article_title` |

Representative output:

```json
{
  "status": "success",
  "search_query": "AI agents",
  "compiled_query": "AI agents lang:en",
  "search_mode": "Latest",
  "result_position": 3,
  "post_type": "original",
  "tweet_id": "2104794571817525630",
  "tweet_url": "https://x.com/aure79lien/status/2104794571817525630",
  "created_at": "2026-09-29T04:45:05Z",
  "text": "Nvidia says new tool can contain rogue AI agents in \"milliseconds\"\n\nNvidia is deploying a new tool that it says can be used to prevent and contain rogue and potentially dangerous AI agents 🤖\nhttps://t.co/0Y2SEHOnRE\n#AI",
  "author_username": "aure79lien",
  "author_name": "Aurelien Lallemant #IA 🔎 & #RSE 🌎",
  "author_profile_url": "https://x.com/aure79lien",
  "author_followers_count": 2670,
  "reply_count": 0,
  "retweet_count": 0,
  "quote_count": 0,
  "like_count": 0,
  "view_count": 2,
  "media_count": 0,
  "media_types": [],
  "is_article": false
}
```

Counts and text in live X data change over time. Optional fields can be `null`, empty, or absent when X does not provide them for a result.

#### Reposts, quotes, replies, Cards, and Articles

- A repost uses the reposting account in the top-level `author_*` fields, a compact identity in `retweeter`, and the original post under `retweeted_post`.
- A quote post contains the quoted post and its author under `quoted_post`.
- A reply contains X's reply target IDs and `reply_to_name` when the matching user is present in the response.
- Posts with an X Card can include its title, description, destination, image, and player information under `card`.
- X Articles expose their available Article metadata alongside the normal post fields.

### Empty results and query failures

Invalid settings do not crash the Actor. The Dataset receives an uncharged `invalid_input` row explaining which value to fix. A valid search with no public matches produces an uncharged `no_results` row.

Example from the **Status rows** view when a search has no matches:

```json
{
  "status": "no_results",
  "message": "No public posts matched this search. Try broader terms, fewer filters, a wider date range, or a different result order.",
  "search_query": "\"an unlikely exact phrase\"",
  "compiled_query": "\"an unlikely exact phrase\" lang:en",
  "search_mode": "Latest"
}
```

When a run contains several searches, one failed search does not stop the remaining searches. A query that fails before saving a post produces `request_failed`; a later-page failure produces `partial` with `results_saved`. Already saved results stay in the Dataset.

### Pricing

This Actor uses pay-per-event pricing. It charges a small start event based on allocated memory and one `post-result` event for every successfully saved post.

| Event | Free | Bronze | Silver | Gold / Platinum / Diamond |
| --- | ---: | ---: | ---: | ---: |
| Actor start, per 1 GB of allocated memory; minimum one event | $0.00005 | $0.00005 | $0.00005 | $0.00005 |
| Successfully saved X post (`post-result`) | $0.00075 | $0.00060 | $0.00050 | $0.00040 |

At the Free-tier result price, a run using the default 1 GB memory costs approximately `$0.00380` for 5 posts, `$0.07505` for 100 posts, or `$0.75005` for 1,000 posts. A run that returns no posts costs only the `$0.00005` start event.

`invalid_input`, `no_results`, `request_failed`, and `partial` status rows do not trigger a `post-result` charge. Duplicate post IDs returned on different pages of the same search are removed before charging. The same post can be saved and charged once for each separate query that returns it because every result keeps its query attribution.

Use `maxPostsPerQuery` and Apify's **Maximum cost per run** setting to control spending. The Actor's **Pricing** tab is authoritative if prices change.

### Run with the Apify API

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/arjun_code~x-twitter-advanced-search-scraper/runs" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "searchQueries": ["AI agents"],
    "searchMode": "Latest",
    "maxPostsPerQuery": 25,
    "language": "en"
  }'
```

The run response contains `defaultDatasetId`. Use the Dataset API to retrieve the saved items. You can also start runs with the Apify Python or JavaScript client, schedule recurring searches, connect webhooks, or send Dataset results to other integrations.

### Related Actors

- [X (Twitter) People Search Scraper](https://apify.com/arjun_code/x-twitter-people-search-scraper) — find public accounts by keyword.
- [X (Twitter) Media Downloader](https://apify.com/arjun_code/x-twitter-media-downloader) — extract post details and download media.
- [X (Twitter) Replies Scraper](https://apify.com/arjun_code/x-twitter-replies-scraper) — collect visible replies and thread context.
- [X (Twitter) Retweeters Scraper](https://apify.com/arjun_code/x-twitter-retweeters-scraper) — collect reposting and quote-post accounts.
- [X (Twitter) Trends Scraper](https://apify.com/arjun_code/x-twitter-trends-scraper) — collect current trends by location.

### FAQ

#### Do I need an X account, cookies, or an API key?

No. The Actor handles X access and proxy routing internally. You only provide the search conditions.

#### Why did I receive fewer posts than requested?

`maxPostsPerQuery` is an upper limit. X may expose fewer matching posts, stop returning result pages, or return duplicates that the Actor removes within the query.

#### What does `0 = all` mean?

Setting `maxPostsPerQuery` to `0` tells the Actor to keep following result pages until X stops providing another usable page. It does not guarantee every historical post because availability is controlled by X. More pages can also increase run time and cost.

#### Are duplicate posts charged more than once?

Not within the same search: duplicate post IDs are removed before storage and charging. If the same post matches two separate queries, it can appear and be charged once under each query so the search attribution remains accurate.

#### What happens when one query fails in a batch?

The Actor writes an uncharged `request_failed` or `partial` status row for that query and continues with the remaining queries. Results already saved from completed pages stay available.

#### What does an empty search cost?

An empty result writes an uncharged `no_results` row. With the default 1 GB memory, the run still has the `$0.00005` Actor start charge.

### Limitations

- Result ranking, availability, and pagination are controlled by X and can change between runs.
- Deleted, private, withheld, restricted, or otherwise unavailable posts may not appear.
- `maxPostsPerQuery` is an upper limit, not a guaranteed result count.
- Very selective searches may expose fewer results than requested.
- X can change its web responses or temporarily limit access.

Use the data responsibly and comply with applicable laws, privacy requirements, X's terms, and Apify's terms. This independent Actor is not affiliated with, endorsed by, or sponsored by X Corp.

### Support

If a run fails or the output changes, open an issue on the Actor page and include the Apify run ID, input, and expected behavior. Do not include passwords, cookies, tokens, or other secrets.

# Actor input Schema

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

Enter one keyword search or complete X search expression per line. Each line runs as a separate search. Leave this empty when starting with an exact phrase, hashtags, cashtags, or an account field. Up to 25 unique searches are allowed per run.

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

Match one exact phrase in the same word order. This field can start a search by itself. Example: artificial intelligence.

## `anyWords` (type: `array`):

Enter one word or phrase per line. Posts may match any one of the values (OR). Multi-word values are matched as phrases. Example: ChatGPT and Claude.

## `hashtags` (type: `array`):

Enter hashtags with or without #. Posts may match any one of the hashtags (OR). This field can start a search by itself. Example: AI and MachineLearning.

## `cashtags` (type: `array`):

Find posts mentioning any of these stock or crypto symbols. Enter symbols with or without $. Multiple symbols are matched with OR. This field can start a search by itself. Example: AAPL and BTC.

## `excludeWords` (type: `array`):

Enter one word or phrase per line. Posts containing any entered value are excluded. This field refines another search and cannot start one by itself. Example: giveaway and promotion.

## `excludeHashtags` (type: `array`):

Exclude posts containing any of these hashtags. Enter hashtags with or without #. This field refines another search and cannot start one by itself. Example: sponsored and giveaway.

## `fromUsers` (type: `array`):

Find posts written by any of these X accounts. Example: OpenAI.

## `toUsers` (type: `array`):

Find posts sent as replies to any of these X accounts. Example: OpenAI.

## `mentionUsers` (type: `array`):

Find posts that mention any of these X accounts. Example: OpenAI.

## `excludeFromUsers` (type: `array`):

Exclude posts written by these X accounts. Enter usernames with or without @. This field refines another search and cannot start one by itself.

## `searchMode` (type: `string`):

Latest returns recent posts. Top follows X's relevance ranking.

## `maxPostsPerQuery` (type: `integer`):

Maximum number of unique posts to save for each separate search. Keep 100 for a typical export, or enter 0 to continue until X provides no further result page.

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

Only return posts X classifies in the selected language. Detection may be less exact for very short or mixed-language posts.

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

Include posts published on or after this UTC date.

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

Include the entire selected UTC date. The Actor converts it to X's exclusive until boundary automatically.

## `postType` (type: `string`):

Choose whether to return all posts, original posts, replies, reposts, or quote posts.

## `mediaType` (type: `string`):

Only return posts containing the selected content type.

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

Only return posts with at least this many likes.

## `minRetweets` (type: `integer`):

Only return posts with at least this many reposts.

## `minReplies` (type: `integer`):

Only return posts with at least this many replies.

## Actor input object example

```json
{
  "searchQueries": [
    "AI agents"
  ],
  "anyWords": [],
  "hashtags": [],
  "cashtags": [],
  "excludeWords": [],
  "excludeHashtags": [],
  "fromUsers": [],
  "toUsers": [],
  "mentionUsers": [],
  "excludeFromUsers": [],
  "searchMode": "Latest",
  "maxPostsPerQuery": 5,
  "language": "en",
  "postType": "any",
  "mediaType": "any",
  "minLikes": 0,
  "minRetweets": 0,
  "minReplies": 0
}
```

# Actor output Schema

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

Structured X posts returned by Advanced Search.

# 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 = {
    "searchQueries": [
        "AI agents"
    ],
    "maxPostsPerQuery": 5,
    "language": "en"
};

// Run the Actor and wait for it to finish
const run = await client.actor("arjun_code/x-twitter-advanced-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 = {
    "searchQueries": ["AI agents"],
    "maxPostsPerQuery": 5,
    "language": "en",
}

# Run the Actor and wait for it to finish
run = client.actor("arjun_code/x-twitter-advanced-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 '{
  "searchQueries": [
    "AI agents"
  ],
  "maxPostsPerQuery": 5,
  "language": "en"
}' |
apify call arjun_code/x-twitter-advanced-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,arjun_code/x-twitter-advanced-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/fvNsT0xGeIPiCoPf0/builds/nVYjgI9E4vz3O7gim/openapi.json