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

Query Rules (X API constraint — required reading)

Every query must contain at least one STANDALONE term. Operator-only queries return HTTP 400 from X.

• Standalone (can stand alone as the whole query): keyword, "quoted phrase", #hashtag, @mention, from:user, to:user, url:domain, context:.
• Conjunction-required (must be combined with a standalone term): lang:, is:retweet / -is:retweet, is:reply / -is:reply, is:quote, has:links, has:media, has:images, has:videos, plain -negation of any keyword.

HTTP 400 — these queries fail:

Valid — these have at least one standalone term:

Query Operators

The X API v2 supports advanced search operators:

Examples

Simple keyword search:

{
  "query": "artificial intelligence",
  "max_results": 20
}

Search with hashtag:

{
  "query": "#MachineLearning -is:retweet lang:en",
  "max_results": 50
}

Search tweets from a user (original tweets only):

{
  "query": "from:OpenAI -is:retweet",
  "max_results": 10
}

Complex query:

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

Search for media posts:

{
  "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.

{
  "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

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

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

Guidelines

1. Always include a standalone term (keyword / phrase / hashtag / mention / from: / to: / url:) — see "Query Rules" above. Operator-only queries fail with HTTP 400.
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 on a base term: e.g., python -is:retweet lang:en has:links — the python keyword anchors all three filters.
6. Exclude retweets: append -is:retweet to a keyword query (e.g. python -is:retweet). Cannot stand alone.
7. Language filter: append lang:en to a keyword/from:/hashtag query (e.g. "openai" lang:en). Cannot stand alone.
8. Media filter: append has:media / has:images / has:videos to a keyword query. Cannot stand alone.

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

References

• X API — Build a query
• X API — Operators reference
• X API — /2/tweets/search/recent