Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.x.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through making your first recent search request to find Posts from the last 7 days.
PrerequisitesBefore 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”)

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.

Make a request

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

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
  }
}

Add fields and expansions

Request additional data with query parameters:
cURL
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
  }
}

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

from:XDevelopers

#Python -is:retweet

"machine learning" has:images lang:en

@elonmusk -is:retweet -is:reply

​
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