Tweet

Overview

The Tweet class represents a Twitter/X post and provides methods for interacting with tweets such as replying, retweeting, favoriting, and more.

Tweet Class

Attributes

str

The unique identifier of the tweet.

created_at

str

The date and time when the tweet was created.

created_at_datetime

datetime

The created_at converted to datetime object.

user

User

Author of the tweet.

text

str

The full text of the tweet.

full_text

str | None

The full text of the tweet including note tweet content if available.

lang

str

The language of the tweet.

in_reply_to

str | None

The tweet ID this tweet is in reply to, if any.

is_quote_status

bool

Indicates if the tweet is a quote status.

quote

Tweet | None

The Tweet being quoted (if any).

retweeted_tweet

Tweet | None

The Tweet being retweeted (if any).

possibly_sensitive

bool

Indicates if the tweet content may be sensitive.

possibly_sensitive_editable

bool

Indicates if the tweet’s sensitivity can be edited.

quote_count

int

The count of quotes for the tweet.

reply_count

int

The count of replies to the tweet.

favorite_count

int

The count of favorites or likes for the tweet.

favorited

bool

Indicates if the tweet is favorited by the authenticated user.

view_count

int | None

The count of views.

view_count_state

str | None

The state of the tweet views.

retweet_count

int

The count of retweets for the tweet.

bookmark_count

int

The count of bookmarks for the tweet.

bookmarked

bool

Indicates if the tweet is bookmarked by the authenticated user.

media

list[Photo | AnimatedGif | Video]

A list of media entities associated with the tweet. See the media documentation for more details.Example: Download tweet media

place

Place | None

The location associated with the tweet.

editable_until_msecs

int

The timestamp until which the tweet is editable.

is_translatable

bool

Indicates if the tweet is translatable.

is_edit_eligible

bool

Indicates if the tweet is eligible for editing.

edits_remaining

int

The remaining number of edits allowed for the tweet.

edit_tweet_ids

list[int]

List of tweet IDs representing the edit history of the tweet.

replies

Result[Tweet] | None

Replies to the tweet.

reply_to

list[Tweet] | None

A list of Tweet objects representing the tweets to which this tweet replied.

Related tweets.

hashtags

list[str]

Hashtags included in the tweet text.

has_card

bool

Indicates if the tweet contains a card.

thumbnail_title

str | None

The title of the webpage displayed inside tweet’s card.

thumbnail_url

str | None

Link to the image displayed in the tweet’s card.

urls

list

Information about URLs contained in the tweet.

poll

Poll | None

Poll associated with the tweet, if any.

community_note

dict | None

Community note attached to the tweet, containing ‘id’ and ‘text’ fields.

has_community_notes

bool

Indicates if the tweet has community notes.

Methods

delete()

Deletes the tweet. Returns: httpx.Response

await tweet.delete()

favorite()

Favorites (likes) the tweet. Returns: httpx.Response

await tweet.favorite()

See Also: Client.favorite_tweet

unfavorite()

Unfavorites (unlikes) the tweet. Returns: httpx.Response

await tweet.unfavorite()

See Also: Client.unfavorite_tweet

retweet()

Retweets the tweet. Returns: httpx.Response

await tweet.retweet()

See Also: Client.retweet

delete_retweet()

Deletes the retweet. Returns: httpx.Response

await tweet.delete_retweet()

See Also: Client.delete_retweet

bookmark()

Adds the tweet to bookmarks. Returns: httpx.Response

await tweet.bookmark()

See Also: Client.bookmark_tweet

delete_bookmark()

Removes the tweet from bookmarks. Returns: httpx.Response

await tweet.delete_bookmark()

See Also: Client.delete_bookmark

reply()

Replies to the tweet.

text

str

default:"''"

The text content of the reply.

media_ids

list[str] | None

default:"None"

A list of media IDs or URIs to attach to the reply. Media IDs can be obtained by using the upload_media method.

Returns: Tweet - The created tweet.

tweet_text = 'Example text'
media_ids = [
    await client.upload_media('image1.png'),
    await client.upload_media('image2.png')
]
await tweet.reply(
    tweet_text,
    media_ids=media_ids
)

See Also: Client.upload_media

get_retweeters()

Retrieve users who retweeted the tweet.

count

int

default:"40"

The maximum number of users to retrieve.

cursor

str | None

default:"None"

A string indicating the position of the cursor for pagination.

Returns: Result[User] - A list of users who retweeted the tweet.

retweeters = await tweet.get_retweeters()
print(retweeters)
# [<User id="...">, <User id="...">, ..., <User id="...">]

more_retweeters = await retweeters.next()  # Retrieve more retweeters
print(more_retweeters)
# [<User id="...">, <User id="...">, ..., <User id="...">]

get_favoriters()

Retrieve users who favorited the tweet.

count

int

default:"40"

The maximum number of users to retrieve.

cursor

str | None

default:"None"

A string indicating the position of the cursor for pagination.

Returns: Result[User] - A list of users who favorited the tweet.

favoriters = await tweet.get_favoriters()
print(favoriters)
# [<User id="...">, <User id="...">, ..., <User id="...">]

more_favoriters = await favoriters.next()  # Retrieve more favoriters
print(more_favoriters)
# [<User id="...">, <User id="...">, ..., <User id="...">]

