# Search X By Keywords (`watcher.data/search-x-by-keywords`) Actor

Fast and reliable scraper for searching tweets and users on X (Twitter). Supports multiple output formats (JSON, CSV, Excel), advanced filtering options, and real-time data extraction. Perfect for social media monitoring, research, and business intelligence.

- **URL**: https://apify.com/watcher.data/search-x-by-keywords.md
- **Developed by:** [Giichi Arai](https://apify.com/watcher.data) (community)
- **Categories:** Social media, Integrations, Automation
- **Stats:** 1,156 total users, 124 monthly users, 100.0% runs succeeded, 4 bookmarks
- **User rating**: 4.00 out of 5 stars

## Pricing

$3.00 / 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/actors/running/actors-in-store.md#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

## Search X (Twitter) by Keywords – Fast API-powered Scraper

This Apify Actor allows you to search for tweets and users on X (Twitter) using a fast API. It's designed to be efficient, user-friendly, and supports multiple output formats.

### Features

- 🔍 **Dual Search Types**: Search for tweets or users
- 🎯 **Multiple Keywords**: Support for multiple keywords with separate API calls for maximum coverage
- ⚡ **Fast API Integration**: Uses optimized API endpoints for quick results
- 📊 **Multiple Output Formats**: JSON, CSV, and Excel (XLSX)
- 🔧 **Flexible Sorting**: Latest, popular, or mixed result ordering
- 🔄 **Retry Logic**: Built-in retry mechanism with exponential backoff
- 📈 **Pagination Support**: Handles large result sets efficiently
- 🛡️ **Proxy Support**: Built-in proxy configuration for reliability

### Input Configuration

#### Required Fields

- **Search Type**: Choose between searching for tweets or users
- **Keywords**: At least one keyword is required
- **Max Items Per Keyword**: Number of results per keyword (1-200)

#### Search Keywords Options

- **Keywords**: Array of keywords to search for (hashtags, usernames, phrases, etc.) - each will be searched separately via individual API calls
- **Max Items Per Keyword**: Number of results to retrieve for each individual keyword (final results will be deduplicated across keywords)

#### Optional Fields

##### Tweet Search Options

- **Include Replies**: Include reply tweets in results (client-side filtering)
- **Include Retweets**: Include retweets in results (client-side filtering)
- **Sort By**: Sort results by latest, popular, or mixed

##### Filtering Options

- **Sorting**: Sort results by latest, popular, or mixed

##### Output Options

- **Output Format**: Choose JSON, CSV, or Excel format
- **Proxy Configuration**: Configure proxy settings

### Usage Examples

#### Search for Tweets about AI (Multiple Keywords)

```json
{
  "searchType": "tweets",
  "keywords": ["#AI", "MachineLearning", "ArtificialIntelligence", "DeepLearning", "NeuralNetworks"],
  "maxItemsPerKeyword": 50,
  "sortBy": "latest",
  "outputFormat": "json"
}
```

**Note**: This will make 5 separate API calls (one for each keyword), getting 50 tweets per keyword, then deduplicate the combined results.

#### Search for Tech Users

```json
{
  "searchType": "users",
  "keywords": ["tech entrepreneur", "startup", "CEO", "founder", "developer"],
  "maxItemsPerKeyword": 20,
  "outputFormat": "csv"
}
```

**Note**: This will make 5 separate API calls (one for each keyword), getting 20 users per keyword, then deduplicate the combined results.

#### Search for Cryptocurrency Tweets

```json
{
  "searchType": "tweets",
  "keywords": ["cryptocurrency", "Bitcoin", "Ethereum", "blockchain", "DeFi"],
  "maxItemsPerKeyword": 50,
  "sortBy": "popular",
  "outputFormat": "excel"
}
```

**Note**: This will make 5 separate searches (one for each keyword), getting 50 tweets per keyword, then deduplicate the combined results.

### Output Schema

#### Tweet Data

Each tweet result includes:

- `id`: Unique tweet identifier

- `text`: Tweet content

- `author`: Username of the author

- `author_name`: Display name of the author

- `created_at`: Tweet creation timestamp

- `retweet_count`: Number of retweets

- `like_count`: Number of likes

- `reply_count`: Number of replies

- `quote_count`: Number of quotes

- `is_retweet`: Whether this is a retweet

- `is_reply`: Whether this is a reply

- `hashtags`: Array of hashtags used

- `mentions`: Array of mentioned users

- `urls`: Array of URLs in the tweet

- `url`: Direct link to the tweet

#### User Data

Each user result includes:

- `id`: Unique user identifier
- `username`: User's handle (@username)
- `name`: Display name
- `description`: User bio/description
- `followers_count`: Number of followers
- `following_count`: Number of accounts following
- `tweets_count`: Total number of tweets
- `created_at`: Account creation date
- `verified`: Verification status
- `location`: User's location
- `profile_image_url`: Profile picture URL
- `profile_url`: Profile page URL

### Performance & Limitations

- **Speed**: Execution time depends on number of keywords (1 second delay between API calls)
- **Multiple API Calls**: Each keyword triggers a separate API call for maximum results
- **Rate Limiting**: Built-in retry logic and delays between requests
- **Data Freshness**: Results are fetched in real-time from the API
- **Deduplication**: Automatic removal of duplicate tweets/users across keyword results
- **Per-Keyword Control**: Precise control over results per keyword (up to 200 per keyword)

### Error Handling

The Actor includes comprehensive error handling:

- **API Failures**: Automatic retry with exponential backoff
- **Invalid Queries**: Clear error messages for malformed inputs
- **Network Issues**: Graceful handling of connection problems
- **Data Format Errors**: Robust parsing of API responses

### Technical Details

- **Runtime**: Python 3.11
- **Framework**: Apify SDK for Python
- **API Integration**: HTTP requests with session management
- **Data Processing**: Pandas for CSV/Excel export
- **Logging**: Comprehensive logging for debugging

### Support

For issues or questions:

1. Check the Actor logs for detailed error information
2. Ensure your search keywords are properly formatted
3. Verify API connectivity and quotas
4. Contact support with specific error messages

### Version History

- **v1.0.0**: Initial release with tweet and user search functionality
- Support for multiple output formats
- Built-in retry logic and error handling
- Comprehensive input validation

***

*This Actor is designed for legitimate research, marketing, and business intelligence purposes. Please comply with X (Twitter) Terms of Service and applicable laws.*

# Actor input Schema

## `searchType` (type: `string`):

Choose what to search for

## `keywords` (type: `array`):

Enter keywords to search for (hashtags, usernames, phrases, etc.). Each keyword will be searched separately via individual API calls.

## `maxItemsPerKeyword` (type: `integer`):

Maximum number of items to retrieve for each individual keyword (after deduplication across keywords)

## `sortBy` (type: `string`):

How to sort the results (for tweets only)

## `outputFormat` (type: `string`):

Choose the output format for downloaded data

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

Proxy settings for requests

## Actor input object example

```json
{
  "searchType": "tweets",
  "keywords": [
    "#AI",
    "Python"
  ],
  "maxItemsPerKeyword": 50,
  "sortBy": "latest",
  "outputFormat": "json",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# 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 = {
    "keywords": [
        "#AI",
        "Python"
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("watcher.data/search-x-by-keywords").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 = {
    "keywords": [
        "#AI",
        "Python",
    ],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("watcher.data/search-x-by-keywords").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 '{
  "keywords": [
    "#AI",
    "Python"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call watcher.data/search-x-by-keywords --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,watcher.data/search-x-by-keywords"
        }
    }
}

```

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/8CiMefkv2yLlD7vYl/builds/1gKGcsUDsD25HUHmc/openapi.json