Recent Search Quickstart

This guide walks you through making your first recent search request to find Posts from the last 7 days. Before you begin, you’ll. Standard X API v2 tier.

This guide walks you through making your first recent search request to find Posts from the last 7 days.

Prerequisites

Before you begin, you’ll need:

• A developer account with an approved App
• Your App’s Bearer Token (found in the Developer Console under “Keys and tokens”)

---

1. Build a query

   Search queries use operators to match Posts. Start with a simple keyword:

   python
   

   Or combine multiple operators:

   python lang:en -is:retweet
   

   This matches Posts containing “python” in English, excluding retweets.

   See the full operator reference for all available options.

2. Make a request

   cURL

   shellscript

   curl "https://api.x.com/2/tweets/search/recent?query=python%20lang%3Aen%20-is%3Aretweet" \
     -H "Authorization: Bearer $BEARER_TOKEN"
   
3. Review the response

   The default response includes id, text, and edit_history_tweet_ids:

   {
     "data": [
       {
         "id": "1234567890123456789",
         "text": "Just started learning Python and loving it!",
         "edit_history_tweet_ids": ["1234567890123456789"]
       },
       {
         "id": "1234567890123456788",
         "text": "Python tip: use list comprehensions for cleaner code",
         "edit_history_tweet_ids": ["1234567890123456788"]
       }
     ],
     "meta": {
       "newest_id": "1234567890123456789",
       "oldest_id": "1234567890123456788",
       "result_count": 2
     }
   }
   
4. Add fields and expansions

   Request additional data with query parameters:

   cURL

   shellscript

   curl "https://api.x.com/2/tweets/search/recent?\
   query=python%20lang%3Aen%20-is%3Aretweet&\
   tweet.fields=created_at,public_metrics,author_id&\
   expansions=author_id&\
   user.fields=username,verified&\
   max_results=10" \
     -H "Authorization: Bearer $BEARER_TOKEN"
   

   Response:

   {
     "data": [
       {
         "id": "1234567890123456789",
         "text": "Just started learning Python and loving it!",
         "created_at": "2024-01-15T10:30:00.000Z",
         "author_id": "9876543210",
         "public_metrics": {
           "retweet_count": 5,
           "reply_count": 2,
           "like_count": 42,
           "quote_count": 1
         },
         "edit_history_tweet_ids": ["1234567890123456789"]
       }
     ],
     "includes": {
       "users": [
         {
           "id": "9876543210",
           "username": "pythondev",
           "verified": false
         }
       ]
     },
     "meta": {
       "newest_id": "1234567890123456789",
       "oldest_id": "1234567890123456789",
       "result_count": 1
     }
   }
   
5. Paginate through results

   The SDKs handle pagination automatically. For cURL, use the next_token from the response:

   curl "https://api.x.com/2/tweets/search/recent?\
   query=python&\
   max_results=100&\
   next_token=b26v89c19zqg8o3fo7gesq314yb9l2l4ptqy" \
     -H "Authorization: Bearer $BEARER_TOKEN"
   

   Pagination guide

   Learn more about navigating large result sets

---

Example queries

Posts from a specific user

from:XDevelopers

Posts with a hashtag

#Python -is:retweet

Posts with images

"machine learning" has:images lang:en

Posts mentioning a user

@elonmusk -is:retweet -is:reply

Posts with links to a domain

url:github.com lang:en

---

Next steps

Build a query

Master query syntax and operators

Operator reference

See all available operators

Full-archive search

Search the complete Post archive

API Reference

Full endpoint documentation