# Twitter Automation API (POST, REPLY, LIKE,  RETWEET, SCRAP)) (`itsoul/twitter-automation-api`) Actor

A powerful and flexible Twitter/X automation API built as an Apify Actor. This API enables you to scrape tweets, post new tweets, reply to tweets, like tweets, and retweet using Playwright browser automation.

- **URL**: https://apify.com/itsoul/twitter-automation-api.md
- **Developed by:** [Mahmoud Alhamdo](https://apify.com/itsoul) (community)
- **Categories:** Automation, Social media, Integrations
- **Security:** Limited permissions
- **Stats:** 30 total users, 5 monthly users, 100.0% runs succeeded, 5 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

$15.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Twitter Automation API

A powerful and flexible Twitter/X automation API built as an Apify Actor. This API enables you to scrape tweets, post new tweets, reply to tweets, like tweets, and retweet using browser automation.

### 🚀 Features

- **Multiple Modes**:
  - **User Mode**: Scrape latest tweets from any Twitter/X user profile
  - **Single Tweet Mode**: Extract data from a specific tweet URL
  - **Post Mode**: Publish a new tweet
  - **Reply Mode**: Reply to a specific tweet
  - **Like Mode**: Like a single tweet or multiple tweets (up to 5)
  - **Retweet Mode**: Retweet a single tweet or multiple tweets (up to 5)

- **Comprehensive Data Extraction**:
  - Tweet text content
  - Tweet ID and URL
  - Author username
  - Timestamp
  - Engagement metrics (likes, retweets, replies, views, bookmarks)
  - Image URLs (if present)
  - Image detection flag

- **Smart Features**:
  - Automatic pinned tweet filtering
  - Real-time data saving to dataset
  - Duplicate tweet detection
  - Automatic scrolling for pagination
  - Batch operations: Like or retweet up to 5 tweets at once
  - Configurable delays between actions to avoid rate limiting
  - Organized output views for different operation types

- **Robust & Reliable**:
  - Error handling and retry logic
  - Realistic browser behavior
  - Smart waiting mechanisms

### 📋 Input Parameters

#### Required

- **mode** (string): Operation mode - `"user"`, `"single"`, `"post"`, `"reply"`, `"like"`, or `"retweet"`

#### Authentication (Required for interaction modes)

- **ct0** (string): Twitter ct0 cookie for authentication (required for post, reply, like, retweet modes)
- **auth_token** (string): Twitter auth_token cookie for authentication (required for post, reply, like, retweet modes)

#### For User Mode (Scraping)

- **username** (string): Twitter username without @ (e.g., `"AlamawiEth"`)
- **maxTweets** (integer): Maximum number of tweets to scrape (1-1000, default: 3)
- **maxDaysOld** (integer): Only scrape tweets from the last N days (0 = no limit, default: 2)

#### For Single Tweet Mode

- **tweetUrl** (string): Full URL of the tweet to scrape

#### For Post Mode (Publish Tweet)

- **tweetText** (string, required): Text content of the tweet to post

#### For Reply Mode

- **replyTweetUrl** (string, required): URL of the tweet to reply to
- **replyText** (string, required): Text content of the reply

#### For Like Mode

- **tweetUrl** (string, optional): URL of a single tweet to like (use this OR tweetUrls)
- **tweetUrls** (array, optional): Array of tweet URLs to like (maximum 5 tweets). Use this for multiple likes.
- **delayBetweenActions** (integer, optional): Delay in seconds between processing each tweet when using multiple tweets (0-60, default: 2). Helps avoid rate limiting.

**Note**: Use either `tweetUrl` for a single tweet OR `tweetUrls` for multiple tweets (up to 5).

#### For Retweet Mode

- **tweetUrl** (string, optional): URL of a single tweet to retweet (use this OR tweetUrls)
- **tweetUrls** (array, optional): Array of tweet URLs to retweet (maximum 5 tweets). Use this for multiple retweets.
- **delayBetweenActions** (integer, optional): Delay in seconds between processing each tweet when using multiple tweets (0-60, default: 2). Helps avoid rate limiting.

**Note**: Use either `tweetUrl` for a single tweet OR `tweetUrls` for multiple tweets (up to 5).

### 📝 Example Inputs

#### User Mode

```json
{
  "mode": "user",
  "username": "apify",
  "maxTweets": 50,
  "maxDaysOld": 5
}
```

#### Post Tweet Mode

```json
{
  "mode": "post",
  "tweetText": "Hello from Apify Actor! 🚀",
  "ct0": "your_ct0_cookie_value",
  "auth_token": "your_auth_token_value"
}
```

#### Reply Mode

```json
{
  "mode": "reply",
  "replyTweetUrl": "https://x.com/user1/status/1234567890",
  "replyText": "Great tweet! Thanks for sharing.",
  "ct0": "your_ct0_cookie_value",
  "auth_token": "your_auth_token_value"
}
```

#### Like Mode - Single Tweet

```json
{
  "mode": "like",
  "tweetUrl": "https://x.com/user1/status/1234567890",
  "ct0": "your_ct0_cookie_value",
  "auth_token": "your_auth_token_value"
}
```

#### Like Mode - Multiple Tweets

```json
{
  "mode": "like",
  "tweetUrls": [
    "https://x.com/user1/status/1234567890",
    "https://x.com/user2/status/0987654321",
    "https://x.com/user3/status/1122334455"
  ],
  "delayBetweenActions": 3,
  "ct0": "your_ct0_cookie_value",
  "auth_token": "your_auth_token_value"
}
```

#### Retweet Mode - Multiple Tweets

```json
{
  "mode": "retweet",
  "tweetUrls": [
    "https://x.com/user1/status/1234567890",
    "https://x.com/user2/status/0987654321"
  ],
  "delayBetweenActions": 3,
  "ct0": "your_ct0_cookie_value",
  "auth_token": "your_auth_token_value"
}
```

### 📊 Output Schema

The Actor provides organized output views in Apify Console for different operation types:

- **📊 Overview**: Complete view of all operations
- **✍️ Posted Tweets**: View for posted tweets
- **💬 Replies**: View for replies
- **❤️ Likes**: View for liked tweets
- **🔄 Retweets**: View for retweeted tweets
- **🔍 Scraped Tweets**: View for scraped tweets

#### For Scraping Modes (user, single)

Each tweet in the dataset contains:

```json
{
  "tweetId": "1987766870477619331",
  "text": "Tweet text content...",
  "username": "AlamawiEth",
  "timestamp": "2025-11-10T06:18:47.000Z",
  "url": "https://x.com/user1/status/1234567890",
  "likes": 59,
  "retweets": 4,
  "replies": 7,
  "views": 24796,
  "bookmarks": 0,
  "images": [
    "https://pbs.twimg.com/media/XXX?format=jpg&name=medium"
  ],
  "hasImages": true,
  "scrapedAt": "2025-11-12T05:00:15.702372"
}
```

#### For Post Mode

```json
{
  "success": true,
  "mode": "post",
  "tweetId": "1987766870477619331",
  "url": "https://x.com/user1/status/1234567890",
  "text": "Tweet text...",
  "postedAt": "2025-11-12T05:00:15.702372"
}
```

#### For Reply Mode

```json
{
  "success": true,
  "mode": "reply",
  "originalTweetUrl": "https://x.com/user1/status/1234567890",
  "replyId": "1987766870477619331",
  "replyUrl": "https://x.com/user1/status/1987766870477619331",
  "replyText": "Reply text...",
  "repliedAt": "2025-11-12T05:00:15.702372"
}
```

#### For Like/Retweet Mode

**Single Tweet:**

```json
{
  "success": true,
  "mode": "like",
  "tweetUrl": "https://x.com/user1/status/1234567890",
  "action": "liked",
  "likedAt": "2025-11-12T05:00:15.702372"
}
```

**Multiple Tweets:**

```json
{
  "success": true,
  "mode": "like",
  "tweetUrl": "https://x.com/user1/status/1234567890",
  "tweetIndex": 1,
  "totalTweets": 3,
  "action": "liked",
  "likedAt": "2025-11-12T05:00:15.702372"
}
```

### 🔐 Authentication Setup

Authentication cookies are **required** for all interaction modes (post, reply, like, retweet) and **recommended** for scraping modes.

#### How to Get Cookies

1. **Install Cookie Editor Extension**:
   - Install from [Chrome Web Store](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm)

2. **Login to Twitter/X**:
   - Go to https://x.com and login to your account

3. **Extract Cookies**:
   - Open Cookie Editor extension
   - Search for `ct0` and copy its value
   - Search for `auth_token` and copy its value

4. **Use in Actor Input**:
   - Paste the values in the `ct0` and `auth_token` fields

#### ⚠️ Security Warning

- **Never share your cookies** with anyone you don't trust
- Cookies contain sensitive login information
- Anyone with your cookies can access your account
- Only use cookies in secure environments
- Consider using a separate Twitter account for automation

#### Benefits of Using Cookies

- ✅ Access to advanced search with date filters
- ✅ Better filtering of recent tweets
- ✅ More reliable scraping results
- ✅ Required for all interaction modes

### 📖 How It Works

#### User Mode

1. Navigate to user profile or use advanced search (if authenticated)
2. Extract tweets one by one
3. Filter by date if `maxDaysOld` is set
4. Skip pinned tweets automatically
5. Save to dataset in real-time
6. Continue until reaching `maxTweets` or no more tweets available

#### Post Mode

1. Navigate to Twitter home page
2. Enter tweet text
3. Submit tweet
4. Return posted tweet data (URL, ID, timestamp)

#### Reply Mode

1. Navigate to the tweet URL
2. Click reply button
3. Enter reply text
4. Submit reply
5. Return reply confirmation with URL and ID

#### Like/Retweet Mode

**Single Tweet:**

1. Navigate to the tweet URL
2. Click like/retweet button
3. Confirm action (for retweet)
4. Return confirmation

**Multiple Tweets:**

1. Process each tweet sequentially
2. Wait for configured delay between actions
3. Return results with index and total count
4. Continue until all tweets are processed

### 🎯 Use Cases

- **Social Media Monitoring**: Track tweets from specific accounts
- **Content Analysis**: Analyze tweet engagement metrics
- **Image Collection**: Extract images from tweets
- **Data Research**: Collect tweet data for analysis
- **Brand Monitoring**: Monitor mentions and engagement
- **Automated Posting**: Schedule and post tweets automatically
- **Engagement Automation**: Automatically like, retweet, or reply to tweets
- **Social Media Management**: Manage Twitter account interactions programmatically
- **Batch Operations**: Process multiple tweets efficiently with configurable delays

### 🔒 Privacy & Compliance

- This Actor respects Twitter/X's public data
- Authentication (cookies) is **required** for interaction modes (post, reply, like, retweet)
- Authentication (cookies) is optional but recommended for scraping modes (user, single)
- Private profiles will not be accessible
- **Never share your cookies** - they contain sensitive login information
- **Important**: All interaction modes require valid authentication cookies
- Please review Twitter/X Terms of Service before use
- Be mindful of rate limits when using interaction modes

**Note**: This Actor is designed for educational and research purposes. Always comply with Twitter/X Terms of Service and applicable laws when scraping data.

# Actor input Schema

## `ct0` (type: `string`):

Twitter ct0 cookie value for authentication. Required for all interaction modes (post, reply, like, retweet) and recommended for scraping modes. Get this from your browser cookies after logging into Twitter/X. Consider using Secret Inputs in Apify Console for sensitive data.

## `auth_token` (type: `string`):

Twitter auth_token cookie value for authentication. Required for all interaction modes (post, reply, like, retweet) and recommended for scraping modes. Get this from your browser cookies after logging into Twitter/X. Consider using Secret Inputs in Apify Console for sensitive data.

## `mode` (type: `string`):

Choose the operation mode. This determines which other fields are required.

## `tweetUrl` (type: `string`):

Full URL of a single tweet. Required for modes: 'single', 'like' (single tweet), or 'retweet' (single tweet).

## `tweetUrls` (type: `array`):

Array of tweet URLs (maximum 5). Use this for liking or retweeting multiple tweets. Required when mode is 'like' or 'retweet' and you want to process multiple tweets. Alternative: use 'tweetUrl' for a single tweet.

## `delayBetweenActions` (type: `integer`):

Delay in seconds between processing each tweet when using 'tweetUrls'. Helps avoid rate limiting. Only used when processing multiple tweets.

## `username` (type: `string`):

Twitter username without @ symbol. Required when mode is 'user'.

## `maxTweets` (type: `integer`):

Maximum number of tweets to scrape. Only used when mode is 'user'.

## `maxDaysOld` (type: `integer`):

Only scrape tweets from the last N days. Set to 0 for no limit. Only used when mode is 'user'.

## `tweetText` (type: `string`):

Text content for the new tweet. Required when mode is 'post'.

## `replyTweetUrl` (type: `string`):

URL of the tweet to reply to. Required when mode is 'reply'.

## `replyText` (type: `string`):

Text content for the reply. Required when mode is 'reply'.

## Actor input object example

```json
{
  "ct0": "",
  "auth_token": "",
  "mode": "user",
  "tweetUrl": "https://x.com/AlamawiEth/status/2005679650551533782",
  "tweetUrls": [
    "https://x.com/AlamawiEth/status/2005679650551533782"
  ],
  "delayBetweenActions": 2,
  "username": "",
  "maxTweets": 3,
  "maxDaysOld": 2,
  "tweetText": "",
  "replyTweetUrl": "",
  "replyText": ""
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

## `posted_tweets` (type: `string`):

No description

## `replies` (type: `string`):

No description

## `likes` (type: `string`):

No description

## `retweets` (type: `string`):

No description

## `scraped_tweets` (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 = {
    "tweetUrl": "https://x.com/AlamawiEth/status/2005679650551533782",
    "tweetUrls": [
        "https://x.com/AlamawiEth/status/2005679650551533782"
    ],
    "username": ""
};

// Run the Actor and wait for it to finish
const run = await client.actor("itsoul/twitter-automation-api").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 = {
    "tweetUrl": "https://x.com/AlamawiEth/status/2005679650551533782",
    "tweetUrls": ["https://x.com/AlamawiEth/status/2005679650551533782"],
    "username": "",
}

# Run the Actor and wait for it to finish
run = client.actor("itsoul/twitter-automation-api").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 '{
  "tweetUrl": "https://x.com/AlamawiEth/status/2005679650551533782",
  "tweetUrls": [
    "https://x.com/AlamawiEth/status/2005679650551533782"
  ],
  "username": ""
}' |
apify call itsoul/twitter-automation-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,itsoul/twitter-automation-api"
        }
    }
}
```

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/gyIqnt7XXX1cIXGva/builds/MuMNrm6e7tbgiS9hY/openapi.json