twitter-search-skill

# Twitter Search Tool

Search for recent tweets on Twitter/X with rich data including full text, expanded URLs, author profiles, media attachments, engagement metrics, and referenced tweets.

## How It Works

This skill provides instructions for the **Twitter Search** tool node. Connect the **Twitter Search** node to an AI Agent's `input-tools` handle to enable tweet searching.

## twitter_search Tool

Search for tweets matching a query. Returns enriched tweet data via X API v2 expansions.

### Schema Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| query | string | Yes | Search query (supports operators) |
| max_results | integer | No | Number of results (10-100, default: 10) |

### Query Operators

The X API v2 supports advanced search operators:

| Operator | Example | Description |
|----------|---------|-------------|
| keyword | `python` | Tweets containing the word |
| phrase | `"machine learning"` | Exact phrase match |
| hashtag | `#AI` | Tweets with hashtag |
| mention | `@username` | Tweets mentioning user |
| from | `from:elonmusk` | Tweets by specific user |
| to | `to:username` | Replies to user |
| -keyword | `-spam` | Exclude keyword |
| OR | `python OR javascript` | Either term |
| lang | `lang:en` | Language filter |
| has:links | `AI has:links` | Tweets with URLs |
| has:media | `sunset has:media` | Tweets with media |
| has:images | `cat has:images` | Tweets with images |
| has:videos | `news has:videos` | Tweets with videos |
| is:retweet | `bitcoin is:retweet` | Only retweets |
| -is:retweet | `news -is:retweet` | Exclude retweets |
| is:reply | `@user is:reply` | Only replies |
| -is:reply | `topic -is:reply` | Exclude replies |
| is:quote | `breaking is:quote` | Only quote tweets |
| url: | `url:"github.com"` | Tweets linking to domain |
| context: | `context:131.1007360414114435072` | Tweets in topic context |

### Examples

**Simple keyword search:**
```json
{
  "query": "artificial intelligence",
  "max_results": 20
}
```

**Search with hashtag:**
```json
{
  "query": "#MachineLearning -is:retweet lang:en",
  "max_results": 50
}
```

**Search tweets from a user (original tweets only):**
```json
{
  "query": "from:OpenAI -is:retweet",
  "max_results": 10
}
```

**Complex query:**
```json
{
  "query": "AI (startup OR company) -is:retweet lang:en has:links",
  "max_results": 100
}
```

**Search for media posts:**
```json
{
  "query": "sunset has:media -is:retweet",
  "max_results": 25
}
```

### Response Format

Each tweet includes rich data. The `display_text` field has t.co links replaced with full expanded URLs. Long-form tweets (>280 chars) use `note_tweet` content.

```json
{
  "success": true,
  "result": {
    "tweets": [
      {
        "id": "1234567890123456789",
        "text": "Check out https://t.co/abc123",
        "display_text": "Check out https://www.example.com/full-article-url",
        "author_id": "987654321",
        "created_at": "2025-02-19T10:30:00+00:00",
        "lang": "en",
        "source": "Twitter Web App",
        "conversation_id": "1234567890123456789",
        "in_reply_to_user_id": null,
        "possibly_sensitive": false,
        "public_metrics": {
          "retweet_count": 42,
          "reply_count": 12,
          "like_count": 256,
          "quote_count": 5,
          "bookmark_count": 18,
          "impression_count": 15000
        },
        "author": {
          "id": "987654321",
          "username": "techuser",
          "name": "Tech User",
          "profile_image_url": "https://pbs.twimg.com/..."
        },
        "urls": [
          {
            "url": "https://t.co/abc123",
            "expanded_url": "https://www.example.com/full-article-url",
            "display_url": "example.com/full-article-..."
          }
        ],
        "media": [
          {
            "media_key": "3_123456789",
            "type": "photo",
            "url": "https://pbs.twimg.com/media/...",
            "alt_text": "Description of the image"
          }
        ],
        "referenced_tweets": [
          {
            "type": "quoted",
            "id": "1111111111111111111",
            "text": "Original tweet text that was quoted",
            "author_id": "222222222"
          }
        ]
      }
    ],
    "count": 20,
    "query": "#AI"
  },
  "execution_time": 0.82
}
```

### Key Response Fields

| Field | Description |
|-------|-------------|
| `text` | Raw tweet text (may contain t.co shortened links) |
| `display_text` | Text with t.co links expanded to full URLs -- **use this for display** |
| `author` | Author profile (username, name, profile image) from includes expansion |
| `public_metrics` | Engagement: retweet_count, reply_count, like_count, quote_count, bookmark_count, impression_count |
| `media` | Attached media objects (photo, video, animated_gif) with URLs and alt text |
| `urls` | Expanded URL mappings (short t.co -> full URL) |
| `referenced_tweets` | Quoted or replied-to tweets with their text content |
| `lang` | Detected language code (e.g., "en", "es", "ja") |
| `source` | Client used to post (e.g., "Twitter Web App", "Twitter for iPhone") |
| `conversation_id` | ID of the conversation thread |
| `in_reply_to_user_id` | If a reply, the user ID being replied to |

### Important Notes

- **Always use `display_text`** instead of `text` when showing tweet content to users -- it contains expanded URLs
- **Long tweets**: Tweets over 280 characters use note_tweet; the full text is in the `text` field
- **Media URLs**: `media[].url` gives the direct image/video URL
- **Referenced tweets**: `referenced_tweets[].text` contains the full text of quoted/replied tweets
- **Metrics**: `public_metrics` shows real-time engagement counts

### Error Response

```json
{
  "success": false,
  "error": "Search query is required",
  "execution_time": 0.01
}
```

## Guidelines

1. **Query length**: Keep queries concise for better results
2. **Max results**: Minimum 10, maximum 100 per request (X API v2 constraint)
3. **Recent tweets only**: X API v2 free/basic tier searches recent tweets (last 7 days)
4. **Rate limits**: Be mindful of API rate limits when searching repeatedly
5. **Combine operators**: Use multiple operators for precise filtering
6. **Exclude retweets**: Add `-is:retweet` to get original content only
7. **Language filter**: Add `lang:en` to filter by language

## Common Use Cases

- Monitor brand mentions with engagement metrics
- Track trending topics and measure reach
- Find tweets about specific subjects with media
- Research competitor activity and engagement
- Gather content for curation with full context
- Find influencers by analyzing follower/engagement metrics
- Analyze conversation threads via conversation_id

## Setup Requirements

1. Connect the **Twitter Search** node to an AI Agent's `input-tools` handle
2. Ensure Twitter is connected (authenticated via OAuth in Credentials Modal)
3. Your X Developer account must have appropriate API access level