# X.com Twitter API Scraper (`xtdata/twitter-x-scraper`) Actor

Scrape Twitter (X) data efficiently with this powerful Apify Actor. Real-time, authentic data. No pre-built databases. Extract tweets, user profiles, and more using keywords, hashtags, URLs, and advanced search filters. Fast, reliable, and cost-effective. #TwitterScraper

- **URL**: https://apify.com/xtdata/twitter-x-scraper.md
- **Developed by:** [xtdata](https://apify.com/xtdata) (community)
- **Categories:** Social media, Lead generation
- **Stats:** 2,828 total users, 152 monthly users, 53.6% runs succeeded, 47 bookmarks
- **User rating**: 3.67 out of 5 stars

## Pricing

from $0.25 / 1,000 each tweet. cheaper for higher plans

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.com Twitter API Scraper - Fast and Efficient Tweet Extraction

This Actor provides a powerful and efficient way to scrape data from Twitter (now X). It allows you to extract tweets
based on various criteria, making it ideal for researchers, entrepreneurs, data analysts, and anyone needing to gather
Twitter data for analysis. It's designed for fetching *historical* data, not real-time monitoring.

### Key Features

- **Multiple Input Methods:** Get the data you need, how you need it:
  - **Start URLs:**  Provide direct URLs for tweets, user profiles, search results, or lists.
  - **Search Terms:** Use keywords and advanced search operators (
    see [Advanced Search Guide](https://github.com/igorbrigadir/twitter-advanced-search)).
  - **Twitter Handles:**  Extract tweets from specific users.

- **Powerful Filtering:** Refine your results with precise filtering:
  - **Maximum Items:** Control the number of tweets you retrieve.
  - **Sorting:** Get results sorted by "Top" or "Latest".
  - **Language:** Filter by language using [ISO 639-1 codes](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (a
    full list of supported languages is available in the Actor's input settings).
  - **User Verification:**  Target tweets from verified users or Twitter Blue subscribers.
  - **Media Type:**  Extract only tweets containing images, videos, or quotes.
  - **Date Range:**  Specify a start and end date to retrieve tweets within a specific timeframe.

- **Advanced Options:**
  - **Include Search Terms:**  Add a field to each tweet showing the search term that matched it.
  - **Custom Map Function:**  Transform the output data using a custom JavaScript function (for data shaping, *not*
    filtering).
  - **Query Wizard**: Easily create complex queries. (Available Tweet X.com Scraper)

- **Lightning-Fast Performance:**
  - Scrape tweets with incredible speed. (Tweet X.com Scraper: advertised as 30-80 tweets per second)

- **Cost-Effective:**
  - Competitive pricing. Tweet X.com Scraper: $0.50 per 1,000 tweets.

\*\*Tutorial from development
team: [Tutorial: Scrape Twitter Data with Apify's Tweet X.com Scraper](https://novidevelop.github.io/twitter/x/scraper/data-extraction/tutorial/2025/03/08/tutorial-scrape-twitter-data-apify-tweet-xcom-scraper.html)
\*\*

### Use Cases

- **Market Research:** Analyze trends, sentiment, and brand perception.
- **Academic Research:** Gather data for social media studies, political science research, and more.
- **Competitive Analysis:** Track competitors' activities and public engagement.
- **Data Journalism:**  Uncover insights and patterns within Twitter data.
- **Historical Data Analysis:** Explore past tweets for specific events or periods.

### Quick Start Examples

Here are some example input configurations to get you started quickly:

**1. Fetching Tweets from a Specific Profile (e.g., NASA) over Several Time Periods:**

This example fetches English tweets from the NASA profile (@NASA) in multiple date ranges, sorted by latest.

```json
{
    "includeSearchTerms": false,
    "onlyImage": false,
    "onlyQuote": false,
    "onlyTwitterBlue": false,
    "onlyVerifiedUsers": false,
    "onlyVideo": false,
    "searchTerms": [
        "from:elonmusk AI since:2023-01-01 until:2023-03-01",
        "from:elonmusk AI since:2023-03-01 until:2023-05-01",
        "from:elonmusk AI since:2023-05-01 until:2023-07-01",
        "from:elonmusk AI since:2023-07-01 until:2023-09-01",
        "from:elonmusk AI since:2023-09-01 until:2023-12-01"
    ],
    "sort": "Top",
    "tweetLanguage": "en"
}
```

**2. Fetching Replies to a Specific Tweet with a Hashtag:**

This example retrieves replies (in English, sorted by top) to a specific tweet (replace `tweet_id_here` with the
actual
tweet ID) that include a specific hashtag (replace `hashtag_here`).

```JSON
{
    "includeSearchTerms": false,
    "onlyImage": false,
    "onlyQuote": false,
    "onlyTwitterBlue": false,
    "onlyVerifiedUsers": false,
    "onlyVideo": false,
    "searchTerms": [
        "conversation_id:tweet_id_here #hashtag_here"
    ],
    "sort": "Latest",
    "tweetLanguage": "en"
}
```

**Explanation of Key Input Fields:**

- `searchTerms`: This is the core of your query. You can use advanced search operators (as shown in the NASA example) or
  a conversation ID combined with a hashtag. Refer to the Advanced Search Guide for all the possibilities.
- `sort`: Choose "Latest" for chronological order or "Top" for the most relevant tweets.
- `tweetLanguage`: Specify the language code (e.g., "en" for English).
- `only...` (e.g., `onlyImage`, `onlyVerifiedUsers`): Boolean flags (true/false) to filter for specific tweet
  characteristics.
- `includeSearchTerms`: Set to true if you want an extra field in the output showing which search term matched each
  tweet.

### Usage Guidelines (Important!)

- **Historical Data Focus:** This Actor is designed for retrieving historical data. Avoid using it for very frequent,
  real-time monitoring.
- **Concurrency Limits:**  There are limits on concurrent runs (maximum 1, with up to 5 batched queries).
- **Minimum Tweets Per Query:**  Aim to fetch at least 50 tweets per query (handle, keyword, etc.). This minimum
  increases proportionally when batching queries.
- **Single Tweet Fetching Restrictions:** Fetching a single tweet by URL is generally prohibited without explicit
  permission. Allow a few minutes interval time minimum between runs.
- **Respect Twitter's Terms of Service**: Always use this tool ethically and responsibly.

### Ethical Use and Data Practices

Our 'actor' operates without logging in to X.com. This means it does not implicitly accept any Terms of Service (ToS)
that require a login, as we only process data that is publicly displayed and accessible to everyone without
authentication.

We are fully committed to the principle of privacy by design and by default. All data collected explicitly excludes
sensitive personal information or non-public data.

Furthermore, our actor runs on Apify, an EU-based company, which means our operations are designed to be compliant with
relevant EU data protection regulations, including GDPR, where applicable. You can find more information about the
legality of web scraping on Apify's blog: https://blog.apify.com/is-web-scraping-legal/

We have implemented robust technical measures to ensure the actor operates gently and does not impose an undue burden on
X.com's servers. Our sole purpose is to facilitate responsible research and public data analysis, and we strictly
prohibit any use that could cause harm to any party or the platform
itself.

#### Output Example

```json
[
    {
        "id": "1630332507265589248",
        "url": "https://x.com/NASA/status/1630332507265589248",
        "twitterUrl": "https://twitter.com/NASA/status/1630332507265589248",
        "full_text": "@yalhunzai We have internships open to international students from countries with whom we have agreements: https://t.co/Kl2Lz4qjpw",
        "favorite_count": 14,
        "retweet_count": 9,
        "reply_count": 0,
        "quote_count": 0,
        "bookmark_count": 1,
        "author": {
            "id_str": "11348282",
            "screen_name": "NASA",
            "name": "NASA",
            "advertiser_account_service_levels": [
                "dso",
                "media_studio"
            ],
            "advertiser_account_type": "promotable_user",
            "analytics_type": "enabled",
            "can_dm": false,
            "can_media_tag": true,
            "created_at": "Wed Dec 19 20:20:32 +0000 2007",
            "description": "There's space for everybody. ✨\n\nVerification: https://t.co/8nok3NP4PW",
            "entities": {
                "description": {
                    "hashtags": [],
                    "symbols": [],
                    "urls": [
                        {
                            "display_url": "nasa.gov/socialmedia",
                            "expanded_url": "http://nasa.gov/socialmedia",
                            "indices": [
                                46,
                                69
                            ],
                            "url": "https://t.co/8nok3NP4PW"
                        }
                    ],
                    "user_mentions": []
                },
                "url": {
                    "urls": [
                        {
                            "display_url": "nasa.gov",
                            "expanded_url": "http://www.nasa.gov/",
                            "indices": [
                                0,
                                23
                            ],
                            "url": "https://t.co/9NkQJKAnuU"
                        }
                    ]
                }
            },
            "fast_followers_count": 0,
            "favourites_count": 16401,
            "followers_count": 85752559,
            "friends_count": 170,
            "geo_enabled": false,
            "has_custom_timelines": true,
            "has_extended_profile": true,
            "is_translator": false,
            "location": "Pale Blue Dot",
            "media_count": 27374,
            "normal_followers_count": 85752559,
            "pinned_tweet_ids_str": [],
            "profile_background_color": "000000",
            "profile_banner_url": "https://pbs.twimg.com/profile_banners/11348282/1718393721",
            "profile_image_url_https": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB_normal.jpg",
            "profile_interstitial_type": "",
            "profile_link_color": "205BA7",
            "protected": false,
            "statuses_count": 72761,
            "translator_type_enum": "Regular",
            "url": "https://t.co/9NkQJKAnuU",
            "verified": false,
            "verified_type": "Government",
            "withheld_in_countries": []
        },
        "bookmarked": false,
        "conversation_id_str": "1630332507265589248",
        "created_at": "Tue Feb 28 20:28:53 +0000 2023",
        "display_text_range": [
            11,
            130
        ],
        "entities": {
            "hashtags": [],
            "symbols": [],
            "timestamps": [],
            "urls": [
                {
                    "display_url": "go.nasa.gov/3EKfKkN",
                    "expanded_url": "https://go.nasa.gov/3EKfKkN",
                    "indices": [
                        107,
                        130
                    ],
                    "url": "https://t.co/Kl2Lz4qjpw"
                }
            ],
            "user_mentions": [
                {
                    "id_str": "1583456964453040129",
                    "indices": [
                        0,
                        10
                    ],
                    "name": "Baki bùlen",
                    "screen_name": "yalhunzai"
                }
            ]
        },
        "favorited": false,
        "in_reply_to_screen_name": "yalhunzai",
        "in_reply_to_status_id_str": "1630616311226048513",
        "in_reply_to_user_id_str": "1583456964453040129",
        "is_quote_status": false,
        "lang": "en",
        "possibly_sensitive": false,
        "possibly_sensitive_editable": true,
        "retweeted": false,
        "user_id_str": "11348282"
    }
]
```

### Troubleshooting

If you encounter issues like too few results, no results, or incomplete tweet collection, refer to the detailed
troubleshooting section in the Actor's input schema or documentation. Common causes include overly restrictive filters
or exceeding rate limits.

### Get Started

Start scraping Twitter data today!  This Actor provides a powerful, flexible, and cost-effective solution for all your
Twitter data extraction needs.

| [🎹️ Fast TikTok API](https://apify.com/novi/fast-tiktok-api)                                | [📹️ TikTok Trend API](https://apify.com/novi/tiktok-trend-api)         | [🔍️ TikTok Search API](https://apify.com/novi/tiktok-search-api)             |
|:---------------------------------------------------------------------------------------------|:------------------------------------------------------------------------|:------------------------------------------------------------------------------|
| [🧛️ TikTok User API](https://apify.com/novi/tiktok-user-api)                                | [🧛️ TikTok User Info API](https://apify.com/novi/tiktok-user-info-api) | [#️ TikTok Hashtag API](https://apify.com/novi/tiktok-hashtag-api)            |
| [🛍️ TikTok Shop API](https://apify.com/novi/tiktok-shop-scraper)                            | [👤️ TikTok Followers API](https://apify.com/novi/tiktok-followers-api) | [⚡️ TikTok Scraper (pay-per-result)](https://apify.com/xtdata/tiktok-scraper) |
| [💬 TikTok Comment API](https://apify.com/novi/tiktok-comment-api)                           | [🎶 TikTok Music API](https://apify.com/novi/tiktok-sound-api)          | [🎶 TikTok Music Trend API](https://apify.com/novi/tiktok-music-trend-api)    |
| [🎶 Tiktok Scraper Ultimate (pay-per-event)](https://apify.com/novi/tiktok-scraper-ultimate) |                                                                         |                                                                               |

# Actor input Schema

## `startUrls` (type: `array`):

Twitter (X) URLs. Paste the URLs and get the results immediately. Tweet, Profile, Search or List URLs are supported.

## `searchTerms` (type: `array`):

Search terms you want to search from Twitter (X). You can refer to https://github.com/igorbrigadir/twitter-advanced-search.

## `twitterHandles` (type: `array`):

Twitter handles (username) that you want to search on Twitter (X)

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

Maximum number of items that you want as output.

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

Sorts search results by the given option. If you are getting low results, try Top instead of Latest. Latest + Top runs both simultaneously to maximize results but may return some duplicate tweets.

## `tweetLanguage` (type: `string`):

Restricts tweets to the given language, given by an ISO 639-1 code.

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

If selected, only returns tweets by users who are verified.

## `onlyTwitterBlue` (type: `boolean`):

If selected, only returns tweets by users who are Twitter Blue subscribers.

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

If selected, only returns tweets that contain images.

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

If selected, only returns tweets that contain videos.

## `onlyQuote` (type: `boolean`):

If selected, only returns tweets that are quotes.

## `start` (type: `string`):

Returns tweets sent after the given date. Does not apply to startUrls or twitterHandles. If you want to filter by date, the best way is to use Twitter queries.

## `end` (type: `string`):

Returns tweets sent before the given date. Does not apply to startUrls or twitterHandles. If you want to filter by date, the best way is to use Twitter queries.

## `includeSearchTerms` (type: `boolean`):

If selected, a field will be added to each tweets about the search term that was used to find it.

## `customMapFunction` (type: `string`):

Function that takes each of the objects as argument and returns data that will be mapped by the function itself. This function is not intended for filtering, please don't use it for filtering purposes or you will get banned automatically.

## Actor input object example

```json
{
  "startUrls": [
    "https://twitter.com/apify",
    "https://twitter.com/search?q=apify%20&src=typed_query"
  ],
  "searchTerms": [
    "web scraping",
    "scraping from:apify"
  ],
  "twitterHandles": [
    "elonmusk",
    "taylorswift13"
  ],
  "maxItems": 50,
  "sort": "Top",
  "tweetLanguage": "en",
  "start": "2021-07-01",
  "end": "2021-07-02",
  "customMapFunction": "(object) => { return {...object} }"
}
```

# Actor output Schema

## `results` (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 = {
    "startUrls": [
        "https://twitter.com/apify",
        "https://twitter.com/search?q=apify%20&src=typed_query"
    ],
    "searchTerms": [
        "web scraping",
        "scraping from:apify"
    ],
    "twitterHandles": [
        "elonmusk",
        "taylorswift13"
    ],
    "maxItems": 50,
    "sort": "Top",
    "tweetLanguage": "en",
    "start": "2021-07-01",
    "end": "2021-07-02",
    "customMapFunction": (object) => { return {...object} }
};

// Run the Actor and wait for it to finish
const run = await client.actor("xtdata/twitter-x-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 = {
    "startUrls": [
        "https://twitter.com/apify",
        "https://twitter.com/search?q=apify%20&src=typed_query",
    ],
    "searchTerms": [
        "web scraping",
        "scraping from:apify",
    ],
    "twitterHandles": [
        "elonmusk",
        "taylorswift13",
    ],
    "maxItems": 50,
    "sort": "Top",
    "tweetLanguage": "en",
    "start": "2021-07-01",
    "end": "2021-07-02",
    "customMapFunction": "(object) => { return {...object} }",
}

# Run the Actor and wait for it to finish
run = client.actor("xtdata/twitter-x-scraper").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 '{
  "startUrls": [
    "https://twitter.com/apify",
    "https://twitter.com/search?q=apify%20&src=typed_query"
  ],
  "searchTerms": [
    "web scraping",
    "scraping from:apify"
  ],
  "twitterHandles": [
    "elonmusk",
    "taylorswift13"
  ],
  "maxItems": 50,
  "sort": "Top",
  "tweetLanguage": "en",
  "start": "2021-07-01",
  "end": "2021-07-02",
  "customMapFunction": "(object) => { return {...object} }"
}' |
apify call xtdata/twitter-x-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

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