Twitter/X

Website: https://twitter.com (https://x.com) CLI Tool: twurl, twitter-api-client (Python) Authentication: OAuth 2.0, API Keys required

Description

Twitter/X is a real-time social media platform for posting and reading short messages (tweets). AI agents can interact with Twitter via the official API v2, using CLI tools like twurl or programmatic access through SDKs. Note: API access requires developer account approval and comes with rate limits and costs.

Commands

Authentication Setup

# Install twurl (Ruby-based Twitter CLI)
gem install twurl

# Authenticate with API keys
twurl authorize --consumer-key <key> --consumer-secret <secret>

Setup authentication for Twitter API access. Required before making any API calls.

Post Tweet

# Using twurl
twurl -d "status=Your tweet text here" /1.1/statuses/update.json

# Using Python (tweepy)
python -c "import tweepy; client = tweepy.Client(bearer_token='TOKEN'); client.create_tweet(text='Your tweet')"

Post a new tweet. Text must be 280 characters or less. Use escape sequences for special characters.

Post Tweet with Media

# Upload media first
twurl -H upload.twitter.com "/1.1/media/upload.json" -d "" -f image.jpg -F media

# Then post tweet with media_ids
twurl -d "status=Check this out!&media_ids=MEDIA_ID" /1.1/statuses/update.json

Post a tweet with images or videos. Upload media first to get media_id, then attach to tweet.

Read Timeline

# Get home timeline
twurl /1.1/statuses/home_timeline.json?count=20

# Get user timeline
twurl "/1.1/statuses/user_timeline.json?screen_name=username&count=20"

Read tweets from your timeline or a specific user's timeline. Returns JSON array of tweets.

Read Single Tweet

twurl "/1.1/statuses/show.json?id=TWEET_ID"

Get details of a specific tweet by its ID. Returns full tweet object with metadata.

Search Tweets

# Recent search (v2 API)
twurl "/2/tweets/search/recent?query=AI%20agents&max_results=10"

# v1.1 search
twurl "/1.1/search/tweets.json?q=worldbook&count=20&result_type=recent"

Search for tweets matching a query. Use URL encoding for spaces and special characters. v2 API requires Essential access or higher.

Get User Info

# By username (v2)
twurl "/2/users/by/username/username"

# By user ID (v1.1)
twurl "/1.1/users/show.json?screen_name=username"

Get user profile information including follower counts, bio, and verification status.

Get Followers

twurl "/1.1/followers/list.json?screen_name=username&count=20"

List followers of a user. Returns paginated results with cursor for next page.

Get Following

twurl "/1.1/friends/list.json?screen_name=username&count=20"

List accounts that a user is following. Paginated with cursor support.

Like Tweet

# Like (v2)
twurl -X POST -d '{"tweet_id":"TWEET_ID"}' "/2/users/USER_ID/likes"

# Like (v1.1)
twurl -d "id=TWEET_ID" /1.1/favorites/create.json

Like (favorite) a tweet. Requires tweet ID and your user ID for v2.

Retweet

# Retweet (v2)
twurl -X POST "/2/users/USER_ID/retweets" -d '{"tweet_id":"TWEET_ID"}'

# Retweet (v1.1)
twurl -d "id=TWEET_ID" /1.1/statuses/retweet/TWEET_ID.json

Retweet another user's tweet. Increases tweet visibility.

Delete Tweet

twurl -X DELETE "/1.1/statuses/destroy/TWEET_ID.json"

Delete your own tweet. Cannot delete tweets from other users.

Get Trending Topics

# Global trends
twurl "/1.1/trends/place.json?id=1"

# Trends by location (WOEID)
twurl "/1.1/trends/place.json?id=2459115"  # New York

Get current trending topics. Use WOEID (Where On Earth ID) for location-specific trends.

Send Direct Message

twurl -A "Content-Type: application/json" -d '{"event":{"type":"message_create","message_create":{"target":{"recipient_id":"USER_ID"},"message_data":{"text":"Hello!"}}}}' /1.1/direct_messages/events/new.json

Send a direct message to a user. Requires recipient's user ID.

Get Rate Limit Status

twurl "/1.1/application/rate_limit_status.json"

Check current API rate limit status. Shows remaining requests per endpoint and reset time.

Examples

Simple Tweet Workflow

# Post a tweet
twurl -d "status=Hello from AI agent! 🤖" /1.1/statuses/update.json

# Verify it was posted
twurl /1.1/statuses/user_timeline.json?count=1

Search and Like Workflow

# Search for tweets about AI
twurl "/1.1/search/tweets.json?q=artificial%20intelligence&count=10&result_type=recent"

# Extract tweet ID from results (using jq)
TWEET_ID=$(twurl "/1.1/search/tweets.json?q=AI&count=1" | jq -r '.statuses[0].id_str')

# Like the tweet
twurl -d "id=$TWEET_ID" /1.1/favorites/create.json

Monitor User Activity

# Get user's recent tweets
twurl "/1.1/statuses/user_timeline.json?screen_name=elonmusk&count=5" | jq '.[] | {text: .text, created: .created_at}'

# Get user's followers count
twurl "/1.1/users/show.json?screen_name=elonmusk" | jq '{name: .name, followers: .followers_count}'

