Omni-X

version: 1.0.0 author: Omni-X category: social-media tags: [twitter, x, social-media, data-extraction, api]

X (Twitter) Data Extractor Skill

Overview

This skill provides AI agents with the ability to extract various types of data from X (Twitter) platform, including user profiles, posts, followers, followings, media content, and search results.

Prerequisites

Workflow

Step 1: Initialize the Skill Interface

from scripts import TwitterSkillInterface
Method 1: Initialize with auth_token (RECOMMENDED for full access)
interface = TwitterSkillInterface(auth_token="your_auth_token_here")
Method 2: Initialize without token (guest session - limited features)
interface = TwitterSkillInterface()
Method 3: Set token after initialization
interface = TwitterSkillInterface()
interface.set_auth_token("your_auth_token_here")

Step 2: Discover Available Skills

# Get all available skills and their metadata
skills = interface.get_available_skills()
Each skill contains:
- description: What the skill does
- parameters: Required and optional parameters
- returns: Expected return format
- requires_auth: Whether authentication is needed

Step 3: Execute Skills

# Execute a skill with parameters
result = interface.execute_skill(
    skill_name="get_user_tweets",
    parameters={"username": "elonmusk", "count": 10}
)
Check result
if result["success"]:
    data = result["data"]
    print(f"Retrieved {result['count']} items")
else:
    print(f"Error: {result['error']}")

Step 4: Handle Results

All skills return a standardized response format:

Success Response:

{
    "success": True,
    "data": [...],           # The actual data
    "count": 10,             # Number of items (if applicable)
    "has_next_page": True,   # Pagination info (if applicable)
    "cursor": "...",         # Cursor for next page (if applicable)
    "skill_name": "...",     # Name of executed skill
    "parameters": {...}      # Parameters used
}

Error Response:

{
    "success": False,
    "error": "Error message",
    "skill_name": "...",
    "parameters": {...}
}

Available Skills

1. get_user_profile

Authentication: Not required (works with guest session)

Parameters:

Example:

result = interface.execute_skill(
    skill_name="get_user_profile",
    parameters={"username": "elonmusk"}
)

Returns: User profile data including name, bio, followers count, following count, etc.

2. get_user_tweets

Authentication: Not required (works with guest session)

Parameters:

Example:

result = interface.execute_skill(
    skill_name="get_user_tweets",
    parameters={"username": "elonmusk", "count": 20}
)

Returns: List of tweets with text, timestamp, engagement metrics, etc.

3. get_user_followers

Authentication: Required (auth_token needed)

Parameters:

Example:

result = interface.execute_skill(
    skill_name="get_user_followers",
    parameters={"username": "elonmusk", "count": 50}
)

Returns: List of follower profiles with pagination support.

4. get_user_followings

Authentication: Required (auth_token needed)

Parameters:

Example:

result = interface.execute_skill(
    skill_name="get_user_followings",
    parameters={"username": "elonmusk", "count": 50}
)

Returns: List of following profiles with pagination support.

5. get_user_media

Authentication: Required (auth_token needed)

Parameters:

Example:

result = interface.execute_skill(
    skill_name="get_user_media",
    parameters={"username": "elonmusk", "count": 15}
)

Returns: List of media items with URLs and metadata.

6. search_tweets

Authentication: Required (auth_token needed)

Parameters:

Example:

result = interface.execute_skill(
    skill_name="search_tweets",
    parameters={
        "query": "AI technology",
        "count": 20,
        "search_filter": "Latest"
    }
)

Returns: List of tweets matching the search query.

Tool Usage Instructions

For AI Agents

When using this skill, follow these steps:

1. Determine the task: Analyze user request to identify which skill is needed - Profile info → get_user_profile - Recent tweets → get_user_tweets - Follower analysis → get_user_followers - Following analysis → get_user_followings - Media extraction → get_user_media - Search tweets → search_tweets

2. Check authentication requirements: - If skill requires auth and no token is set, inform user to provide auth_token - Guest session works for: get_user_profile, get_user_tweets - Auth required for: get_user_followers, get_user_followings, get_user_media, search_tweets

3. Extract parameters from user request: - Username (remove @ if present) - Count/limit for results - Search filters (for search_tweets)

4. Execute the skill:

   result = interface.execute_skill(skill_name="...", parameters={...})
   

5. Process and present results: - Check result["success"] first - If successful, format and present result["data"] - If failed, explain result["error"] to user - Mention pagination if result["has_next_page"] is True

Error Handling

result = interface.execute_skill(skill_name="...", parameters={...})
if not result["success"]:
    error_msg = result["error"]
    
    # Common errors and solutions:
    if "auth" in error_msg.lower() or "login" in error_msg.lower():
        # Inform user that authentication is required
        print("This feature requires authentication. Please provide auth_token.")
    elif "not found" in error_msg.lower():
        # Username doesn't exist
        print(f"User not found. Please check the username.")
    elif "rate limit" in error_msg.lower():
        # Rate limit exceeded
        print("Rate limit exceeded. Please wait before trying again.")
    else:
        # Generic error
        print(f"An error occurred: {error_msg}")

Examples

Example 1: Get User Profile and Recent Tweets

from scripts import TwitterSkillInterface
Initialize
interface = TwitterSkillInterface()
Get profile
profile = interface.execute_skill(
    skill_name="get_user_profile",
    parameters={"username": "elonmusk"}
)
if profile["success"]:
    print(f"User: {profile['data']['name']}")
    print(f"Followers: {profile['data']['followers_count']}")
