Skip to main content

​
Overview

The User class represents a Twitter/X user profile and provides methods for following, blocking, retrieving tweets, and more.

​
User Class

​
Attributes

​
id
str
The unique identifier of the user.
​
created_at
str
The date and time when the user account was created.
​
created_at_datetime
datetime
The created_at converted to datetime object.
​
name
str
The user’s display name.
​
screen_name
str
The user’s screen name (handle without @).
​
profile_image_url
str
The URL of the user’s profile image (HTTPS version).
​
profile_banner_url
str
The URL of the user’s profile banner.
​
url
str
The user’s URL.
​
location
str
The user’s location information.
​
description
str
The user’s profile description (bio).
​
description_urls
list
URLs found in the user’s profile description.
​
urls
list
URLs associated with the user.
​
pinned_tweet_ids
list[str]
The IDs of tweets that the user has pinned to their profile.
​
is_blue_verified
bool
Indicates if the user is verified with a blue checkmark (Twitter Blue).
​
verified
bool
Indicates if the user is verified (legacy verification).
​
possibly_sensitive
bool
Indicates if the user’s content may be sensitive.
​
can_dm
bool
Indicates whether the user can receive direct messages.
​
can_media_tag
bool
Indicates whether the user can be tagged in media.
​
want_retweets
bool
Indicates if the user wants retweets.
​
default_profile
bool
Indicates if the user has the default profile.
​
default_profile_image
bool
Indicates if the user has the default profile image.
​
has_custom_timelines
bool
Indicates if the user has custom timelines.
​
followers_count
int
The count of followers.
​
fast_followers_count
int
The count of fast followers.
​
normal_followers_count
int
The count of normal followers.
​
following_count
int
The count of users the user is following.
​
favourites_count
int
The count of favorites or likes.
​
listed_count
int
The count of lists the user is a member of.
​
media_count
int
The count of media items associated with the user.
​
statuses_count
int
The count of tweets.
​
is_translator
bool
Indicates if the user is a translator.
​
translator_type
str
The type of translator.
​
withheld_in_countries
list[str]
Countries where the user’s content is withheld.
​
protected
bool
Indicates if the user’s tweets are protected (private account).

​
Methods

​
get_tweets()

Retrieves the user’s tweets.
​
tweet_type
'Tweets' | 'Replies' | 'Media' | 'Likes'
required
The type of tweets to retrieve.
​
count
int
default:"40"
The number of tweets to retrieve.
Returns: Result[Tweet] - A Result object containing a list of Tweet objects. 
user = await client.get_user_by_screen_name('example_user')
tweets = await user.get_tweets('Tweets', count=20)
for tweet in tweets:
    print(tweet)
# <Tweet id="...">
# <Tweet id="...">

more_tweets = await tweets.next()  # Retrieve more tweets
for tweet in more_tweets:
    print(tweet)
# <Tweet id="...">
# <Tweet id="...">

​
follow()

Follows the user. Returns: httpx.Response 
await user.follow()
See Also: Client.follow_user

​
unfollow()

Unfollows the user. Returns: httpx.Response 
await user.unfollow()
See Also: Client.unfollow_user

​
block()

Blocks the user. Returns: httpx.Response 
await user.block()
See Also: Client.block_user

​
unblock()

Unblocks the user. Returns: httpx.Response 
await user.unblock()
See Also: Client.unblock_user

​
mute()

Mutes the user. Returns: httpx.Response 
await user.mute()
See Also: Client.mute_user

​
unmute()

Unmutes the user. Returns: httpx.Response 
await user.unmute()
See Also: Client.unmute_user

​
get_followers()

Retrieves a list of followers for the user.
​
count
int
default:"20"
The number of followers to retrieve.
Returns: Result[User] - A list of User objects representing the followers. 
followers = await user.get_followers(count=50)
for follower in followers:
    print(follower.screen_name)
See Also: Client.get_user_followers

​
get_verified_followers()

Retrieves a list of verified followers for the user.
​
count
int
default:"20"
The number of verified followers to retrieve.
Returns: Result[User] - A list of User objects representing the verified followers. 
verified_followers = await user.get_verified_followers(count=20)
See Also: Client.get_user_verified_followers

​
get_followers_you_know()

Retrieves a list of followers whom the user might know.
​
count
int
default:"20"
The number of followers you might know to retrieve.
Returns: Result[User] - A list of User objects representing the followers you might know. 
followers_you_know = await user.get_followers_you_know(count=20)
See Also: Client.get_user_followers_you_know

​
get_following()

