Skip to main content
This guide walks you through retrieving Posts that mention a specific user.
PrerequisitesBefore 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
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
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
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

ParameterDescriptionDefault
max_resultsResults per page (1-100)10
start_timeOldest Post timestamp (ISO 8601)—
end_timeNewest Post timestamp (ISO 8601)—
since_idReturn Posts after this ID—
until_idReturn Posts before this ID—
excludeExclude retweets, replies, or both—
pagination_tokenToken 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