Get recent tweets
tweets = interface.execute_skill(
    skill_name="get_user_tweets",
    parameters={"username": "elonmusk", "count": 5}
)
if tweets["success"]:
    for tweet in tweets["data"]:
        print(f"Tweet: {tweet['text']}")

Example 2: Search and Analyze Tweets (Requires Auth)

from scripts import TwitterSkillInterface
Initialize with auth token
interface = TwitterSkillInterface(auth_token="your_auth_token")
Search for tweets
results = interface.execute_skill(
    skill_name="search_tweets",
    parameters={
        "query": "artificial intelligence",
        "count": 20,
        "search_filter": "Latest"
    }
)
if results["success"]:
    print(f"Found {results['count']} tweets")
    for tweet in results["data"]:
        print(f"- {tweet['text'][:100]}...")

Example 3: Analyze User Network (Requires Auth)

from scripts import TwitterSkillInterface
Initialize with auth token
interface = TwitterSkillInterface(auth_token="your_auth_token")
username = "elonmusk"
Get followers
followers = interface.execute_skill(
    skill_name="get_user_followers",
    parameters={"username": username, "count": 100}
)
Get followings
followings = interface.execute_skill(
    skill_name="get_user_followings",
    parameters={"username": username, "count": 100}
)
if followers["success"] and followings["success"]:
    print(f"Followers: {followers['count']}")
    print(f"Following: {followings['count']}")
    print(f"Ratio: {followers['count'] / followings['count']:.2f}")

Best Practices

1. Always provide auth_token when possible - Many features require authentication 2. Check success field first - Always verify result["success"] before accessing data 3. Handle pagination - Use cursor field for large datasets 4. Respect rate limits - CRITICAL: Implement delays between requests to avoid account restrictions - Recommended: 1-2 second delay between requests - For bulk operations: 2-3 second delay - Monitor for rate limit errors and back off exponentially if encountered 5. Cache results - Avoid repeated requests for the same data 6. Validate usernames - Remove @ symbol and validate format before calling 7. Use appropriate count values - Start with small counts (10-20) and increase gradually as needed 8. Handle errors gracefully - Provide meaningful feedback to users 9. Comply with Terms of Service - Ensure all usage complies with X (Twitter) Terms of Service 10. Educational/Research Use Only - This tool is intended for educational and research purposes only

Authentication Guide

See references/LOGIN_GUIDE.md for detailed instructions on obtaining and using auth_token.

Quick steps: 1. Log in to Twitter/X in browser 2. Open Developer Tools (F12) 3. Go to Application/Storage → Cookies 4. Find auth_token cookie 5. Copy its value 6. Use it to initialize: TwitterSkillInterface(auth_token="...")

Troubleshooting

Problem: "Guest session has limited access"

Problem: "User not found"

Problem: "Rate limit exceeded"

Problem: "Authentication required"

References

Support

For issues or questions, refer to the documentation in the references/ directory or check the main README.md file.

Example 1: Get User Profile and Recent Tweets

from scripts import TwitterSkillInterface
Initialize
interface = TwitterSkillInterface()
Get profile
profile = interface.execute_skill(
    skill_name="get_user_profile",
    parameters={"username": "elonmusk"}
)
if profile["success"]:
    print(f"User: {profile['data']['name']}")
    print(f"Followers: {profile['data']['followers_count']}")
Get recent tweets
tweets = interface.execute_skill(
    skill_name="get_user_tweets",
    parameters={"username": "elonmusk", "count": 5}
)
if tweets["success"]:
    for tweet in tweets["data"]:
        print(f"Tweet: {tweet['text']}")

Example 2: Search and Analyze Tweets (Requires Auth)

from scripts import TwitterSkillInterface
Initialize with auth token
interface = TwitterSkillInterface(auth_token="your_auth_token")
Search for tweets
results = interface.execute_skill(
    skill_name="search_tweets",
    parameters={
        "query": "artificial intelligence",
        "count": 20,
        "search_filter": "Latest"
    }
)
if results["success"]:
    print(f"Found {results['count']} tweets")
    for tweet in results["data"]:
        print(f"- {tweet['text'][:100]}...")

Example 3: Analyze User Network (Requires Auth)

from scripts import TwitterSkillInterface
Initialize with auth token
interface = TwitterSkillInterface(auth_token="your_auth_token")
username = "elonmusk"
Get followers
followers = interface.execute_skill(
    skill_name="get_user_followers",
    parameters={"username": username, "count": 100}
)
Get followings
followings = interface.execute_skill(
    skill_name="get_user_followings",
    parameters={"username": username, "count": 100}
)
if followers["success"] and followings["success"]:
    print(f"Followers: {followers['count']}")
    print(f"Following: {followings['count']}")
    print(f"Ratio: {followers['count'] / followings['count']:.2f}")

1. Always provide auth_token when possible - Many features require authentication 2. Check success field first - Always verify result["success"] before accessing data 3. Handle pagination - Use cursor field for large datasets 4. Respect rate limits - CRITICAL: Implement delays between requests to avoid account restrictions - Recommended: 1-2 second delay between requests - For bulk operations: 2-3 second delay - Monitor for rate limit errors and back off exponentially if encountered 5. Cache results - Avoid repeated requests for the same data 6. Validate usernames - Remove @ symbol and validate format before calling 7. Use appropriate count values - Start with small counts (10-20) and increase gradually as needed 8. Handle errors gracefully - Provide meaningful feedback to users 9. Comply with Terms of Service - Ensure all usage complies with X (Twitter) Terms of Service 10. Educational/Research Use Only - This tool is intended for educational and research purposes only