Retrieves a list of users whom the user is following.
​
count
int
default:"20"
The number of following users to retrieve.
Returns: Result[User] - A list of User objects representing the users being followed. 
following = await user.get_following(count=50)
for followed_user in following:
    print(followed_user.screen_name)
See Also: Client.get_user_following

​
get_subscriptions()

Retrieves a list of users whom the user is subscribed to.
​
count
int
default:"20"
The number of subscriptions to retrieve.
Returns: Result[User] - A list of User objects representing the subscribed users. 
subscriptions = await user.get_subscriptions(count=20)
See Also: Client.get_user_subscriptions

​
get_latest_followers()

Retrieves the latest followers. Max count: 200.
​
count
int | None
default:"None"
The number of followers to retrieve.
​
cursor
str | None
default:"None"
The cursor for pagination.
Returns: Result[User] 
latest_followers = await user.get_latest_followers(count=100)

​
get_latest_friends()

Retrieves the latest friends (following users). Max count: 200.
​
count
int | None
default:"None"
The number of friends to retrieve.
​
cursor
str | None
default:"None"
The cursor for pagination.
Returns: Result[User] 
latest_friends = await user.get_latest_friends(count=100)

​
send_dm()

Send a direct message to the user.
​
text
str
required
The text content of the direct message.
​
media_id
str
default:"None"
The media ID associated with any media content to be included in the message. Media ID can be received by using the upload_media method.
​
reply_to
str
default:"None"
Message ID to reply to.
Returns: Message - Message object containing information about the message sent. 
# Send DM with media
media_id = await client.upload_media('image.png')
message = await user.send_dm('Hello!', media_id)
print(message)
# <Message id="...">
See Also: Client.upload_media, Client.send_dm

​
get_dm_history()

Retrieves the DM conversation history with the user.
​
max_id
str
default:"None"
If specified, retrieves messages older than the specified max_id.
Returns: Result[Message] - A Result object containing a list of Message objects representing the DM conversation history. 
messages = await user.get_dm_history()
for message in messages:
    print(message)
# <Message id="...">
# <Message id="...">

more_messages = await messages.next()  # Retrieve more messages
for message in more_messages:
    print(message)
# <Message id="...">
# <Message id="...">

​
get_highlights_tweets()

Retrieves highlighted tweets from the user’s timeline.
​
count
int
default:"20"
The number of tweets to retrieve.
​
cursor
str | None
default:"None"
The cursor for pagination.
Returns: Result[Tweet] - An instance of the Result class containing the highlighted tweets. 
result = await user.get_highlights_tweets(count=20)
for tweet in result:
    print(tweet)
# <Tweet id="...">
# <Tweet id="...">

more_results = await result.next()  # Retrieve more highlighted tweets
for tweet in more_results:
    print(tweet)
# <Tweet id="...">
# <Tweet id="...">

​
update()

Updates the user object with fresh data from the API. 
await user.update()

​
Examples

​
Basic User Information

# Get user by screen name
user = await client.get_user_by_screen_name('elonmusk')

# Access user properties
print(f"Name: {user.name}")
print(f"Handle: @{user.screen_name}")
print(f"Bio: {user.description}")
print(f"Followers: {user.followers_count:,}")
print(f"Following: {user.following_count:,}")
print(f"Verified: {user.verified or user.is_blue_verified}")

​
Follow a User and Get Their Tweets

user = await client.get_user_by_screen_name('github')

# Follow the user
await user.follow()

# Get their recent tweets
tweets = await user.get_tweets('Tweets', count=10)
for tweet in tweets:
    print(f"{tweet.created_at}: {tweet.text}")

​
Get User’s Followers and Following

user = await client.get_user_by_screen_name('example_user')

# Get followers
followers = await user.get_followers(count=50)
print(f"First 50 followers:")
for follower in followers:
    print(f"  @{follower.screen_name} - {follower.name}")

# Get following
following = await user.get_following(count=50)
print(f"\nFirst 50 following:")
for followed in following:
    print(f"  @{followed.screen_name} - {followed.name}")

​
Send Direct Message

user = await client.get_user_by_screen_name('friend_user')

# Send a simple text message
message = await user.send_dm('Hey! How are you?')

# Send a message with an image
media_id = await client.upload_media('photo.jpg')
message_with_media = await user.send_dm(
    'Check out this photo!',
    media_id=media_id
)

​
Block and Mute Management

user = await client.get_user_by_screen_name('spam_account')

# Mute the user (still see profile, but not tweets in timeline)
await user.mute()

# Or block the user (complete block)
await user.block()

# Later, if needed
await user.unmute()
await user.unblock()

Build docs developers (and LLMs) love

Get started for freeTalk to us