User Mentions Timeline

This guide walks you through retrieving Posts that mention a specific user. Reference for the X API v2 standard tier covering quickstart.

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"
   

   from xdk import Client
   
   client = Client(bearer_token="YOUR_BEARER_TOKEN")
   
   # Get mentions timeline with pagination
   for page in client.posts.get_user_mentions(
       "2244994945",
       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.author_id}: {post.text[:50]}...")
   

   import { Client } from "@xdevplatform/xdk";
   
   const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });
   
   // Get mentions timeline with pagination
   const paginator = client.posts.getUserMentions("2244994945", {
     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.author_id}: ${post.text?.slice(0, 50)}...`);
     });
   }
   
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"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Get mentions excluding replies
for page in client.posts.get_user_mentions(
    "2244994945",
    exclude=["replies"],
    max_results=10
):
    for post in page.data:
        print(post.text)

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Get mentions excluding replies
const paginator = client.posts.getUserMentions("2244994945", {
  exclude: ["replies"],
  maxResults: 10,
});

for await (const page of paginator) {
  page.data?.forEach((post) => {
    console.log(post.text);
  });
}

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"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Get mentions in a time range
for page in client.posts.get_user_mentions(
    "2244994945",
    start_time="2024-01-01T00:00:00Z",
    end_time="2024-01-31T23:59:59Z"
):
    for post in page.data:
        print(f"{post.created_at}: {post.text[:50]}...")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Get mentions in a time range
const paginator = client.posts.getUserMentions("2244994945", {
  startTime: "2024-01-01T00:00:00Z",
  endTime: "2024-01-31T23:59:59Z",
});

for await (const page of paginator) {
  page.data?.forEach((post) => {
    console.log(`${post.created_at}: ${post.text?.slice(0, 50)}...`);
  });
}

---

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