# X (twitter) User Timeline/Tweets (`datamagnet/x-twitter-user-timeline-tweets`) Actor
Fetch the latest tweets from a Twitter/X user by username.
- **URL**: https://apify.com/datamagnet/x-twitter-user-timeline-tweets.md
- **Developed by:** [Datamagnet](https://apify.com/datamagnet) (community)
- **Categories:** Social media, Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet
## Pricing
from $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.
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
## Twitter User Timeline Scraper
Twitter User Timeline Scraper helps you quickly collect the latest tweets from any public X user by username. It is ideal for marketers, researchers, analysts, journalists, and social media teams who need fresh Twitter/X timeline data without manual scrolling. Use it to capture tweet text, timestamps, engagement counts, media, author details, and pagination data in one place. If you want a simple way to monitor a public profile and export tweet data for analysis, this actor gives you a fast, reliable starting point.
### Key Features
- **Extract** the newest tweets from a single public X account by username.
- **Collect** older tweets automatically when you want to go beyond the first page of results.
- **Preserve** the timeline data exactly as returned, so you can review the original tweet details and metadata.
- **Capture** engagement signals such as likes, replies, reposts, quotes, bookmarks, and views.
- **Include** rich tweet context like author information, media, mentions, and retweeted content when available.
- **Support** ongoing monitoring workflows by letting you continue from a saved cursor.
- **Export** results in a format that is easy to analyze, share, or load into your reporting workflow.
### Use Cases
#### Social Media Monitoring
Social media managers use this actor to keep an eye on a brand, executive, competitor, or creator account. By collecting tweet text, created time, and engagement metrics like favorites, replies, retweets, and views, they can spot what content is gaining traction and react faster.
#### Competitor Research
Growth teams and analysts can compare how different public accounts communicate, post frequency, and audience response. Fields such as tweet text, source, language, and engagement counts help them understand messaging patterns and identify content that performs well.
#### Content Performance Analysis
Creators and marketing teams often want to know which posts drive the most attention. This actor returns the raw tweet data, including bookmarks, quotes, replies, retweets, and views, so teams can review performance trends and build better content strategies.
#### Media and Journalism Research
Journalists and researchers can use the timeline data to document what a public figure posted and when they posted it. The created_at timestamp, conversation_id, and author details make it easier to verify timelines, track public statements, and reference original posts accurately.
#### Audience and Brand Intelligence
Brand and communications teams can study how a public account presents itself and how audiences respond. The output includes author profile details, profile image, follower count, pinned posts, and tweet metadata, which helps teams understand account positioning and public reach.
#### Repost and Mention Tracking
Teams that track conversations around a topic can inspect retweeted posts and user mentions inside the timeline data. This is useful for identifying which accounts are being amplified, who is being mentioned, and how a public profile participates in broader discussions.
### Input
| Field | Type | Required | Description | Example |
|---|---|---:|---|---|
| cursor | string | No | A saved position that lets you continue from a previous page of results. | cursor123 |
| screenname | string | string | Yes | The Twitter/X username whose timeline you want to fetch. | elonmusk |
| max_results | integer | No | The maximum number of tweets to collect before stopping. | 100 |
### Output
| Field | Type | Description |
|---|---|---|
| tweet_id | string | The unique ID of the tweet, useful for tracking or referencing a specific post. |
| bookmarks | number | How many times the tweet was bookmarked, which can indicate strong interest. |
| created_at | string | The date and time the tweet was posted. |
| favorites | number | How many likes the tweet received. |
| text | string | The tweet content exactly as posted, including links or shortened text. |
| lang | string | The language of the tweet. |
| source | string | The app or device used to publish the tweet. |
| views | string | The number of views shown for the tweet. |
| quotes | number | How many times the tweet was quoted. |
| replies | number | How many replies the tweet received. |
| retweets | number | How many times the tweet was reposted. |
| conversation_id | string | The ID that groups the tweet with its conversation thread. |
| media | object | Media attached to the tweet, such as photos or other visual content. |
| author | object | Basic information about the account that posted the tweet. |
| type | string | The kind of timeline item, such as a normal post or a pinned post. |
| user | object | Profile details for the account whose timeline was collected. |
| entities | object | Extra tweet details such as mentioned accounts, when available. |
| retweeted | object | Information about the original tweet when the item is a repost. |
| retweeted_tweet | object | The full details of the original tweet that was reposted, when available. |
### Sample Output
```json
{
"tweet_id": "2073311697474076672",
"bookmarks": 6761,
"created_at": "Sat Jul 04 07:43:23 +0000 2026",
"favorites": 394954,
"text": "God Bless America https://t.co/ffqS5KzKB5",
"lang": "en",
"source": "Twitter for iPhone",
"views": "13075094",
"quotes": 1997,
"replies": 21360,
"retweets": 32416,
"conversation_id": "2073311697474076672",
"media": {
"photo": [
{
"media_url_https": "https://pbs.twimg.com/media/HMXiAEJaoAAR4xI.jpg",
"id": "2073311694215094272",
"sizes": {
"h": 797,
"w": 1152
}
}
]
},
"author": {
"rest_id": "44196397",
"name": "Elon Musk",
"screen_name": "elonmusk",
"avatar": "https://pbs.twimg.com/profile_images/2053244804520427520/m8mdWZCG_normal.jpg",
"followers_count": 240728548,
"blue_verified": true
},
"type": "pinned_post",
"user": {
"status": "active",
"profile": null,
"rest_id": "44196397",
"blue_verified": true,
"verification_type": null,
"affiliates": {
"label": {
"badge": {
"url": "https://pbs.twimg.com/profile_images/1955359038532653056/OSHY3ewP_bigger.jpg"
},
"description": "X",
"url": {
"url": "https://twitter.com/X",
"urlType": "DeepLink"
},
"userLabelDisplayType": "Badge",
"userLabelType": "BusinessLabel"
}
},
"business_account": [],
"avatar": "https://pbs.twimg.com/profile_images/2053244804520427520/m8mdWZCG_normal.jpg",
"header_image": "https://pbs.twimg.com/profile_banners/44196397/1774145451",
"desc": "Starmind",
"name": "Elon Musk",
"protected": false,
"location": "",
"friends": 1366,
"sub_count": 240728408,
"statuses_count": 105263,
"media_count": 4589,
"created_at": "Tue Jun 02 20:12:29 +0000 2009",
"pinned_tweet_ids_str": [
"2073311697474076672"
],
"id": "44196397"
}
}
````
### How It Works
1. You enter the public X username you want to review.
2. The actor fetches the latest tweets from that account automatically.
3. If you want more history, it continues loading older tweets until it reaches your limit.
4. The actor keeps the tweet data in its original structure so you can inspect it without losing detail.
5. When the run finishes, you can review and export the results for your workflow.
### Getting Started
Getting started is simple and does not require coding knowledge. Click **Try for free**, enter the username you want to collect, choose how many tweets you want, and click **Run**. The actor will gather the timeline data for you and return it in a format that is easy to work with. You can download the results as JSON, CSV, or Excel depending on how you want to analyze or share them.
### Frequently Asked Questions
#### Do I need technical skills?
No. This actor is designed for business users, researchers, and marketers who want tweet data without building anything themselves. Just enter a username, choose your limit, and run it.
#### How fast does it run?
Speed depends on how many tweets you request and whether the actor needs to continue loading older posts. Smaller requests usually finish quickly, while larger timelines take longer because more data is being collected.
#### What format is the output?
The results are available in formats that are easy to use for reporting and analysis, including JSON, CSV, and Excel. The actor also preserves the original timeline structure so you can keep the full context of each tweet.
#### Is this legal to use?
This actor is intended for collecting publicly available timeline data from public X accounts. You should always make sure your use complies with applicable laws, platform rules, and your own internal policies, especially if you plan to store, analyze, or republish the data.
#### Can I schedule it to run automatically?
Yes. You can use Apify scheduling and automation features to run it on a regular basis. That makes it easy to monitor a public account over time and keep your dataset fresh without manual work.
# Actor input Schema
## `screenname` (type: `string`):
Twitter/X username whose timeline you want to fetch.
## `max_results` (type: `integer`):
Maximum number of tweets to collect before stopping.
## Actor input object example
```json
{
"screenname": "elonmusk",
"max_results": 10
}
```
# 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 = {
"screenname": "elonmusk"
};
// Run the Actor and wait for it to finish
const run = await client.actor("datamagnet/x-twitter-user-timeline-tweets").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 = { "screenname": "elonmusk" }
# Run the Actor and wait for it to finish
run = client.actor("datamagnet/x-twitter-user-timeline-tweets").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 '{
"screenname": "elonmusk"
}' |
apify call datamagnet/x-twitter-user-timeline-tweets --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=datamagnet/x-twitter-user-timeline-tweets",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "X (twitter) User Timeline/Tweets",
"description": "Fetch the latest tweets from a Twitter/X user by username.",
"version": "0.0",
"x-build-id": "LMDtwJo8WWUOlKgav"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/datamagnet~x-twitter-user-timeline-tweets/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-datamagnet-x-twitter-user-timeline-tweets",
"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/datamagnet~x-twitter-user-timeline-tweets/runs": {
"post": {
"operationId": "runs-sync-datamagnet-x-twitter-user-timeline-tweets",
"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/datamagnet~x-twitter-user-timeline-tweets/run-sync": {
"post": {
"operationId": "run-sync-datamagnet-x-twitter-user-timeline-tweets",
"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": [
"screenname"
],
"properties": {
"screenname": {
"title": "Username",
"type": "string",
"description": "Twitter/X username whose timeline you want to fetch."
},
"max_results": {
"title": "Max results",
"type": "integer",
"description": "Maximum number of tweets to collect before stopping.",
"default": 10
}
}
},
"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
}
}
}
}
}
}
}
}
}
}
```