User Mentions Timeline

Get Posts that mention a specific user

This guide walks you through retrieving Posts that mention a specific user.

Prerequisites

Before you begin, you’ll need:

• A developer account with an approved App
• Your App’s Bearer Token (for public data) or User Access Token (for private metrics)

---

Get user mentions

1. Get the user ID

   Find the user ID using the user lookup endpoint. For example, @XDevelopers has user ID 2244994945.

2. Request the mentions timeline

   cURL

   shellscript

   curl "https://api.x.com/2/users/2244994945/mentions?\
   tweet.fields=created_at,public_metrics,author_id&\
   expansions=author_id&\
   user.fields=username,verified&\
   max_results=10" \
     -H "Authorization: Bearer $BEARER_TOKEN"
   
3. Review the response

   {
     "data": [
       {
         "id": "1301573587187331074",
         "text": "Hey @XDevelopers, love the new API!",
         "author_id": "1234567890",
         "created_at": "2024-01-15T10:30:00.000Z",
         "public_metrics": {
           "retweet_count": 5,
           "reply_count": 2,
           "like_count": 42,
           "quote_count": 1
         }
       }
     ],
     "includes": {
       "users": [
         {
           "id": "1234567890",
           "username": "developer",
           "name": "Dev Person",
           "verified": false
         }
       ]
     },
     "meta": {
       "newest_id": "1301573587187331074",
       "oldest_id": "1301573587187331074",
       "result_count": 1,
       "next_token": "t3buvdr5pujq9g7bggsnf3ep2ha28"
     }
   }
   

---

Filter mentions

Exclude replies

Get only original Posts that mention the user:

cURL

shellscript

curl "https://api.x.com/2/users/2244994945/mentions?\
exclude=replies&\
max_results=10" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Get mentions in a time range

cURL

shellscript

curl "https://api.x.com/2/users/2244994945/mentions?\
start_time=2024-01-01T00%3A00%3A00Z&\
end_time=2024-01-31T23%3A59%3A59Z" \
  -H "Authorization: Bearer $BEARER_TOKEN"

---

Common parameters

Parameter	Description	Default
max_results	Results per page (1-100)	10
start_time	Oldest Post timestamp (ISO 8601)	—
end_time	Newest Post timestamp (ISO 8601)	—
since_id	Return Posts after this ID	—
until_id	Return Posts before this ID	—
exclude	Exclude retweets, replies, or both	—
pagination_token	Token for next page	—

---

Next steps

Home timeline

Get user’s home timeline

Integration guide

Key concepts and best practices

API Reference

Full endpoint documentation

Pagination guide

Navigate large result sets