Recent Search Quickstart

This guide walks you through making your first recent search request to find Posts from the. Reference for the X API v2 standard tier covering quickstart.

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"
   

   from xdk import Client
   
   client = Client(bearer_token="YOUR_BEARER_TOKEN")
   
   # Search recent Posts
   for page in client.posts.search_recent(
       query="python lang:en -is:retweet"
   ):
       for post in page.data:
           print(post.text)
   

   import { Client } from "@xdevplatform/xdk";
   
   const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });
   
   // Search recent Posts
   const paginator = client.posts.searchRecent({
     query: "python lang:en -is:retweet",
   });
   
   for await (const page of paginator) {
     page.data?.forEach((post) => {
       console.log(post.text);
     });
   }
   
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"
   

   from xdk import Client
   
   client = Client(bearer_token="YOUR_BEARER_TOKEN")
   
   # Search with fields and expansions
   for page in client.posts.search_recent(
       query="python lang:en -is:retweet",
       tweet_fields=["created_at", "public_metrics", "author_id"],
       expansions=["author_id"],
       user_fields=["username", "verified"],
       max_results=10
   ):
       for post in page.data:
           print(f"{post.text[:50]}... - Likes: {post.public_metrics.like_count}")
   

   import { Client } from "@xdevplatform/xdk";
   
   const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });
   
   // Search with fields and expansions
   const paginator = client.posts.searchRecent({
     query: "python lang:en -is:retweet",
     tweetFields: ["created_at", "public_metrics", "author_id"],
     expansions: ["author_id"],
     userFields: ["username", "verified"],
     maxResults: 10,
   });
   
   for await (const page of paginator) {
     page.data?.forEach((post) => {
       console.log(`${post.text?.slice(0, 50)}... - Likes: ${post.public_metrics?.like_count}`);
     });
   }
   

   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