Thread Creation Workflow

# Post first tweet
RESPONSE=$(twurl -d "status=1/3 This is the start of a thread..." /1.1/statuses/update.json)
TWEET_ID=$(echo $RESPONSE | jq -r '.id_str')

# Reply to create thread
twurl -d "status=2/3 Continuing the thread...&in_reply_to_status_id=$TWEET_ID" /1.1/statuses/update.json

Scheduled Tweet Check

# Check timeline every hour for mentions
while true; do
  twurl "/1.1/statuses/mentions_timeline.json?count=5" | jq '.[] | {user: .user.screen_name, text: .text}'
  sleep 3600
done

Engagement Analysis

# Get your latest tweet stats
twurl /1.1/statuses/user_timeline.json?count=1 | jq '.[0] | {
  text: .text,
  retweets: .retweet_count,
  likes: .favorite_count,
  replies: .reply_count
}'

Python SDK Example (tweepy)

import tweepy

# Initialize client with bearer token
client = tweepy.Client(bearer_token='YOUR_BEARER_TOKEN')

# Post tweet
response = client.create_tweet(text='Hello from Python!')
print(f"Tweet ID: {response.data['id']}")

# Search recent tweets
tweets = client.search_recent_tweets(query='AI agents', max_results=10)
for tweet in tweets.data:
    print(f"{tweet.text}\n")

Bulk Operations Example

# Search and save tweets to file
twurl "/1.1/search/tweets.json?q=worldbook&count=100" > tweets.json

# Process and filter
jq '.statuses[] | select(.retweet_count > 10) | {text: .text, rt: .retweet_count}' tweets.json

# Like all results
jq -r '.statuses[].id_str' tweets.json | while read id; do
  twurl -d "id=$id" /1.1/favorites/create.json
  sleep 1  # Rate limit protection
done

Notes

• API Access Tiers: Twitter has multiple API access levels:
• Free: Very limited (500K tweets/month read, 1.7K posts/month)
• Basic ($100/mo): 10K tweets/month read, 3K posts/month
• Pro ($5000/mo): 1M tweets/month read, 300K posts/month

• Enterprise: Custom pricing for unlimited access

• Rate Limits: Strictly enforced per endpoint:

• Tweet posting: 300 tweets per 3 hours (user), 50 per 24 hours (app)
• Timeline reading: 900 requests per 15 minutes
• Search: 180 requests per 15 minutes (v1.1), 450 per 15 min (v2 with Pro)

• Check limits: twurl /1.1/application/rate_limit_status.json

• Authentication Methods:

• OAuth 2.0 Bearer Token: Read-only operations
• OAuth 1.0a: Required for posting and user context operations
• API Key + Secret: App-level authentication

• Access Token + Secret: User-level authentication

• Character Limits:

• Standard tweets: 280 characters
• Twitter Blue subscribers: 4,000 characters (with verified status)
• URLs count as 23 characters regardless of actual length

• Media attachments don't count toward character limit

• JSON Output: All API responses are JSON. Use jq for parsing and filtering in bash

• Parse text: jq '.text'
• Parse arrays: jq '.[]'

• Filter: jq 'select(.retweet_count > 10)'

• Error Handling: Common error codes:

• 401: Authentication failed
• 403: Forbidden (possibly rate limited or suspended)
• 404: Resource not found (user or tweet doesn't exist)
• 429: Rate limit exceeded

• 503: Service unavailable (Twitter is down)

• Best Practices for AI Agents:

• Always check rate limits before batch operations
• Use exponential backoff when rate limited
• Cache user IDs to avoid repeated lookups
• Respect user privacy settings (protected accounts)
• Monitor for 403 errors indicating content violations
• Use v2 API when possible (more stable, better features)

• Store tweets with id_str not id (JavaScript number limits)

• Media Upload:

• Supported formats: JPEG, PNG, GIF, MP4, MOV
• Image size limit: 5MB
• Video size limit: 512MB
• Upload to upload.twitter.com, then attach media_id to tweet

• Videos require chunked upload for files > 15MB

• Webhooks & Streaming:

• Account Activity API: Real-time webhooks for mentions, DMs
• Filtered Stream API (v2): Subscribe to tweets matching rules
• Requires elevated API access (Basic tier or higher)

• Alternative: Poll APIs with efficient rate limit management

• Developer Account:

• Required for any API access
• Apply at developer.twitter.com
• Approval can take 1-3 days
• Must describe intended use case

• Platform policies strictly enforced

• API Version Notes:

• v1.1: Legacy, still widely used, being phased out
• v2: Current, recommended for new development
• Some features only available in v1.1 (trends, favorites)

• Some features only available in v2 (conversation threads, polls)

• Content Policies:

• No spam or automation of interactions
• No bulk/aggressive following
• No duplicate content across accounts
• No manipulation of engagement metrics

• Violating policies can result in account suspension

• Alternative Tools:

• tweepy (Python): Full-featured Twitter SDK
• twitter-api-client (Python): Async support
• twit (Node.js): Popular JavaScript library
• twarc (Python): Archiving and research tool
• twitter-cli (Go): Alternative CLI tool