X/Twitter Post Cleaner

Bulk delete tweets from your X/Twitter account. Clean up old tweets, retweets, and likes with powerful filtering.

Features

• Date range filtering -- delete tweets before/after a specific date
• Keyword filtering -- only delete tweets containing specific words
• Preserve keywords -- protect tweets containing specific words from deletion
• Delete modes -- tweets only, retweets only, likes (unlike), or all (tweets + retweets + unlikes)
• Media filter -- only delete tweets with images/videos
• Archive support -- upload your Twitter archive to delete tweets older than the API's ~3,200 limit
• Dry run -- preview what would be deleted without actually deleting
• Safety cap -- set a maximum number of deletions per run
• Webhook -- get notified when the cleanup finishes

Quick Start

1. Get your API credentials (see below)
2. Run with dryRun: true first to preview what will be deleted
3. Once you're happy, set dryRun: false and run again

Getting Your API Credentials

You need a Twitter/X Developer account with an app that has OAuth 1.0a enabled.

Step-by-step:

1. Go to developer.x.com and sign in with the X account you want to clean
2. Click Developer Portal (top right)
3. If you don't have a project yet, create one (any name is fine)
4. Create an App inside the project
5. In your App settings:
   • Under User authentication settings, click Set up
   • Enable OAuth 1.0a
   • Set App permissions to Read and Write (IMPORTANT -- "Read only" won't work)
   • Set callback URL to https://localhost (it won't be used, but it's required)
   • Save
6. Go to Keys and Tokens tab and generate/regenerate:
   • API Key (also called Consumer Key) -- copy it
   • API Key Secret (also called Consumer Secret) -- copy it
   • Access Token -- copy it
   • Access Token Secret -- copy it
7. Paste all four into this actor's input fields

Which X/Twitter API tier do I need?

• Free tier: Can delete tweets and unlike, but CANNOT read your tweet timeline. You will need to use the Archive Upload method (see below) to provide the list of tweet IDs.
• Basic tier ($200/mo): Can read your timeline AND delete. Works fully without archive upload, but limited to ~3,200 most recent tweets.
• Pro tier ($5,000/mo): Higher rate limits and full timeline access.

Recommendation for most users: Use the Free tier + Archive Upload. It costs nothing for the API and covers your entire history.

Deleting Old Tweets (Archive Upload)

The Twitter API only returns your most recent ~3,200 tweets. If you have older tweets (or are on the Free tier), you need your archive:

1. On X, go to Settings and privacy > Your account > Download an archive of your data
2. Confirm your identity (may require email/phone verification)
3. Click Request archive
4. Wait for the email from X (usually 24-48 hours, sometimes longer)
5. Download and unzip the .zip file
6. Navigate to the data/ folder inside the archive
7. Open tweets.js in any text editor (Notepad, VS Code, TextEdit, etc.)
8. Select All (Ctrl+A / Cmd+A) and Copy (Ctrl+C / Cmd+C)
9. Paste into the Tweet Archive input field in this actor

The file starts with window.YTD.tweet.part0 = [...] -- that's expected, the actor handles it.

Warning: Archive files can be very large (10MB+) for accounts with thousands of tweets. If your archive is too large for the textarea, try splitting it or filtering in a text editor first.

Usage Examples

Delete everything before 2024 (with archive)

{
  "apiKey": "your-key",
  "apiKeySecret": "your-secret",
  "accessToken": "your-token",
  "accessTokenSecret": "your-token-secret",
  "deleteMode": "all",
  "beforeDate": "2024-01-01",
  "tweetArchiveJson": "(paste your tweets.js contents here)",
  "maxDeletions": 0
}

Delete only retweets

{
  "deleteMode": "retweets",
  "maxDeletions": 500
}

Dry run to preview (no deletions)

{
  "deleteMode": "all",
  "beforeDate": "2020-01-01",
  "dryRun": true
}

Delete tweets containing a keyword but keep pinned

{
  "deleteMode": "tweets",
  "keywordFilter": "embarrassing",
  "preserveKeyword": "pinned",
  "maxDeletions": 100
}

Nuclear option -- delete absolutely everything

{
  "deleteMode": "all",
  "maxDeletions": 0,
  "tweetArchiveJson": "(paste your tweets.js contents here)"
}

Rate Limits

The Twitter API enforces strict rate limits on deletions:

Tier	Delete Rate	Timeline Read Rate
Free ($0)	50 deletes / 15 min	Not available (use archive)
Basic ($200/mo)	50 deletes / 15 min	100 reads / 15 min
Pro ($5,000/mo)	300 deletes / 15 min	900 reads / 15 min

The actor automatically detects rate limits and pauses until the reset window. You'll see log messages like "Rate limit hit. Waiting 14.5 minutes until reset..."

Time estimates:

• 100 tweets: ~5 minutes
• 1,000 tweets: ~1 hour
• 5,000 tweets: ~5 hours
• 10,000 tweets: ~10 hours

For large jobs, increase the actor timeout in Run Options (default: 1 hour, max: 24 hours).

Pricing

Pay-per-event billing -- you only pay for successful actions:

Action	Price
Tweet/retweet deleted	$0.01
Tweet unliked	$0.005

Free actions (no charge):

• Dry runs (preview mode)
• Skipped tweets (didn't match filters)
• Already-deleted tweets (404 from API)
• Failed deletions (errors)

Output

Each run produces a dataset with:

• One row per processed tweet: tweet ID, text preview (first 200 chars), date, deleted (true/false), error message
• A summary row at the end with totals: totalFound, matchingFilters, deleted, errors

Troubleshooting

"Failed to get user info" / 401 Unauthorized

• Your API credentials are wrong or expired. Regenerate them at developer.x.com.
• Make sure you're using OAuth 1.0a User Context tokens, not OAuth 2.0 Bearer tokens.
• Verify your app has Read and Write permissions (not just Read).

"Tweet fetch returned 403"

• Your X Developer account is on the Free tier, which doesn't allow reading timelines. Use the Archive Upload method instead.

Deletions are very slow

• This is normal. Twitter limits deletions to 50 per 15 minutes on Free/Basic tiers. The actor handles this automatically by pausing and resuming.

Some tweets weren't deleted

• Tweets from archived/suspended accounts or tweets that have already been deleted will return errors. These are logged but don't stop the run.
• If you're using the API (no archive), only your most recent ~3,200 tweets are accessible. Use archive upload for older tweets.

Archive file is too large

• Open tweets.js in a text editor, remove entries you want to keep, and paste the rest. Each tweet is a JSON object in the array -- you can safely remove array elements.

Safety Tips

1. Always start with a dry run (dryRun: true) to verify your filters match the right tweets
2. Start with a small maxDeletions (e.g., 50) before setting to 0 (unlimited)
3. Download your archive BEFORE bulk deleting -- it's your only backup
4. Use preserveKeyword to protect important tweets from accidental deletion
5. Deletions are permanent -- there is no undo. X/Twitter does not offer tweet recovery.