get_similar_tweets()

Retrieves tweets similar to the tweet (Twitter premium only). Returns: list[Tweet] - A list of Tweet objects representing tweets similar to the tweet.

similar_tweets = await tweet.get_similar_tweets()

update()

Updates the tweet object with fresh data from the API.

await tweet.update()

Poll Class

Represents a poll associated with a tweet.

Attributes

The tweet associated with the poll.

str

The unique identifier of the poll.

name

str

The name of the poll.

choices

list[dict]

A list containing dictionaries representing poll choices. Each dictionary contains ‘number’, ‘label’, and ‘count’ keys for choice information.

duration_minutes

int

The duration of the poll in minutes.

end_datetime_utc

str

The end date and time of the poll in UTC format.

last_updated_datetime_utc

str

The last updated date and time of the poll in UTC format.

selected_choice

str | None

Number of the selected choice.

counts_are_final

bool

Indicates if the poll counts are final.

Methods

vote()

Vote on the poll with the specified selected choice.

selected_choice

str

required

The label of the selected choice for the vote.

Returns: Poll - The Poll object representing the updated poll after voting.

await poll.vote('Choice 1')

ScheduledTweet Class

Represents a scheduled tweet.

Attributes

str

The unique identifier of the scheduled tweet.

execute_at

int

The timestamp when the tweet is scheduled to be posted.

state

str

The state of the scheduled tweet.

type

str

The type of the tweet.

text

str

The text content of the scheduled tweet.

media

list

A list of media entities to be included in the tweet.

Methods

delete()

Delete the scheduled tweet. Returns: httpx.Response

await scheduled_tweet.delete()

CommunityNote Class

Represents a community note on a tweet.

Attributes

str

The ID of the community note.

text

str

The text content of the community note.

misleading_tags

list[str]

A list of tags indicating misleading information.

trustworthy_sources

bool

Indicates if the sources are trustworthy.

helpful_tags

list[str]

A list of tags indicating helpful information.

created_at

int

The timestamp when the note was created.

can_appeal

bool

Indicates if the note can be appealed.

appeal_status

str

The status of the appeal.

is_media_note

bool

Indicates if the note is related to media content.

media_note_matches

str

Matches related to media content.

birdwatch_profile

dict

Birdwatch profile associated with the note.

tweet_id

str

The ID of the tweet associated with the note.

Methods

update()

Updates the community note object with fresh data from the API.

await community_note.update()

Examples

Basic Tweet Interaction

# Get a tweet
tweet = await client.get_tweet_by_id('1234567890')

# Access tweet properties
print(f"Tweet by {tweet.user.name}: {tweet.text}")
print(f"Likes: {tweet.favorite_count}, Retweets: {tweet.retweet_count}")

# Interact with the tweet
await tweet.favorite()
await tweet.retweet()
await tweet.reply('Great tweet!')

Working with Media

tweet = await client.get_tweet_by_id('1234567890')

if tweet.media:
    for media in tweet.media:
        if isinstance(media, Video):
            print(f"Video: {media.duration_millis}ms")
            # Download the highest quality stream
            streams = media.streams
            if streams:
                await streams[0].download('video.mp4')

Accessing Polls

tweet = await client.get_tweet_by_id('1234567890')

if tweet.poll:
    print(f"Poll: {tweet.poll.name}")
    for choice in tweet.poll.choices:
        print(f"  {choice['label']}: {choice['count']} votes")
    
    # Vote on the poll
    await tweet.poll.vote('Option 1')

Core Classes

Data Models

Additional Features

Overview

Tweet Class

Attributes

Methods

delete()

favorite()

unfavorite()

retweet()

delete_retweet()

bookmark()

delete_bookmark()

reply()

get_retweeters()

get_favoriters()

get_similar_tweets()

update()

Poll Class

Attributes

Methods

vote()

ScheduledTweet Class

Attributes

Methods

delete()

CommunityNote Class

Attributes

Methods

update()

Examples

Basic Tweet Interaction

Working with Media

Accessing Polls

Build docs developers (and LLMs) love

Core Classes

Data Models

Additional Features

​Overview

​Tweet Class

​Attributes

​Methods

​delete()

​favorite()

​unfavorite()

​retweet()

​delete_retweet()

​bookmark()

​delete_bookmark()

​reply()

​get_retweeters()

​get_favoriters()

​get_similar_tweets()

​update()

​Poll Class

​Attributes

​Methods

​vote()

​ScheduledTweet Class

​Attributes

​Methods

​delete()

​CommunityNote Class

​Attributes

​Methods

​update()

​Examples

​Basic Tweet Interaction

​Working with Media

​Accessing Polls

Build docs developers (and LLMs) love

Overview

Tweet Class

Attributes

Methods

delete()

favorite()

unfavorite()

retweet()

delete_retweet()

bookmark()

delete_bookmark()

reply()

get_retweeters()

get_favoriters()

get_similar_tweets()

update()

Poll Class

Attributes

Methods

vote()

ScheduledTweet Class

Attributes

Methods

delete()

CommunityNote Class

Attributes

Methods

update()

Examples

Basic Tweet Interaction

Working with Media

Accessing Polls