# X (Twitter) Account Tweets Scraper (`xtracto/x-account-tweets-scraper`) Actor
Get recent tweets from any public X (Twitter) account by handle. Returns up to ~100 most recent tweets per account with text, media, counts (likes/retweets/replies/views), entities, and author metadata. HTTP-only, no login required.
- **URL**: https://apify.com/xtracto/x-account-tweets-scraper.md
- **Developed by:** [Farhan Febrian Nauval](https://apify.com/xtracto) (community)
- **Categories:** Social media
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet
## Pricing
from $0.10 / 1,000 results
This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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 a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.
In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):
```bash
npm install apify-client
```
In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):
```bash
pip install apify-client
```
In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):
````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash
In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).
If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).
For usage examples, see the [API](#api) section below.
For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).
# README
## X (Twitter) Account Tweets Scraper
Bulk-scrape recent tweets from any public X (Twitter) account — full text (including long tweets over 280 characters), media URLs, view count, like / retweet / reply / quote counts, hashtags, mentions, and author metadata — in a clean structured JSON output.
### Why use this actor
- **No account / no login required** — just give it an X handle, an `@handle`, or a profile URL.
- **No API key needed** — get the same data the X web app shows, without paying for the X API.
- **Full tweet text, not truncated** — long tweets (>280 chars, premium long-form) are returned in full via the `full_text` field; the legacy 280-char shape is preserved for backward compatibility.
- **All public engagement counters** — view count, likes, retweets, replies, quotes, and bookmarks per tweet.
- **Paginated timeline** — automatically follows the next-page cursor so you can pull dozens of tweets per account in one run.
- **Bulk input** — pass a list of handles in a single run; each account is processed independently with its own error envelope.
- **Stable JSON output** suitable for pipelines, spreadsheets, and databases — every row carries `_input`, `_source`, and `_scrapedAt` envelope fields so you can join results back to your input list.
### How it works
1. You provide a list of X handles (e.g. `jack`) or profile URLs (e.g. `https://x.com/elonmusk`).
2. The actor resolves each handle to the underlying account, then reads its public timeline page by page the same way the X web app does.
3. For tweets with long-form content, the full rich-text body is lifted into `full_text` automatically.
4. Results stream into your dataset, ready to download as JSON, CSV, or Excel.
You do not need to manage scrapers, browsers, or rotating IPs — all handled internally.
### Input
```json
{
"handles": ["jack", "elonmusk"],
"maxTweets": 50,
"includeReplies": false,
"proxyConfiguration": {
"useApifyProxy": true,
"apifyProxyGroups": ["DATACENTER"]
}
}
````
| Field | Type | Description |
|---|---|---|
| `handles` | array | List of X (Twitter) accounts to scrape. Bare handle (`jack`), `@handle`, or full profile URL all accepted. |
| `maxTweets` | integer | Maximum tweets to return per account. Default `50`. X serves up to ~100 tweets per anonymous page; higher values rely on pagination and may stop early when no further page is available. |
| `includeReplies` | boolean | If `true`, return the tweets-and-replies timeline (conversational view). Default `false` (original tweets and retweets only). |
| `proxyConfiguration` | object | Apify Proxy settings. Datacenter proxy is sufficient and is the cheapest option. |
### Output
Input: `jack`, `maxTweets: 3`
```json
{
"_input": "jack",
"_source": "S1-primary",
"_scrapedAt": "2026-05-18T11:04:21.569704+00:00",
"rest_id": "1833951636005552366",
"id_str": "1833951636005552366",
"conversation_id_str": "1833951636005552366",
"created_at": "Wed Sep 11 19:31:57 +0000 2024",
"lang": "en",
"full_text": "We reject: kings, presidents, and voting.\nWe believe in: rough consensus and running code.\n\n—David Clark, 1992",
"display_text_range": [0, 110],
"favorite_count": 26190,
"retweet_count": 4333,
"reply_count": 3646,
"quote_count": 674,
"bookmark_count": 3474,
"views": { "count": "7990536", "state": "EnabledWithCount" },
"entities": {
"hashtags": [],
"user_mentions": [],
"urls": [],
"symbols": [],
"smarttags": [],
"timestamps": []
},
"is_quote_status": false,
"source": "Twitter Web App",
"user_id_str": "12",
"author": {
"screen_name": "jack",
"name": "jack",
"rest_id": "12",
"description": "no state is the best state",
"followers_count": 7537418,
"friends_count": 3,
"statuses_count": 30509,
"media_count": 2963,
"listed_count": 33146,
"is_blue_verified": true,
"profile_banner_url": "https://pbs.twimg.com/profile_banners/12/1742427520"
}
}
```
```json
{
"_input": "jack",
"_source": "S1-primary",
"_scrapedAt": "2026-05-18T11:04:21.570681+00:00",
"rest_id": "1247616214769086465",
"id_str": "1247616214769086465",
"created_at": "Tue Apr 07 20:04:19 +0000 2020",
"lang": "en",
"full_text": "I'm moving $1B of my Square equity (~28% of my wealth) to #startsmall LLC to fund global COVID-19 relief. After we disarm this pandemic, the focus will shift to girl's health and education, and UBI. It will operate transparently, all flows tracked here: https://t.co/hVkUczDQmz",
"favorite_count": 353958,
"retweet_count": 62405,
"reply_count": 29511,
"quote_count": 19200,
"bookmark_count": 4932,
"views": { "state": "Enabled" },
"entities": {
"hashtags": [ { "indices": [58, 69], "text": "startsmall" } ],
"urls": [
{
"display_url": "docs.google.com/spreadsheets/d…",
"expanded_url": "https://docs.google.com/spreadsheets/d/1-eGxq2mMoEGwgSpNVL5j2sa6ToojZUZ-Zun8h2oBAR4",
"indices": [254, 277],
"url": "https://t.co/hVkUczDQmz"
}
],
"user_mentions": []
},
"is_quote_status": false,
"user_id_str": "12",
"author": { "screen_name": "jack", "name": "jack", "rest_id": "12", "followers_count": 7537418 }
}
```
| Field | Type | Description |
|---|---|---|
| `_input` | string | The handle or URL exactly as you supplied it. Use this to join results back to your input list. |
| `_source` | string | Internal tag for the path used to fetch the record. `S1-primary` means the fastest path; values starting with `S2-` indicate a fallback. |
| `_scrapedAt` | string | ISO-8601 UTC timestamp when the tweet was scraped. |
| `rest_id` / `id_str` | string | The tweet's unique numeric ID. |
| `conversation_id_str` | string | ID of the thread / conversation this tweet belongs to. |
| `created_at` | string | When the tweet was posted (X's native timestamp format, UTC). |
| `lang` | string | Detected language code (`en`, `id`, `ja`, …). |
| `full_text` | string | Complete tweet text. For long-form tweets (>280 chars) this holds the entire body, not the legacy 280-char truncation. |
| `display_text_range` | array | `[start, end]` character offsets of the visible tweet body (excludes trailing media links). |
| `favorite_count` | integer | Number of likes. |
| `retweet_count` | integer | Number of retweets. |
| `reply_count` | integer | Number of direct replies. |
| `quote_count` | integer | Number of quote tweets. |
| `bookmark_count` | integer | Number of bookmarks (when X exposes it). |
| `views` | object | `{ "count": "7990536", "state": "EnabledWithCount" }` — total view count and view-tracking state. For older tweets `count` may be absent and `state` is `"Enabled"`. |
| `entities` | object | Hashtags, user mentions, URLs, symbols, and smart tags, each with character offsets back into the tweet text. |
| `extended_entities.media` | array | When the tweet has media: photos, videos (with all bitrate variants), and GIFs — URLs, dimensions, durations, and types — passed through verbatim. |
| `note_tweet` | object | Present only on long-form tweets. Holds the rich-text body, inline media references, and rich-text formatting tags (bold, italic, etc.). |
| `is_quote_status` | boolean | `true` if this tweet quotes another tweet. |
| `source` | string | Client used to post (e.g. "Twitter Web App", "Twitter for iPhone"). |
| `user_id_str` | string | The author's numeric account ID. |
| `author` | object | Author snapshot: `screen_name`, `name`, `rest_id`, `description`, `followers_count`, `friends_count`, `statuses_count`, `media_count`, `listed_count`, `is_blue_verified`, `profile_banner_url`, etc. |
#### Error envelope
Handles that don't exist, are suspended, or return an empty anonymous timeline surface a structured error instead of crashing the run:
```json
{
"_input": "this-handle-does-not-exist-xyz",
"_error": "resolve_failed",
"_errorDetail": "could not resolve handle 'this-handle-does-not-exist-xyz' to user_id",
"_source": "S1-primary",
"_scrapedAt": "2026-05-18T11:04:21.570681+00:00"
}
```
Possible `_error` values: `resolve_failed` (handle does not exist or is unavailable), `empty_timeline` (account is private, suspended, or anonymous reads restricted), `exception` (transport-level failure after retries). Filter on `_error` to triage failed rows — errors are not billed.
### Pricing
This actor is billed per result: **$8.00 per 1,000 tweets**. Each successful tweet returned = 1 result. Error rows (`resolve_failed`, `empty_timeline`, `exception`) are not billed.
### Other Sosmed Actors
| Platform | Actor | Best for |
|---|---|---|
| Twitter / X | [X Account Scraper](https://apify.com/xtracto/x-account-scraper) | Profile metadata + counters for any handle |
| Twitter / X | [X Post Detail Scraper](https://apify.com/xtracto/x-post-detail-scraper) | Full single-tweet detail + replies tree |
| Twitter / X | [X Search Scraper](https://apify.com/xtracto/x-search-scraper) | Search tweets by keyword, hashtag, or query |
| Bluesky | [Bluesky Account Posts Scraper](https://apify.com/xtracto/bluesky-account-posts-scraper) | Recent posts from any Bluesky handle |
| Threads | [Threads Account Threads Scraper](https://apify.com/xtracto/threads-account-threads-scraper) | Recent threads from any Threads account |
| Instagram | [Instagram Account Posts Scraper](https://apify.com/xtracto/instagram-account-posts-scraper) | Recent posts (media + captions) for any IG account |
| Mastodon | [Mastodon Account Scraper](https://apify.com/xtracto/mastodon-account-scraper) | Profile + recent toots for any Mastodon handle |
Browse the full catalog at [apify.com/xtracto](https://apify.com/xtracto).
### Notes
- **Protected / private accounts** return one row with `_error: "empty_timeline"` and no tweets — anonymous access cannot see follower-only content.
- **Long tweets** (>280 characters, X Premium long-form) are returned with the full body in `full_text`; the rich-text shape (with bold/italic spans and inline-media references) is preserved under `note_tweet` for callers that need it.
- **Pinned tweets** appear first when present; chronological order of the remaining timeline is approximate.
- **Pagination** via the next-page cursor is followed automatically until `maxTweets` is reached or the timeline ends. Anonymous reads are typically capped near ~100 tweets per account before X stops returning a usable cursor.
- **Media tweets** carry the full `extended_entities.media` array verbatim (image URLs, video variants with bitrate, durations, sizes).
- For large jobs (>50 handles), enable Apify Proxy rotation to avoid per-IP rate limits.
# Actor input Schema
## `handles` (type: `array`):
List of X (Twitter) accounts to scrape tweets from. Accepts a bare handle (`jack`), an @-handle (`@jack`), or a full profile URL (`https://x.com/jack`). One dataset row per tweet.
## `maxTweets` (type: `integer`):
Maximum number of tweets to return per account. The actor stops as soon as this many tweets have been collected. Note: X serves up to ~100 tweets per anonymous page; higher values rely on automatic pagination and may stop early when no further page is available.
## `includeReplies` (type: `boolean`):
When enabled, the actor returns the tweets-and-replies timeline (the full conversational view). When disabled, only original tweets and retweets are returned. Enabling replies typically doubles the result volume.
## `proxyConfiguration` (type: `object`):
Apify Proxy settings. Datacenter proxies are sufficient for anonymous X timeline reads and are the cheapest option.
## Actor input object example
```json
{
"handles": [
"jack",
"elonmusk"
],
"maxTweets": 50,
"includeReplies": false,
"proxyConfiguration": {
"useApifyProxy": true
}
}
```
# 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 '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {
"handles": [
"jack",
"elonmusk"
],
"maxTweets": 50,
"includeReplies": false,
"proxyConfiguration": {
"useApifyProxy": true
}
};
// Run the Actor and wait for it to finish
const run = await client.actor("xtracto/x-account-tweets-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 '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = {
"handles": [
"jack",
"elonmusk",
],
"maxTweets": 50,
"includeReplies": False,
"proxyConfiguration": { "useApifyProxy": True },
}
# Run the Actor and wait for it to finish
run = client.actor("xtracto/x-account-tweets-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 '{
"handles": [
"jack",
"elonmusk"
],
"maxTweets": 50,
"includeReplies": false,
"proxyConfiguration": {
"useApifyProxy": true
}
}' |
apify call xtracto/x-account-tweets-scraper --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=xtracto/x-account-tweets-scraper",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "X (Twitter) Account Tweets Scraper",
"description": "Get recent tweets from any public X (Twitter) account by handle. Returns up to ~100 most recent tweets per account with text, media, counts (likes/retweets/replies/views), entities, and author metadata. HTTP-only, no login required.",
"version": "1.0",
"x-build-id": "N145bGGgOO6JJJDU4"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/xtracto~x-account-tweets-scraper/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-xtracto-x-account-tweets-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/acts/xtracto~x-account-tweets-scraper/runs": {
"post": {
"operationId": "runs-sync-xtracto-x-account-tweets-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor and returns information about the initiated run in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/runsResponseSchema"
}
}
}
}
}
}
},
"/acts/xtracto~x-account-tweets-scraper/run-sync": {
"post": {
"operationId": "run-sync-xtracto-x-account-tweets-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
},
"components": {
"schemas": {
"inputSchema": {
"type": "object",
"required": [
"handles"
],
"properties": {
"handles": {
"title": "X handles or profile URLs",
"type": "array",
"description": "List of X (Twitter) accounts to scrape tweets from. Accepts a bare handle (`jack`), an @-handle (`@jack`), or a full profile URL (`https://x.com/jack`). One dataset row per tweet.",
"items": {
"type": "string"
}
},
"maxTweets": {
"title": "Max tweets per account",
"minimum": 1,
"maximum": 500,
"type": "integer",
"description": "Maximum number of tweets to return per account. The actor stops as soon as this many tweets have been collected. Note: X serves up to ~100 tweets per anonymous page; higher values rely on automatic pagination and may stop early when no further page is available.",
"default": 50
},
"includeReplies": {
"title": "Include replies",
"type": "boolean",
"description": "When enabled, the actor returns the tweets-and-replies timeline (the full conversational view). When disabled, only original tweets and retweets are returned. Enabling replies typically doubles the result volume.",
"default": false
},
"proxyConfiguration": {
"title": "Proxy configuration",
"type": "object",
"description": "Apify Proxy settings. Datacenter proxies are sufficient for anonymous X timeline reads and are the cheapest option.",
"default": {
"useApifyProxy": true
}
}
}
},
"runsResponseSchema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"actId": {
"type": "string"
},
"userId": {
"type": "string"
},
"startedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"finishedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"status": {
"type": "string",
"example": "READY"
},
"meta": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"example": "API"
},
"userAgent": {
"type": "string"
}
}
},
"stats": {
"type": "object",
"properties": {
"inputBodyLen": {
"type": "integer",
"example": 2000
},
"rebootCount": {
"type": "integer",
"example": 0
},
"restartCount": {
"type": "integer",
"example": 0
},
"resurrectCount": {
"type": "integer",
"example": 0
},
"computeUnits": {
"type": "integer",
"example": 0
}
}
},
"options": {
"type": "object",
"properties": {
"build": {
"type": "string",
"example": "latest"
},
"timeoutSecs": {
"type": "integer",
"example": 300
},
"memoryMbytes": {
"type": "integer",
"example": 1024
},
"diskMbytes": {
"type": "integer",
"example": 2048
}
}
},
"buildId": {
"type": "string"
},
"defaultKeyValueStoreId": {
"type": "string"
},
"defaultDatasetId": {
"type": "string"
},
"defaultRequestQueueId": {
"type": "string"
},
"buildNumber": {
"type": "string",
"example": "1.0.0"
},
"containerUrl": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "integer",
"example": 1
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
},
"usageTotalUsd": {
"type": "number",
"example": 0.00005
},
"usageUsd": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "number",
"example": 0.00005
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
}
}
}
}
}
}
}
}
```