# Tweet Scraper - $0.15/1K Tweets - No Rate Limits - X Scraper (`theagents/twitter-scraper`) Actor

Only $0.15 per 1,000 tweets. The cheapest and fastest Tweet Scraper on the platform for X/Twitter data extraction. Scrape tweets at scale with no rate limits, high reliability, fast retrieval, and powerful Twitter scraping infrastructure built for large datasets.

- **URL**: https://apify.com/theagents/twitter-scraper.md
- **Developed by:** [Agents](https://apify.com/theagents) (community)
- **Categories:** Social media, SEO tools, Lead generation
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.15 / 1,000 tweets

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

### Fast Twitter (X) Scraper API: Extract Tweets, Profiles, Conversations & Advanced Search at Scale

The **Twitter (X) Scraper** is an Apify Actor that extracts tweets, user timelines, conversation threads, and advanced-search results from Twitter (X)—including full text, engagement metrics, media, and rich author profiles—without requiring the paid X API. This **twitter scraper api** collects structured data from search queries, handles, and tweet IDs.

**Why a scraper instead of the X API?** The official X API charges hundreds of dollars per month and imposes strict rate limits and tweet caps. This scraper delivers the same public data with **event-based pricing** from as little as **$0.00015 per tweet**—no developer account, no OAuth, no rate-limit headaches. It speaks the full [Twitter advanced search](https://github.com/igorbrigadir/twitter-advanced-search) syntax, so you get exactly what you'd see on X.

Use this **twitter data extractor** for market research, sentiment analysis, lead generation, or brand monitoring. **Download tweet data** to JSON, CSV, or Excel for analytics, dashboards, and AI/ML pipelines.

**Pricing:** from $0.00015/tweet (at the highest volume discount tier) · **No X API key required**

> ⚠️ **Getting low results?** Try `queryType: Top` instead of `Latest`. Twitter has recently returned fewer results for some queries—especially with `until_time`. For large date ranges, split your query into smaller time windows (e.g. daily) to maximize coverage.

***

#### 📋 Table of Contents

1. [What Does the Twitter Scraper Do?](#what-does-the-twitter-scraper-do)
2. [Features and Capabilities](#features-and-capabilities)
3. [Pricing](#pricing)
4. [Input Parameters](#input-parameters)
5. [Output Format and Data Fields](#output-format-and-data-fields)
6. [AI Agent Integration via MCP](#ai-agent-integration-via-mcp)
7. [Related Tools](#related-tools)
8. [Demo Mode and Free Testing](#demo-mode-and-free-testing)
9. [Automated Scheduling and Monitoring](#automated-scheduling-and-monitoring)
10. [Quick Start Guide](#quick-start-guide)
11. [Use Cases and Industries](#use-cases-and-industries)
12. [Troubleshooting](#troubleshooting)
13. [Frequently Asked Questions](#frequently-asked-questions)
14. [Contact](#contact)

***

#### What Does the Twitter Scraper Do?

**Twitter data extraction** is the automated process of collecting tweets, engagement metrics, author profiles, and conversation data from Twitter (X). It powers market research, sentiment analysis, lead generation, and real-time brand monitoring.

The **Agents Twitter (X) Scraper** is a high-performance Actor that scrapes Twitter through three input modes, with automatic cursor-based pagination and full advanced-search support—no X API key, no OAuth, no rate limits.

##### What You Can Scrape

- **Search results** — any [Twitter advanced search](https://github.com/igorbrigadir/twitter-advanced-search) query, with Latest / Top ordering.
- **User timelines** — all tweets from one or more handles.
- **Single tweets** — specific tweets by ID.
- **Conversation threads & replies** — via the `conversation_id:` operator or the `filter:replies` field.
- **Twitter Lists** — every tweet from a public list.

##### What You Get From Every Tweet

- Tweet text, ID, URLs, language, and creation date
- Engagement metrics — retweets, replies, likes, quotes, bookmarks, views
- Reply/quote/retweet context and `conversationId`
- Media, cards, and place entities
- Full author profile — handle, name, verification, follower/following counts, and more

***

#### Features and Capabilities

##### Input Flexibility

| Input Type | Example | Best For |
| ---------- | ------- | -------- |
| **Search query** | `"searchTerms": ["from:NASA min_faves:100"]` | Keywords, advanced operators, date ranges |
| **Twitter handle** | `"twitterHandles": ["NASA"]` | Full user timelines |
| **Tweet ID** | `"tweetIDs": ["1846987139428634858"]` | Specific tweets (overrides everything else) |

##### Core Features

- **Full Advanced Search** — every Twitter search operator works inside `searchTerms` / `twitterContent`.
- **Automatic Pagination** — cursor-based paging fetches large result sets, not just the first page.
- **Dedicated Filter Fields** — language, user, geo, engagement, media, and date/ID ranges as first-class inputs (applied to `twitterContent`).
- **Human-Friendly Dates** — `since:`/`until:` dates are auto-converted to `since_time:`/`until_time:` (UNIX), with timezone support.
- **Sort Control** — `queryType` supports `Latest` and `Top`.
- **Rich Author Data** — full user profiles attached to every tweet.
- **Resilient** — automatic retries, 5xx handling, and rate-limit backoff built in.
- **Multiple Export Formats** — JSON, CSV, Excel direct download.
- **API & MCP Integration** — REST API for any language, plus AI-agent access via the Apify MCP server.

***

#### Pricing

##### Event-Based Cost Structure

Pay only for what you scrape—no subscriptions, no hidden fees. This **twitter scraper api** uses transparent pay-per-event pricing that gets cheaper automatically as your usage grows, through Apify's volume discount tiers:

| Event Type | No discount | Bronze | Silver | Gold | What's Included |
| ---------- | -----------: | -----: | -----: | -----: | --------------- |
| **Search** (`list-query`) | $0.005/query | $0.004/query | $0.0036/query | $0.003/query | One search, profile, replies, or list request. Includes the first 20 tweets for free. |
| **Tweet URL** (`get-tweet-query`) | $0.015/query | $0.012/query | $0.0105/query | $0.009/query | Fetching an individual tweet by ID or URL. |
| **Tweet** (`dataset-item`) | $0.00025/tweet | $0.0002/tweet | $0.00018/tweet | $0.00015/tweet | Each tweet returned in the dataset, beyond the first 20 free tweets per search. |

> The first 20 tweets of every search are pre-paid as part of the **Search** event fee, so they don't add any extra **Tweet** cost. Only tweets beyond that first 20 are billed as dataset items.

**Free users:** Limited to **5 runs per month**, each capped at **10 items**.

##### Cost Examples

Using the default (no discount) rate:

| Scenario | Approximate Cost |
| -------- | ---------------- |
| 1 search query, ~20 tweets | $0.005 (covered by the free 20-tweet allowance) ≈ **$0.005** |
| 1 search query, 200 tweets | $0.005 + (200 − 20) × $0.00025 ≈ **$0.05** |
| 10 profiles, ~200 tweets each | 10 × $0.005 + 10 × (200 − 20) × $0.00025 ≈ **$0.50** |
| 1 tweet via URL | $0.015 + $0.00025 ≈ **$0.015** |

##### Cost Optimization Tips

1. Use search queries instead of many individual handles/URLs when possible—each query has its own per-query fee.
2. Keep queries focused so you only pay for the tweets you actually need.
3. Use `maxItems` to cap total output and control spend.

***

#### Input Parameters

| Field | Type | Description | Default |
| ----- | ---- | ----------- | ------- |
| `tweetIDs` | array | Tweet IDs to scrape individually. **When set, all other inputs are ignored.** | `[]` |
| `twitterContent` | string | A single Twitter advanced search query. Dedicated filter fields below are appended to it. | `""` |
| `searchTerms` | array | Multiple search queries, each processed separately (passed verbatim). `maxItems` applies per term. | `[]` |
| `twitterHandles` | array | Handles whose timelines to scrape (no `@` needed). | `[]` |
| `maxItems` | integer | Maximum items to return (per search term when `searchTerms` is set). | `200` |
| `queryType` | string | Result ordering: `Latest` or `Top`. | `Latest` |
| `lang` | string | Restrict to an ISO 639-1 language code (e.g. `en`). | `null` |
| `from` / `to` / `@` | string | Tweets from / replying to / mentioning a specific `@username`. | `null` |
| `list` | string | Tweets from members of a public list (list ID). | `null` |
| `conversation_id` | string | Tweets in a specific thread. | `null` |
| `near` / `within` / `geocode` | string | Geo filters: place, radius, or coordinate radius. | `null` |
| `since_time` / `until_time` | string | Date range as UNIX timestamps (seconds). | `null` |
| `since_id` / `max_id` | string | Date range by tweet ID. | `null` |
| `min_retweets` / `min_faves` / `min_replies` | integer | Minimum engagement thresholds. | `0` |
| `filter:blue_verified` | boolean | Only tweets from Blue-verified users. | `false` |
| `filter:images` / `filter:videos` / `filter:media` | boolean | Only tweets with images / videos / any media. | `false` |
| `filter:quote` / `filter:replies` | boolean | Only quote tweets / only replies. | `false` |
| `url` | string | Match tweets containing a URL/domain (the `url:` operator). | `null` |

> 💡 The dedicated filter fields (`lang`, `from`, `filter:*`, `min_*`, date/ID ranges, etc.) are appended to `twitterContent`. For `searchTerms`, put operators directly inside each term — they're sent to Twitter as-is.

The Actor also exposes 20+ additional dedicated fields for the full [Twitter advanced search](https://github.com/igorbrigadir/twitter-advanced-search) syntax—media type (`filter:videos`, `filter:images`, `filter:native_video`, …), engagement (`filter:has_engagement`, `-min_retweets`, …), tweet type (`filter:quote`, `include:nativeretweets`, `quoted_tweet_id`, …), polls (`card_name`), and more. Open the Actor's **Input** tab in Apify Console to see every field with inline examples.

##### Input Examples

**Advanced search:**

```json
{
    "searchTerms": ["from:NASA filter:images min_faves:100"],
    "queryType": "Top",
    "maxItems": 200
}
```

**User timelines by handle:**

```json
{
    "twitterHandles": ["NASA", "elonmusk"],
    "maxItems": 100
}
```

**Specific tweets by ID:**

```json
{
    "tweetIDs": ["1846987139428634858", "1858743654778892784"]
}
```

***

#### Output Format and Data Fields

Each tweet is a structured JSON object. Here is a sample:

```json
{
  "type": "tweet",
  "id": "1728108619189874825",
  "url": "https://x.com/elonmusk/status/1728108619189874825",
  "twitterUrl": "https://twitter.com/elonmusk/status/1728108619189874825",
  "text": "More than 10 per human on average",
  "retweetCount": 11311,
  "replyCount": 6526,
  "likeCount": 104121,
  "quoteCount": 2915,
  "viewCount": 10913296,
  "bookmarkCount": 702,
  "createdAt": "Fri Nov 24 17:49:36 +0000 2023",
  "lang": "en",
  "isReply": false,
  "conversationId": "1728108619189874825",
  "isPinned": false,
  "isRetweet": false,
  "isQuote": true,
  "author": {
    "type": "user",
    "userName": "elonmusk",
    "url": "https://x.com/elonmusk",
    "id": "44196397",
    "name": "Elon Musk",
    "isVerified": true,
    "isBlueVerified": true,
    "followers": 172669889,
    "following": 538
  }
}
```

##### Key Fields

| Field | Type | Description |
| ----- | ---- | ----------- |
| `id` | string | Tweet ID |
| `url` / `twitterUrl` | string | Canonical tweet URLs |
| `text` | string | Tweet text |
| `retweetCount` / `replyCount` / `likeCount` / `quoteCount` / `viewCount` / `bookmarkCount` | number | Engagement metrics |
| `createdAt` | string | Tweet creation timestamp |
| `lang` | string | Detected language |
| `isReply` / `isRetweet` / `isQuote` / `isPinned` | boolean | Tweet type flags |
| `conversationId` | string | Thread ID the tweet belongs to |
| `author` | object | Full author profile (handle, name, verification, follower counts, …) |

***

#### AI Agent Integration via MCP

Apify provides a hosted **Model Context Protocol (MCP) server** at `mcp.apify.com` that lets AI agents discover and run Apify Actors as tools—including this Twitter Scraper.

##### How to Connect

Add this to your MCP client config (Claude Desktop, Cursor, etc.):

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=agents/twitter-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect—no API token needed in the config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from [API & Integrations](https://console.apify.com/settings/integrations) in Apify Console.

Or run locally for development:

```bash
npx @apify/actors-mcp-server --tools agents/twitter-scraper
```

##### Use Cases for AI Agent Integration

- **Autonomous social research** — an agent receives "find recent tweets from NASA about the Moon" and calls this scraper for structured data.
- **Sentiment & trend pipelines** — feed tweets into an LLM for summarization, sentiment scoring, or report generation.
- **Multi-step workflows** — combine with the [Agents](https://apify.com/theagents?fpr=yhdrb) review scrapers to blend social and review signals in one pipeline.

For full setup, see the [Apify MCP documentation](https://docs.apify.com/platform/integrations/mcp).

***

#### Related Tools

##### Agents Data Intelligence Suite

All tools below are built and maintained by [Agents](https://apify.com/theagents?fpr=yhdrb)—a team of ex-Big Tech engineers, former ad agency strategists, and data specialists delivering intelligence, precision, and impact at scale.

| Tool | What It Extracts | Best For |
| ---- | ---------------- | -------- |
| **Twitter (X) Scraper** | Tweets, profiles, conversations, search | Social intelligence **(You are here)** |
| **[Google Maps Search Scraper](https://apify.com/theagents/google-maps-search?fpr=yhdrb)** | Business listings, contact, ratings | Lead generation, directories |
| **[Google Maps Business Scraper](https://apify.com/theagents/google-maps-business?fpr=yhdrb)** | Full business profiles and data | Business data, prospecting |
| **[Google Maps Reviews Scraper](https://apify.com/theagents/google-maps-reviews?fpr=yhdrb)** | Reviews, ratings, reviewer profiles | Sentiment, reputation monitoring |
| **[Yelp Business Scraper](https://apify.com/theagents/yelp-business?fpr=yhdrb)** | Business profiles, ratings, contact | Lead generation |
| **[Yelp Reviews Scraper](https://apify.com/theagents/yelp-reviews?fpr=yhdrb)** | Yelp reviews, ratings, reviewer profiles | Restaurant/hospitality |
| **[Trustpilot Reviews Scraper](https://apify.com/theagents/trustpilot-reviews?fpr=yhdrb)** | Reviews, TrustScores, company replies | SaaS/B2B analysis |
| **[TripAdvisor Reviews Scraper](https://apify.com/theagents/tripadvisor-reviews?fpr=yhdrb)** | Hotel/restaurant reviews, ratings | Hospitality intelligence |
| **[Google Play Reviews Scraper](https://apify.com/theagents/googleplay-reviews?fpr=yhdrb)** | Android app reviews and ratings | App/product feedback |
| **[App Store Reviews Scraper](https://apify.com/theagents/appstore-reviews?fpr=yhdrb)** | iOS app reviews and ratings | App/product feedback |

***

#### Demo Mode and Free Testing

If you run on Apify's Free plan, you can still use this **twitter scraper** in Demo Mode. **Free users can run the actor up to 5 times per month**, with each run capped at a maximum of 10 items — just enough to test it out. Free users also cannot use the actor via API. For unrestricted usage and full API access at scale, subscribe to a paid Apify plan.

**Free Plan Benefits:**

- Test the API before committing to larger runs
- Validate output format and data quality
- No credit card required to start

**Upgrade for Full Access:**

- No item caps per run
- Full API access for integration with your systems
- Scheduled runs and webhooks for automated pipelines

For unrestricted usage, [subscribe to a paid Apify plan](https://apify.com/pricing?fpr=yhdrb).

***

#### Automated Scheduling and Monitoring

Conversations on X move fast. For brand monitoring, trend tracking, and sentiment analysis, set up automated recurring runs to keep your data current.

##### Why Schedule Extraction?

- **Brand monitoring** — catch new mentions early for rapid response
- **Trend tracking** — follow hashtags and topics as they evolve
- **Competitive intelligence** — track competitor activity and engagement
- **Sentiment over time** — build time-series datasets for analysis

##### How to Set Up Scheduled Runs

1. Open the Actor in Apify Console
2. Configure your input (search terms, handles, `maxItems`, etc.)
3. Click **Schedule** and set frequency (hourly, daily, weekly)
4. Optionally add a **webhook** to push new data to your pipeline (CRM, database, Slack, Zapier/Make)

***

#### Quick Start Guide

##### For Non-Technical Users (Apify Console)

1. Open the **Twitter (X) Scraper** on Apify
2. Click **Try for free**
3. Enter `searchTerms`, `twitterHandles`, or `tweetIDs`
4. Set `maxItems`
5. Click **Start** and export results (JSON/CSV/Excel) from the Storage tab

##### For Developers (Python API)

```python
from apify_client import ApifyClient
client = ApifyClient("YOUR_TOKEN")
run = client.actor("agents/twitter-scraper").call(run_input={
    "searchTerms": ["from:NASA"],
    "queryType": "Latest",
    "maxItems": 200
})
items = client.dataset(run["defaultDatasetId"]).list_items().items
```

##### For Developers (JavaScript / Node.js API)

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_TOKEN' });

const run = await client.actor('agents/twitter-scraper').call({
    searchTerms: ['from:NASA'],
    queryType: 'Latest',
    maxItems: 200,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

##### For Developers (CLI / cURL)

```bash
curl --location 'https://api.apify.com/v2/acts/theagents~twitter-scraper/run-sync-get-dataset-items?token=YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "searchTerms": ["from:NASA"],
    "queryType": "Latest",
    "maxItems": 200
}'
```

##### For Analysts (Multiple Queries)

```json
{
    "searchTerms": ["from:NASA min_faves:100", "from:SpaceX filter:media"],
    "queryType": "Top",
    "maxItems": 500
}
```

***

#### Use Cases and Industries

##### Market Research and Trend Analysis

Track topics, hashtags, and audience sentiment across languages and regions to spot emerging trends before they go mainstream.

**Key fields:** `text`, `lang`, `likeCount`, `retweetCount`, `createdAt`

##### Brand Monitoring and Reputation Management

Monitor mentions of your brand and competitors in real time; respond quickly to negative sentiment.

**Key fields:** `text`, `author`, `replyCount`, `conversationId`

##### Lead Generation and Sales Intelligence

Find and qualify prospects engaging with specific topics, competitors, or hashtags.

**Key fields:** `author.userName`, `author.followers`, `text`

##### Academic and Data Science Research

Build large, structured datasets for NLP, sentiment analysis, and social-network studies.

**Key fields:** `text`, `lang`, engagement metrics, `author`

***

#### Troubleshooting

| Issue | Cause | Solution |
| ----- | ----- | -------- |
| **Fewer results than expected** | `queryType: Latest` or restrictive query | Try `queryType: Top`; remove `until_time`; split large date ranges into smaller windows |
| **No results** | Overly restrictive or invalid query | Test the query on [Twitter's search](https://x.com/search); loosen filters |
| **Missing tweets** | Shadow banning or Twitter filtering | Outside our control; try different date ranges |
| **Outputs look incomplete** | Viewing overview only | Open the **Storage** tab → "Download the results" or "Open in a New Tab" |
| **Filters seem ignored** | Dedicated filter fields only apply to `twitterContent` | Put operators directly inside each `searchTerms` entry |

***

#### Frequently Asked Questions

##### Do I need a Twitter/X API key?

No. This scraper requires no X developer account, no API key, and no OAuth. Just provide search terms, handles, or tweet IDs.

##### How much does it cost?

Event-based, from as little as **$0.00015 per tweet** returned, at the highest volume discount tier. Use `maxItems` to cap spend. See [Pricing](#pricing) for the full tier breakdown.

##### What can I scrape?

Search results, user timelines, single tweets, conversation threads/replies, and Twitter Lists—via search queries, handles, or tweet IDs.

##### Can I use full Twitter advanced search?

Yes. Every [advanced search](https://github.com/igorbrigadir/twitter-advanced-search) operator works when placed inside `searchTerms` or `twitterContent`.

##### Can I export to CSV?

Yes. Download results from Apify Console in JSON, CSV, or Excel format.

##### Can I use Python or Node.js?

Yes. Use the Apify Client for [Python](https://docs.apify.com/api/client/python/docs) or [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs), or the [REST API](https://docs.apify.com/api/v2) for any language.

##### Can AI agents use this scraper?

Yes—via Apify's MCP server. See [AI Agent Integration via MCP](#ai-agent-integration-via-mcp).

##### Is this legal to use?

This tool extracts publicly available data. Always ensure your use case complies with Twitter/X's Terms of Service and applicable data protection regulations.

***

#### Contact

**Built by [Agents](https://apify.com/theagents?fpr=yhdrb)** — Where others search, we uncover. Our team of ex-Big Tech engineers, growth hackers, and data specialists builds high-performance scraping tools engineered for speed, precision, and reliability.

For questions or further assistance:

- **Email:** Reach out at **whoaretheagents@gmail.com**
- **Discord:** Join our community to connect with our support team

***

**Ready to start extracting Twitter data?** With transparent event-based pricing from as little as **$0.00015 per tweet** and no X API key required, this **Twitter (X) Scraper API** by [Agents](https://apify.com/theagents?fpr=yhdrb) is the definitive tool for **market research**, **sentiment analysis**, **brand monitoring**, and **lead generation**. Start scraping today. 🐦

# Actor input Schema

## `tweetIDs` (type: `array`):

Enter the tweet ids you want to scrape. Case1: 1846987139428634858,1858743654778892784. Note: When this field has a value, all other filter conditions will be ignored.

## `twitterContent` (type: `string`):

Enter the content of the tweet you want to scrape. case 1: nasa esa => Containing both "nasa" and "esa". Spaces are implicit AND. Brackets can be used to group individual words if using other operators. case 2: nasa OR esa => Either "nasa" or "esa". OR must be in uppercase. case 3: "state of the art" => The complete phrase "state of the art". Will also match "state-of-the-art". Also use quotes to prevent spelling correction. case 4: "this is the \* time this week" => A complete phrase with a wildcard. \* does not work outside of a quoted phrase or without spaces. case 5: +radiooooo => Force a term to be included as-is. Useful to prevent spelling correction. case 6: -love => - is used for excluding "love". Also applies to quoted phrases and other operators. case 7: -"live laugh love" => - also applies to quoted phrases and other operators. case 8: #tgif => A hashtag. case 9: $TWTR => A cashtag, like hashtags but for stock symbols. case 10: What ? => Question marks are matched. case 11: :) OR :( => Some emoticons are matched, positive :) :-) :P :D or negative :-( :(. case 12: 👀 => Emoji searches are also matched. Usually needs another operator to work.

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

Enter the search terms you want to scrape. Each term should follow Twitter's search syntax. Multiple terms will be processed separately. If set, this field will override the twitterContent field, and the field 'Maximum number of items on output' means the maximum number of items for each search term.

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

Maximum number of items that you want as output. When searchTerms is set, this field means the maximum number of items for each search term. Twitter has a default limit of around 800 tweets per query. Check the README for workarounds.

## `queryType` (type: `string`):

This field determines the type of Twitter search to be performed. The options are 'Latest', 'Top', 'Photos', 'Videos'. 'Latest' will return the most recent tweets. 'Top' will return the most popular or relevant tweets according to Twitter's algorithm. 'Photos' will return tweets containing photos. 'Videos' will return tweets containing videos. Alias of the sort field above, accepted for Tweet Scraper input compatibility. When both are set, sort takes precedence.

## `lang` (type: `string`):

Search for tweets in specified language, not always accurate. Language is specified as https://en.wikipedia.org/wiki/List\_of\_ISO\_639-1\_codes.

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

You can add the twitter handles of specific profiles you want to scrape. This is a shortcut so that you don't have to add full username URLs like https://twitter.com/apify

## `from` (type: `string`):

Sent by a particular @username e.g. "NASA". https://twitter.com/search?q=dogs%20from%3Anasa\&src=typed\_query\&f=live

## `to` (type: `string`):

Replying to a particular @username. eg. "NASA". https://twitter.com/search?q=%23MoonTunes%20to%3Anasa\&src=typed\_query\&f=live

## `@` (type: `string`):

Mentioning a particular @username. Combine with -from:username to get only mentions. Eg. https://twitter.com/search?q=%40cern%20-from%3Acern\&src=typed\_query\&f=live

## `list` (type: `string`):

Tweets from members of this public list. Use the list ID from the API or with urls like twitter.com/i/lists/715919216927322112. List slug is for old list urls like twitter.com/esa/lists/astronauts.

## `filter:blue_verified` (type: `boolean`):

Filter tweets from blue verified users only. However, I found that using filter:blue\_verified alone causes issues and needs to be used together with filter:verified, possibly due to a Twitter bug. Eg. https://twitter.com/search?q=filter%3Ablue\_verified%20-filter%3Averified\&src=typed\_query\&f=live

## `near` (type: `string`):

Geotagged in this place. Also supports Phrases, eg: near:"The Hague". eg https://twitter.com/search?q=near%3A%22The%20Hague%22\&src=typed\_query\&f=live

## `within` (type: `string`):

Within specific radius of the "near" operator, to apply a limit. Can use km or mi. e.g. fire near:san-francisco within:10km. eg: https://twitter.com/search?q=fire%20near%3Asan-francisco%20within%3A10km\&src=typed\_query\&f=live

## `geocode` (type: `string`):

Search within a specific radius of a coordinate. E.g. to get tweets 10km around twitters hq, use geocode:37.7764685,-122.4172004,10km. Eg. https://twitter.com/search?q=geocode%3A37.7764685%2C-122.4172004%2C10km\&src=typed\_query\&f=live

## `since_time` (type: `string`):

On or after a specified unix timestamp in seconds. Combine with the "Until Time" operator for dates between. Maybe easier to use than since\_id below. Eg. https://twitter.com/search?q=since\_time%3A1561720321%20until\_time%3A1562198400%20%23nasamoontunes\&src=typed\_query\&f=live

## `until_time` (type: `string`):

Before a specified unix timestamp in seconds. Combine with a "Since Time" operator for dates between. Maybe easier to use than max\_id below. Eg. https://twitter.com/search?q=since\_time%3A1561720321%20until\_time%3A1562198400%20%23nasamoontunes\&src=typed\_query\&f=live

## `since_id` (type: `string`):

On or after a specified tweet ID. Combine with the "Max ID" operator for dates between. Maybe easier to use than since\_time above. Eg. https://twitter.com/search?q=since\_id%3A1138872932887924737%20max\_id%3A1144730280353247233%20%23nasamoontunes\&src=typed\_query\&f=live

## `max_id` (type: `string`):

Before a specified tweet ID. Combine with a "Since ID" operator for dates between. Maybe easier to use than until\_time above. Eg. https://twitter.com/search?q=since\_id%3A1138872932887924737%20max\_id%3A1144730280353247233%20%23nasamoontunes\&src=typed\_query\&f=live

## `filter:nativeretweets` (type: `boolean`):

Only retweets created using the retweet button. Works well combined with from: to show only retweets. Only works within the last 7-10 days or so. Eg. https://twitter.com/search?q=from%3Anasa%20filter%3Anativeretweets\&src=typed\_query\&f=live

## `include:nativeretweets` (type: `boolean`):

Native retweets are excluded by default. This shows them. In contrast to filter:, which shows only retweets, this includes retweets in addition to other tweets. Only works within the last 7-10 days or so. Eg. https://twitter.com/search?q=from%3Anasa%20include%3Anativeretweets%20\&src=typed\_query\&f=live

## `filter:replies` (type: `boolean`):

Tweet is a reply to another Tweet. good for finding conversations, or threads if you add or remove to:user. eg. https://twitter.com/search?q=from%3Anasa%20filter%3Areplies%20-to%3Anasa\&src=typed\_query\&f=live

## `conversation_id` (type: `string`):

Tweets that are part of a thread (direct replies and other replies). Eg. https://twitter.com/search?q=conversation\_id%3A1140437409710116865%20lang%3Aen\&src=typed\_query\&f=live

## `filter:quote` (type: `boolean`):

Contain Quote Tweets. Eg. https://twitter.com/search?q=from%3Anasa%20filter%3Aquote\&src=typed\_query\&f=live

## `quoted_tweet_id` (type: `string`):

Search for quotes of a specific tweet. Eg. https://twitter.com/search?q=quoted\_user\_id%3A11348282\&src=typed\_query\&f=live

## `quoted_user_id` (type: `string`):

Search for all quotes of a specific user, by numeric User ID. Eg. https://twitter.com/search?q=quoted\_user\_id%3A11348282\&src=typed\_query\&f=live

## `card_name` (type: `string`):

Tweets containing polls. For polls containing 2, 3, 4 choices, or image Polls. Eg. https://twitter.com/search?q=lang%3Aen%20card\_name%3Apoll4choice\_text\_only%20OR%20card\_name%3Apoll3choice\_text\_only%20OR%20card\_name%3Apoll2choice\_text\_only\&src=typed\_query\&f=live

## `filter:has_engagement` (type: `boolean`):

Has some engagement (replies, likes, retweets). Can be negated to find tweets with no engagement. Note all of these are mutually exclusive with filter:nativeretweets or include:nativeretweets, as they apply to the retweet, not the original tweet, so they won't work as expected. Eg. https://twitter.com/search?q=breaking%20filter%3Anews%20-filter%3Ahas\_engagement\&src=typed\_query\&f=live

## `min_retweets` (type: `integer`):

Minimum number of retweets. Eg. https://twitter.com/search?q=min\_retweets%3A5000%20nasa\&src=typed\_query\&f=live

## `min_faves` (type: `integer`):

Minimum number of favorites. Eg. https://twitter.com/search?q=min\_faves%3A5000%20nasa\&src=typed\_query\&f=live

## `min_replies` (type: `integer`):

Minimum number of replies. Eg. https://twitter.com/search?q=min\_replies%3A5000%20nasa\&src=typed\_query\&f=live

## `-min_retweets` (type: `integer`):

A maximum number of Retweets. Eg. https://twitter.com/search?q=-min\_retweets%3A5000%20nasa\&src=typed\_query\&f=live

## `-min_faves` (type: `integer`):

A maximum number of Faves. Eg. https://twitter.com/search?q=-min\_faves%3A5000%20nasa\&src=typed\_query\&f=live

## `-min_replies` (type: `integer`):

A maximum number of Replies. Eg. https://twitter.com/search?q=-min\_replies%3A5000%20nasa\&src=typed\_query\&f=live

## `filter:media` (type: `boolean`):

Filter tweets with media, All media types. Eg. https://twitter.com/search?q=filter%3Amedia%20%23nasamoontunes\&src=typed\_query\&f=live

## `filter:twimg` (type: `boolean`):

Native Twitter images (pic.twitter.com links). Eg. https://twitter.com/search?q=filter%3Atwimg%20%23nasamoontunes\&src=typed\_query\&f=live

## `filter:images` (type: `boolean`):

Filter tweets with images. Eg. https://twitter.com/search?q=filter%3Aimages%20%23nasamoontunes\&src=typed\_query\&f=live

## `filter:videos` (type: `boolean`):

All video types, including native Twitter video and external sources such as Youtube. Eg. https://twitter.com/search?q=filter%3Avideos%20%23nasamoontunes\&src=typed\_query\&f=live

## `filter:native_video` (type: `boolean`):

All Twitter-owned video types (native video, vine, periscope). Eg. https://twitter.com/search?q=filter%3Anative\_video%20%23nasamoontunes\&src=typed\_query\&f=live

## `filter:vine` (type: `boolean`):

Vine videos. Eg. https://twitter.com/search?q=filter%3Avine%20%23nasamoontunes\&src=typed\_query\&f=live

## `filter:consumer_video` (type: `boolean`):

Twitter native video only. Eg. https://twitter.com/search?q=filter%3Aconsumer\_video%20%23nasamoontunes\&src=typed\_query\&f=live

## `filter:pro_video` (type: `boolean`):

Twitter pro video (Amplify) only. Eg. https://twitter.com/search?q=filter%3Apro\_video%20%23nasamoontunes\&src=typed\_query\&f=live

## `filter:spaces` (type: `boolean`):

Twitter Spaces only. Eg. https://twitter.com/search?q=filter%3Aspaces%20%23nasamoontunes\&src=typed\_query\&f=live

## `filter:links` (type: `boolean`):

Only containing some URL, includes media. use -filter:media for urls that aren't media. Eg. https://twitter.com/search?q=filter%3Alinks%20%23nasamoontunes\&src=typed\_query\&f=live

## `filter:mentions` (type: `boolean`):

Containing any sort of @mentions. Eg. https://twitter.com/search?q=filter%3Amentions%20%23nasamoontunes\&src=typed\_query\&f=live

## `filter:news` (type: `boolean`):

Containing link to a news story. Combine with a list operator to narrow the user set down further. Matches on a list of Domains. (See Note for full list: https://github.com/igorbrigadir/twitter-advanced-search?tab=readme-ov-file#news-sites)

## `filter:safe` (type: `boolean`):

Excluding NSFW content. Excludes content that users have marked as "Potentially Sensitive". Doesn't always guarantee SFW results.

## `filter:hashtags` (type: `boolean`):

Containing any sort of hashtags. Eg. https://twitter.com/search?q=filter%3Ahashtags%20%23nasamoontunes\&src=typed\_query\&f=live

## `url` (type: `string`):

urls are tokenized and matched, works very well for subdomains and domains, not so well for long urls, depends on url. Youtube ids work well. Works for both shortened and canonical urls, eg: gu.com shortener for theguardian.com. When searching for Domains with hyphens in it, you have to replace the hyphen by an underscore (like url:t\_mobile.com) but underscores \_ are also tokenized out, and may not match. Eg. https://twitter.com/search?q=url%3Agu.com\&src=typed\_query\&f=live

## Actor input object example

```json
{
  "searchTerms": [
    "apify"
  ],
  "maxItems": 200,
  "filter:blue_verified": false,
  "filter:nativeretweets": false,
  "include:nativeretweets": false,
  "filter:replies": false,
  "filter:quote": false,
  "filter:has_engagement": false,
  "min_retweets": 0,
  "min_faves": 0,
  "min_replies": 0,
  "-min_retweets": 0,
  "-min_faves": 0,
  "-min_replies": 0,
  "filter:media": false,
  "filter:twimg": false,
  "filter:images": false,
  "filter:videos": false,
  "filter:native_video": false,
  "filter:vine": false,
  "filter:consumer_video": false,
  "filter:pro_video": false,
  "filter:spaces": false,
  "filter:links": false,
  "filter:mentions": false,
  "filter:news": false,
  "filter:safe": false,
  "filter:hashtags": false
}
```

# Actor output Schema

## `overview` (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 = {
    "searchTerms": [
        "apify"
    ],
    "maxItems": 200
};

// Run the Actor and wait for it to finish
const run = await client.actor("theagents/twitter-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 = {
    "searchTerms": ["apify"],
    "maxItems": 200,
}

# Run the Actor and wait for it to finish
run = client.actor("theagents/twitter-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 '{
  "searchTerms": [
    "apify"
  ],
  "maxItems": 200
}' |
apify call theagents/twitter-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,theagents/twitter-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/zHhpf5cLN7ymb3nIk/builds/3TCz3TUtKJy3gc8ha/openapi.json