User Mentions Timeline

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

Get the user ID

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

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"

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)}...`);
  });
}

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"

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

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

​Get user mentions

​Filter mentions

​Exclude replies

​Get mentions in a time range

​Common parameters

​Next steps

Home timeline

Integration guide

API Reference

Pagination guide

Get user mentions

Filter mentions

Exclude replies

Get mentions in a time range

Common parameters

Next steps