twikit package

Submodules

twikit.client module

class twikit.client.Client(language: str | None = None, proxies: dict | None = None, **kwargs)[source]

Bases: object

A client for interacting with the Twitter API.

Examples

>>> client = Client(language='en-US')

>>> client.login(
...     auth_info_1='example_user',
...     auth_info_2='email@example.com',
...     password='00000000'
... )
login(*, auth_info_1: str, auth_info_2: str | None = None, password: str) → dict[source]

Logs into the account using the specified login information. auth_info_1 and password are required parameters. auth_info_2 is optional and can be omitted, but it is recommended to provide if available. The order in which you specify authentication information (auth_info_1 and auth_info_2) is flexible.

Parameters:

  • auth_info_1 (str) – The first piece of authentication information, which can be a username, email address, or phone number.

  • auth_info_2 (str, default=None) – The second piece of authentication information, which is optional but recommended to provide. It can be a username, email address, or phone number.

  • password (str) – The password associated with the account.

Examples

>>> client.login(
...     auth_info_1='example_user',
...     auth_info_2='email@example.com',
...     password='00000000'
... )
logout() → Response[source]

Logs out of the currently logged-in account.

user_id() → str[source]

Retrieves the user ID associated with the authenticated account.

user() → User[source]

Retrieve detailed information about the authenticated user.

get_cookies() → dict[source]

Get the cookies. You can skip the login procedure by loading the saved cookies using the set_cookies() method.

Examples

>>> client.get_cookies()

See also

set_cookies, load_cookies, save_cookies

save_cookies(path: str) → None[source]

Save cookies to file in json format. You can skip the login procedure by loading the saved cookies using the load_cookies() method.

Parameters:

path (str) – The path to the file where the cookie will be stored.

Examples

>>> client.save_cookies('cookies.json')

See also

load_cookies, get_cookies, set_cookies

set_cookies(cookies: dict, clear_cookies: bool = False) → None[source]

Sets cookies. You can skip the login procedure by loading a saved cookies.

Parameters:

cookies (dict) – The cookies to be set as key value pair.

Examples

>>> with open('cookies.json', 'r', encoding='utf-8') as f:
...     client.set_cookies(json.load(f))

See also

get_cookies, load_cookies, save_cookies

load_cookies(path: str) → None[source]

Loads cookies from a file. You can skip the login procedure by loading a saved cookies.

Parameters:

path (str) – Path to the file where the cookie is stored.

Examples

>>> client.load_cookies('cookies.json')

See also

get_cookies, save_cookies, set_cookies

set_delegate_account(user_id: str | None) → None[source]

Sets the account to act as.

Parameters:

user_id (str | None) – The user ID of the account to act as. Set to None to clear the delegated account.

search_tweet(query: str, product: Literal['Top', 'Latest', 'Media'], count: int = 20, cursor: str | None = None) → Result[Tweet][source]

Searches for tweets based on the specified query and product type.

Parameters:

  • query (str) – The search query.

  • product ({'Top', 'Latest', 'Media'}) – The type of tweets to retrieve.

  • count (int, default=20) – The number of tweets to retrieve, between 1 and 20.

  • cursor (str, default=20) – Token to retrieve more tweets.

Returns:

An instance of the Result class containing the search results.

Return type:

Result[Tweet]

Examples

>>> tweets = client.search_tweet('query', 'Top')
>>> for tweet in tweets:
...    print(tweet)
<Tweet id="...">
<Tweet id="...">
...
...

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

>>> previous_tweets = tweets.previous()  # Retrieve previous tweets
search_user(query: str, count: int = 20, cursor: str | None = None) → Result[User][source]

Searches for users based on the provided query.

Parameters:

  • query (str) – The search query for finding users.

  • count (int, default=20) – The number of users to retrieve in each request.

  • cursor (str, default=None) – Token to retrieve more users.

Returns:

An instance of the Result class containing the search results.

Return type:

Result[User]

Examples

>>> result = client.search_user('query')
>>> for user in result:
...     print(user)
<User id="...">
<User id="...">
...
...

>>> more_results = result.next()  # Retrieve more search results
>>> for user in more_results:
...     print(user)
<User id="...">
<User id="...">
...
...
get_similar_tweets(tweet_id: str) → list[Tweet][source]

Retrieves tweets similar to the specified tweet (Twitter premium only).

Parameters:

tweet_id (str) – The ID of the tweet for which similar tweets are to be retrieved.

Returns:

A list of Tweet objects representing tweets similar to the specified tweet.

Return type:

list[Tweet]

upload_media(source: str | bytes, wait_for_completion: bool = False, status_check_interval: float = 1.0, media_type: str | None = None, media_category: str | None = None, is_long_video: bool = False) → str[source]

Uploads media to twitter.

Parameters:

  • source (str | bytes) – The source of the media to be uploaded. It can be either a file path or bytes of the media content.

  • wait_for_completion (bool, default=False) – Whether to wait for the completion of the media upload process.

  • status_check_interval (float, default=1.0) – The interval (in seconds) to check the status of the media upload process.

  • media_type (str, default=None) – The MIME type of the media. If not specified, it will be guessed from the source.

  • media_category (str, default=None) – The media category.

  • is_long_video (bool, default=False) – If this is True, videos longer than 2:20 can be uploaded. (Twitter Premium only)

Returns:

The media ID of the uploaded media.

Return type:

str

Examples

Videos, images and gifs can be uploaded.

>>> media_id_1 = client.upload_media(
...     'media1.jpg',
... )

>>> media_id_2 = client.upload_media(
...     'media2.mp4',
...     wait_for_completion=True
... )

>>> media_id_3 = client.upload_media(
...     'media3.gif',
...     wait_for_completion=True,
...     media_category='tweet_gif'  # media_category must be specified
... )
check_media_status(media_id: str, is_long_video: bool = False) → dict[source]

Check the status of uploaded media.

Parameters:

media_id (str) – The media ID of the uploaded media.

Returns:

A dictionary containing information about the status of the uploaded media.

Return type:

dict

create_media_metadata(media_id: str, alt_text: str | None = None, sensitive_warning: list[Literal['adult_content', 'graphic_violence', 'other']] = None) → Response[source]

Adds metadata to uploaded media.

Parameters:

  • media_id (str) – The media id for which to create metadata.

  • alt_text (str | None, default=None) – Alternative text for the media.

  • sensitive_warning (list{'adult_content', 'graphic_violence', 'other'}) – A list of sensitive content warnings for the media.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

Examples

>>> media_id = client.upload_media('media.jpg')
>>> client.create_media_metadata(
...     media_id,
...     alt_text='This is a sample media',
...     sensitive_warning=['other']
... )
>>> client.create_tweet(media_ids=[media_id])
get_media(url: str) → bytes[source]

Retrieves media bytes.

Parameters:

url (str) – Media URL

create_poll(choices: list[str], duration_minutes: int) → str[source]

Creates a poll and returns card-uri.

Parameters:

  • choices (list[str]) – A list of choices for the poll. Maximum of 4 choices.

  • duration_minutes (int) – The duration of the poll in minutes.

Returns:

The URI of the created poll card.

Return type:

str

Examples

Create a poll with three choices lasting for 60 minutes:

>>> choices = ['Option A', 'Option B', 'Option C']
>>> duration_minutes = 60
>>> card_uri = client.create_poll(choices, duration_minutes)
>>> print(card_uri)
'card://0000000000000000000'
vote(selected_choice: str, card_uri: str, tweet_id: str, card_name: str) → Poll[source]

Vote on a poll with the selected choice.

Parameters:

  • selected_choice (str) – The label of the selected choice for the vote.

  • card_uri (str) – The URI of the poll card.

  • tweet_id (str) – The ID of the original tweet containing the poll.

  • card_name (str) – The name of the poll card.

Returns:

The Poll object representing the updated poll after voting.

Return type:

Poll

create_tweet(text: str = '', media_ids: list[str] | None = None, poll_uri: str | None = None, reply_to: str | None = None, conversation_control: Literal['followers', 'verified', 'mentioned'] | None = None, attachment_url: str | None = None, community_id: str | None = None, share_with_followers: bool = False, is_note_tweet: bool = False, richtext_options: list[dict] | None = None, edit_tweet_id: str | None = None) → Tweet[source]

Creates a new tweet on Twitter with the specified text, media, and poll.

Parameters:

  • text (str, default=’’) – The text content of the tweet.

  • media_ids (list[str], default=None) – A list of media IDs or URIs to attach to the tweet. media IDs can be obtained by using the upload_media method.

  • poll_uri (str, default=None) – The URI of a Twitter poll card to attach to the tweet. Poll URIs can be obtained by using the create_poll method.

  • reply_to (str, default=None) – The ID of the tweet to which this tweet is a reply.

  • conversation_control ({'followers', 'verified', 'mentioned'}) – The type of conversation control for the tweet: - ‘followers’: Limits replies to followers only. - ‘verified’: Limits replies to verified accounts only. - ‘mentioned’: Limits replies to mentioned accounts only.

  • attachment_url (str) – URL of the tweet to be quoted.

  • is_note_tweet (class`bool`, default=False) – If this option is set to True, tweets longer than 280 characters can be posted (Twitter Premium only).

  • richtext_options (list[dict], default=None) – Options for decorating text (Twitter Premium only).

  • edit_tweet_id (str | None, default=None) – ID of the tweet to edit (Twitter Premium only).

Raises:

DuplicateTweet –

Returns:

The Created Tweet.

Return type:

Tweet

Examples

Create a tweet with media:

>>> tweet_text = 'Example text'
>>> media_ids = [
...     client.upload_media('image1.png'),
...     client.upload_media('image2.png')
... ]
>>> client.create_tweet(
...     tweet_text,
...     media_ids=media_ids
... )

Create a tweet with a poll:

>>> tweet_text = 'Example text'
>>> poll_choices = ['Option A', 'Option B', 'Option C']
>>> duration_minutes = 60
>>> poll_uri = client.create_poll(poll_choices, duration_minutes)
>>> client.create_tweet(
...     tweet_text,
...     poll_uri=poll_uri
... )

See also

upload_media, create_poll

create_scheduled_tweet(scheduled_at: int, text: str = '', media_ids: list[str] | None = None) → str[source]

Schedules a tweet to be posted at a specified timestamp.

Parameters:

  • scheduled_at (int) – The timestamp when the tweet should be scheduled for posting.

  • text (str, default=’’) – The text content of the tweet, by default an empty string.

  • media_ids (list[str], default=None) – A list of media IDs to be attached to the tweet, by default None.

Returns:

The ID of the scheduled tweet.

Return type:

str

Examples

Create a tweet with media:

>>> scheduled_time = int(time.time()) + 3600  # One hour from now
>>> tweet_text = 'Example text'
>>> media_ids = [
...     client.upload_media('image1.png'),
...     client.upload_media('image2.png')
... ]
>>> client.create_scheduled_tweet(
...     scheduled_time
...     tweet_text,
...     media_ids=media_ids
... )
delete_tweet(tweet_id: str) → Response[source]

Deletes a tweet.

Parameters:

tweet_id (str) – ID of the tweet to be deleted.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

Examples

>>> tweet_id = '0000000000'
>>> delete_tweet(tweet_id)
get_user_by_screen_name(screen_name: str) → User[source]

Fetches a user by screen name.

Parameter

screen_namestr

The screen name of the Twitter user.

returns:

An instance of the User class representing the Twitter user.

rtype:

User

Examples

>>> target_screen_name = 'example_user'
>>> user = client.get_user_by_name(target_screen_name)
>>> print(user)
<User id="...">
get_user_by_id(user_id: str) → User[source]

Fetches a user by ID

Parameter

user_idstr

The ID of the Twitter user.

returns:

An instance of the User class representing the Twitter user.

rtype:

User

Examples

>>> target_screen_name = '000000000'
>>> user = client.get_user_by_id(target_screen_name)
>>> print(user)
<User id="000000000">
get_tweet_by_id(tweet_id: str, cursor: str | None = None) → Tweet[source]

Fetches a tweet by tweet ID.

Parameters:

tweet_id (str) – The ID of the tweet.

Returns:

A Tweet object representing the fetched tweet.

Return type:

Tweet

Examples

>>> target_tweet_id = '...'
>>> tweet = client.get_tweet_by_id(target_tweet_id)
>>> print(tweet)
<Tweet id="...">
get_scheduled_tweets() → list[ScheduledTweet][source]

Retrieves scheduled tweets.

Returns:

List of ScheduledTweet objects representing the scheduled tweets.

Return type:

list[ScheduledTweet]

delete_scheduled_tweet(tweet_id: str) → Response[source]

Delete a scheduled tweet.

Parameters:

tweet_id (str) – The ID of the scheduled tweet to delete.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

get_retweeters(tweet_id: str, count: int = 40, cursor: str | None = None) → Result[User][source]

Retrieve users who retweeted a specific tweet.

Parameters:

  • tweet_id (str) – The ID of the tweet.

  • count (int, default=40) – The maximum number of users to retrieve.

  • cursor (str, default=None) – A string indicating the position of the cursor for pagination.

Returns:

A list of users who retweeted the tweet.

Return type:

Result[User]

Examples

>>> tweet_id = '...'
>>> retweeters = client.get_retweeters(tweet_id)
>>> print(retweeters)
[<User id="...">, <User id="...">, ..., <User id="...">]

>>> more_retweeters = retweeters.next()  # Retrieve more retweeters.
>>> print(more_retweeters)
[<User id="...">, <User id="...">, ..., <User id="...">]
get_favoriters(tweet_id: str, count: int = 40, cursor: str | None = None) → Result[User][source]

Retrieve users who favorited a specific tweet.

Parameters:

  • tweet_id (str) – The ID of the tweet.

  • count (int, default=40) – The maximum number of users to retrieve.

  • cursor (str, default=None) – A string indicating the position of the cursor for pagination.

Returns:

A list of users who favorited the tweet.

Return type:

Result[User]

Examples

>>> tweet_id = '...'
>>> favoriters = client.get_favoriters(tweet_id)
>>> print(favoriters)
[<User id="...">, <User id="...">, ..., <User id="...">]

>>> more_favoriters = favoriters.next()  # Retrieve more favoriters.
>>> print(more_favoriters)
[<User id="...">, <User id="...">, ..., <User id="...">]
get_community_note(note_id: str) → CommunityNote[source]

Fetches a community note by ID.

Parameters:

note_id (str) – The ID of the community note.

Returns:

A CommunityNote object representing the fetched community note.

Return type:

CommunityNote

Raises:

TwitterException – Invalid note ID.

Examples

>>> note_id = '...'
>>> note = client.get_community_note(note_id)
>>> print(note)
<CommunityNote id="...">
get_user_tweets(user_id: str, tweet_type: Literal['Tweets', 'Replies', 'Media', 'Likes'], count: int = 40, cursor: str | None = None) → Result[Tweet][source]

Fetches tweets from a specific user’s timeline.

Parameters:

  • user_id (str) – The ID of the Twitter user whose tweets to retrieve. To get the user id from the screen name, you can use get_user_by_screen_name method.

  • tweet_type ({'Tweets', 'Replies', 'Media', 'Likes'}) – The type of tweets to retrieve.

  • count (int, default=40) – The number of tweets to retrieve.

  • cursor (str, default=None) – The cursor for fetching the next set of results.

Returns:

A Result object containing a list of Tweet objects.

Return type:

Result[Tweet]

Examples

>>> user_id = '...'

If you only have the screen name, you can get the user id as follows:

>>> screen_name = 'example_user'
>>> user = client.get_user_by_screen_name(screen_name)
>>> user_id = user.id

>>> tweets = client.get_user_tweets(user_id, 'Tweets', count=20)
>>> for tweet in tweets:
...    print(tweet)
<Tweet id="...">
<Tweet id="...">
...
...

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

>>> previous_tweets = tweets.previous()  # Retrieve previous tweets

See also

get_user_by_screen_name

get_timeline(count: int = 20, seen_tweet_ids: list[str] | None = None, cursor: str | None = None) → Result[Tweet][source]

Retrieves the timeline. Retrieves tweets from Home -> For You.

Parameters:

  • count (int, default=20) – The number of tweets to retrieve.

  • seen_tweet_ids (list[str], default=None) – A list of tweet IDs that have been seen.

  • cursor (str, default=None) – A cursor for pagination.

Returns:

A Result object containing a list of Tweet objects.

Return type:

Result[Tweet]

Example

>>> tweets = client.get_timeline()
>>> for tweet in tweets:
...     print(tweet)
<Tweet id="...">
<Tweet id="...">
...
...
>>> more_tweets = tweets.next() # Retrieve more tweets
>>> for tweet in more_tweets:
...     print(tweet)
<Tweet id="...">
<Tweet id="...">
...
...
get_latest_timeline(count: int = 20, seen_tweet_ids: list[str] | None = None, cursor: str | None = None) → Result[Tweet][source]

Retrieves the timeline. Retrieves tweets from Home -> Following.

Parameters:

  • count (int, default=20) – The number of tweets to retrieve.

  • seen_tweet_ids (list[str], default=None) – A list of tweet IDs that have been seen.

  • cursor (str, default=None) – A cursor for pagination.

Returns:

A Result object containing a list of Tweet objects.

Return type:

Result[Tweet]

Example

>>> tweets = client.get_latest_timeline()
>>> for tweet in tweets:
...     print(tweet)
<Tweet id="...">
<Tweet id="...">
...
...
>>> more_tweets = tweets.next() # Retrieve more tweets
>>> for tweet in more_tweets:
...     print(tweet)
<Tweet id="...">
<Tweet id="...">
...
...
favorite_tweet(tweet_id: str) → Response[source]

Favorites a tweet.

Parameters:

tweet_id (str) – The ID of the tweet to be liked.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

Examples

>>> tweet_id = '...'
>>> client.favorite_tweet(tweet_id)

See also

unfavorite_tweet

unfavorite_tweet(tweet_id: str) → Response[source]

Unfavorites a tweet.

Parameters:

tweet_id (str) – The ID of the tweet to be unliked.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

Examples

>>> tweet_id = '...'
>>> client.unfavorite_tweet(tweet_id)

See also

favorite_tweet

retweet(tweet_id: str) → Response[source]

Retweets a tweet.

Parameters:

tweet_id (str) – The ID of the tweet to be retweeted.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

Examples

>>> tweet_id = '...'
>>> client.retweet(tweet_id)

See also

delete_retweet

delete_retweet(tweet_id: str) → Response[source]

Deletes the retweet.

Parameters:

tweet_id (str) – The ID of the retweeted tweet to be unretweeted.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

Examples

>>> tweet_id = '...'
>>> client.delete_retweet(tweet_id)

See also

retweet

bookmark_tweet(tweet_id: str, folder_id: str | None = None) → Response[source]

Adds the tweet to bookmarks.

Parameters:

  • tweet_id (str) – The ID of the tweet to be bookmarked.

  • folder_id (str | None, default=None) – The ID of the folder to add the bookmark to.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

Examples

>>> tweet_id = '...'
>>> client.bookmark_tweet(tweet_id)
delete_bookmark(tweet_id: str) → Response[source]

Removes the tweet from bookmarks.

Parameters:

tweet_id (str) – The ID of the tweet to be removed from bookmarks.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

Examples

>>> tweet_id = '...'
>>> client.delete_bookmark(tweet_id)

See also

bookmark_tweet

get_bookmarks(count: int = 20, cursor: str | None = None, folder_id: str | None = None) → Result[Tweet][source]

Retrieves bookmarks from the authenticated user’s Twitter account.

Parameters:

  • count (int, default=20) – The number of bookmarks to retrieve.

  • folder_id (str | None, default=None) – Folder to retrieve bookmarks.

Returns:

A Result object containing a list of Tweet objects representing bookmarks.

Return type:

Result[Tweet]

Example

>>> bookmarks = client.get_bookmarks()
>>> for bookmark in bookmarks:
...     print(bookmark)
<Tweet id="...">
<Tweet id="...">

>>> more_bookmarks = bookmarks.next()  # To retrieve more bookmarks
>>> for bookmark in more_bookmarks:
...     print(bookmark)
<Tweet id="...">
<Tweet id="...">
delete_all_bookmarks() → Response[source]

Deleted all bookmarks.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

Examples

>>> client.delete_all_bookmarks()
get_bookmark_folders(cursor: str | None = None) → Result[BookmarkFolder][source]

Retrieves bookmark folders.

Returns:

Result object containing a list of bookmark folders.

Return type:

Result[BookmarkFolder]

Examples

>>> folders = client.get_bookmark_folders()
>>> print(folders)
[<BookmarkFolder id="...">, ..., <BookmarkFolder id="...">]
>>> more_folders = folders.next()  # Retrieve more folders
edit_bookmark_folder(folder_id: str, name: str) → BookmarkFolder[source]

Edits a bookmark folder.

Parameters:

  • folder_id (str) – ID of the folder to edit.

  • name (str) – New name for the folder.

Returns:

Updated bookmark folder.

Return type:

BookmarkFolder

Examples

>>> client.edit_bookmark_folder('123456789', 'MyFolder')
delete_bookmark_folder(folder_id: str) → Response[source]

Deletes a bookmark folder.

Parameters:

folder_id (str) – ID of the folder to delete.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

create_bookmark_folder(name: str) → BookmarkFolder[source]

Creates a bookmark folder.

Parameters:

name (str) – Name of the folder.

Returns:

Newly created bookmark folder.

Return type:

BookmarkFolder

follow_user(user_id: str) → Response[source]

Follows a user.

Parameters:

user_id (str) – The ID of the user to follow.

Returns:

Response returned from twitter api.

Return type:

httpx.Response:class:

Examples

>>> user_id = '...'
>>> client.follow_user(user_id)

See also

unfollow_user

unfollow_user(user_id: str) → Response[source]

Unfollows a user.

Parameters:

user_id (str) – The ID of the user to unfollow.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

Examples

>>> user_id = '...'
>>> client.unfollow_user(user_id)

See also

follow_user

block_user(user_id: str) → Response[source]

Blocks a user.

Parameters:

user_id (str) – The ID of the user to block.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

See also

unblock_user

unblock_user(user_id: str) → Response[source]

Unblocks a user.

Parameters:

user_id (str) – The ID of the user to unblock.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

See also

block_user

mute_user(user_id: str) → Response[source]

Mutes a user.

Parameters:

user_id (str) – The ID of the user to mute.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

See also

unmute_user

unmute_user(user_id: str) → Response[source]

Unmutes a user.

Parameters:

user_id (str) – The ID of the user to unmute.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

See also

mute_user

Retrieves trending topics on Twitter.

Parameters:

  • category ({'trending', 'for-you', 'news', 'sports', 'entertainment'}) – The category of trends to retrieve. Valid options include: - ‘trending’: General trending topics. - ‘for-you’: Trends personalized for the user. - ‘news’: News-related trends. - ‘sports’: Sports-related trends. - ‘entertainment’: Entertainment-related trends.

  • count (int, default=20) – The number of trends to retrieve.

  • retry (bool, default=True) – If no trends are fetched continuously retry to fetch trends.

  • additional_request_params (dict, default=None) – Parameters to be added on top of the existing trends API parameters. Typically, it is used as additional_request_params = {‘candidate_source’: ‘trends’} when this function doesn’t work otherwise.

Returns:

A list of Trend objects representing the retrieved trends.

Return type:

list[Trend]

Examples

>>> trends = client.get_trends('trending')
>>> for trend in trends:
...     print(trend)
<Trend name="...">
<Trend name="...">
...
get_user_followers(user_id: str, count: int = 20, cursor: str | None = None) → Result[User][source]

Retrieves a list of followers for a given user.

Parameters:

  • user_id (str) – The ID of the user for whom to retrieve followers.

  • count (int, default=20) – The number of followers to retrieve.

Returns:

A list of User objects representing the followers.

Return type:

Result[User]

get_user_verified_followers(user_id: str, count: int = 20, cursor: str | None = None) → Result[User][source]

Retrieves a list of verified followers for a given user.

Parameters:

  • user_id (str) – The ID of the user for whom to retrieve verified followers.

  • count (int, default=20) – The number of verified followers to retrieve.

Returns:

A list of User objects representing the verified followers.

Return type:

Result[User]

get_user_followers_you_know(user_id: str, count: int = 20, cursor: str | None = None) → Result[User][source]

Retrieves a list of common followers.

Parameters:

  • user_id (str) – The ID of the user for whom to retrieve followers you might know.

  • count (int, default=20) – The number of followers you might know to retrieve.

Returns:

A list of User objects representing the followers you might know.

Return type:

Result[User]

get_user_following(user_id: str, count: int = 20, cursor: str | None = None) → Result[User][source]

Retrieves a list of users whom the given user is following.

Parameters:

  • user_id (str) – The ID of the user for whom to retrieve the following users.

  • count (int, default=20) – The number of following users to retrieve.

Returns:

A list of User objects representing the users being followed.

Return type:

Result[User]

get_user_subscriptions(user_id: str, count: int = 20, cursor: str | None = None) → Result[User][source]

Retrieves a list of users to which the specified user is subscribed.

Parameters:

  • user_id (str) – The ID of the user for whom to retrieve subscriptions.

  • count (int, default=20) – The number of subscriptions to retrieve.

Returns:

A list of User objects representing the subscribed users.

Return type:

Result[User]

send_dm(user_id: str, text: str, media_id: str | None = None, reply_to: str | None = None) → Message[source]

Send a direct message to a user.

Parameters:

  • user_id (str) – The ID of the user to whom the direct message will be sent.

  • text (str) – 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 object containing information about the message sent.

Return type:

Message

Examples

>>> # send DM with media
>>> user_id = '000000000'
>>> media_id = client.upload_media('image.png')
>>> message = client.send_dm(user_id, 'text', media_id)
>>> print(message)
<Message id='...'>

See also

upload_media, delete_dm

add_reaction_to_message(message_id: str, conversation_id: str, emoji: str) → Response[source]

Adds a reaction emoji to a specific message in a conversation.

Parameters:

  • message_id (str) – The ID of the message to which the reaction emoji will be added. Group ID (‘00000000’) or partner_ID-your_ID (‘00000000-00000001’)

  • conversation_id (str) – The ID of the conversation containing the message.

  • emoji (str) – The emoji to be added as a reaction.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

Examples

>>> message_id = '00000000'
>>> conversation_id = f'00000001-{client.user_id()}'
>>> client.add_reaction_to_message(
...    message_id, conversation_id, 'Emoji here'
... )
remove_reaction_from_message(message_id: str, conversation_id: str, emoji: str) → Response[source]

Remove a reaction from a message.

Parameters:

  • message_id (str) – The ID of the message from which to remove the reaction.

  • conversation_id (str) – The ID of the conversation where the message is located. Group ID (‘00000000’) or partner_ID-your_ID (‘00000000-00000001’)

  • emoji (str) – The emoji to remove as a reaction.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

Examples

>>> message_id = '00000000'
>>> conversation_id = f'00000001-{client.user_id()}'
>>> client.remove_reaction_from_message(
...    message_id, conversation_id, 'Emoji here'
... )
delete_dm(message_id: str) → Response[source]

Deletes a direct message with the specified message ID.

Parameters:

message_id (str) – The ID of the direct message to be deleted.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

Examples

>>> client.delete_dm('0000000000')
get_dm_history(user_id: str, max_id: str | None = None) → Result[Message][source]

Retrieves the DM conversation history with a specific user.

Parameters:

  • user_id (str) – The ID of the user with whom the DM conversation history will be retrieved.

  • max_id (str, default=None) – If specified, retrieves messages older than the specified max_id.

Returns:

A Result object containing a list of Message objects representing the DM conversation history.

Return type:

Result[Message]

Examples

>>> messages = client.get_dm_history('0000000000')
>>> for message in messages:
>>>     print(message)
<Message id="...">
<Message id="...">
...
...

>>> more_messages = messages.next()  # Retrieve more messages
>>> for message in more_messages:
>>>     print(message)
<Message id="...">
<Message id="...">
...
...
send_dm_to_group(group_id: str, text: str, media_id: str | None = None, reply_to: str | None = None) → GroupMessage[source]

Sends a message to a group.

Parameters:

  • group_id (str) – The ID of the group in which the direct message will be sent.

  • text (str) – 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:

GroupMessage object containing information about the message sent.

Return type:

GroupMessage

Examples

>>> # send DM with media
>>> group_id = '000000000'
>>> media_id = client.upload_media('image.png')
>>> message = client.send_dm_to_group(group_id, 'text', media_id)
>>> print(message)
<GroupMessage id='...'>

See also

upload_media, delete_dm

get_group_dm_history(group_id: str, max_id: str | None = None) → Result[GroupMessage][source]

Retrieves the DM conversation history in a group.

Parameters:

  • group_id (str) – The ID of the group in which the DM conversation history will be retrieved.

  • max_id (str, default=None) – If specified, retrieves messages older than the specified max_id.

Returns:

A Result object containing a list of GroupMessage objects representing the DM conversation history.

Return type:

Result[GroupMessage]

Examples

>>> messages = client.get_group_dm_history('0000000000')
>>> for message in messages:
>>>     print(message)
<GroupMessage id="...">
<GroupMessage id="...">
...
...

>>> more_messages = messages.next()  # Retrieve more messages
>>> for message in more_messages:
>>>     print(message)
<GroupMessage id="...">
<GroupMessage id="...">
...
...
get_group(group_id: str) → Group[source]

Fetches a guild by ID.

Parameters:

group_id (str) – The ID of the group to retrieve information for.

Returns:

An object representing the retrieved group.

Return type:

Group

add_members_to_group(group_id: str, user_ids: list[str]) → Response[source]

Adds members to a group.

Parameters:

  • group_id (str) – ID of the group to which the member is to be added.

  • user_ids (list[str]) – List of IDs of users to be added.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

Examples

>>> group_id = '...'
>>> members = ['...']
>>> client.add_members_to_group(group_id, members)
change_group_name(group_id: str, name: str) → Response[source]

Changes group name

Parameters:

  • group_id (str) – ID of the group to be renamed.

  • name (str) – New name.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

create_list(name: str, description: str = '', is_private: bool = False) → List[source]

Creates a list.

Parameters:

  • name (str) – The name of the list.

  • description (str, default=’’) – The description of the list.

  • is_private (bool, default=False) – Indicates whether the list is private (True) or public (False).

Returns:

The created list.

Return type:

list

Examples

>>> list = client.create_list(
...     'list name',
...     'list description',
...     is_private=True
... )
>>> print(list)
<List id="...">
edit_list_banner(list_id: str, media_id: str) → Response[source]

Edit the banner image of a list.

Parameters:

  • list_id (str) – The ID of the list.

  • media_id (str) – The ID of the media to use as the new banner image.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

Examples

>>> list_id = '...'
>>> media_id = client.upload_media('image.png')
>>> client.edit_list_banner(list_id, media_id)
delete_list_banner(list_id: str) → Response[source]

Deletes list banner.

Parameters:

list_id (str) – ID of the list from which the banner is to be removed.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

edit_list(list_id: str, name: str | None = None, description: str | None = None, is_private: bool | None = None) → List[source]

Edits list information.

Parameters:

  • list_id (str) – The ID of the list to edit.

  • name (str, default=None) – The new name for the list.

  • description (str, default=None) – The new description for the list.

  • is_private (bool, default=None) – Indicates whether the list should be private (True) or public (False).

Returns:

The updated Twitter list.

Return type:

list

Examples

>>> client.edit_list(
...     'new name', 'new description', True
... )
add_list_member(list_id: str, user_id: str) → Response[source]

Adds a user to a list.

Parameters:

  • list_id (str) – The ID of the list.

  • user_id (str) – The ID of the user to add to the list.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

Examples

>>> client.add_list_member('list id', 'user id')
remove_list_member(list_id: str, user_id: str) → Response[source]

Removes a user from a list.

Parameters:

  • list_id (str) – The ID of the list.

  • user_id (str) – The ID of the user to remove from the list.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

Examples

>>> client.remove_list_member('list id', 'user id')
get_lists(count: int = 100, cursor: str = None) → Result[List][source]

Retrieves a list of user lists.

Parameters:

count (int) – The number of lists to retrieve.

Returns:

Retrieved lists.

Return type:

Result[List]

Examples

>>> lists = client.get_lists()
>>> for list_ in lists:
...     print(list_)
<List id="...">
<List id="...">
...
...
>>> more_lists = lists.next()  # Retrieve more lists
get_list(list_id: str) → List[source]

Retrieve list by ID.

Parameters:

list_id (str) – The ID of the list to retrieve.

Returns:

List object.

Return type:

List

get_list_tweets(list_id: str, count: int = 20, cursor: str | None = None) → Result[Tweet][source]

Retrieves tweets from a list.

Parameters:

  • list_id (str) – The ID of the list to retrieve tweets from.

  • count (int, default=20) – The number of tweets to retrieve.

  • cursor (str, default=None) – The cursor for pagination.

Returns:

A Result object containing the retrieved tweets.

Return type:

Result[Tweet]

Examples

>>> tweets = client.get_list_tweets('list id')
>>> for tweet in tweets:
...    print(tweet)
<Tweet id="...">
<Tweet id="...">
...
...

>>> more_tweets = tweets.next()  # Retrieve more tweets
>>> for tweet in more_tweets:
...     print(tweet)
<Tweet id="...">
<Tweet id="...">
...
...
get_list_members(list_id: str, count: int = 20, cursor: str | None = None) → Result[User][source]

Retrieves members of a list.

Parameters:

  • list_id (str) – List ID.

  • count (int, default=20) – Number of members to retrieve.

Returns:

Members of a list

Return type:

Result[User]

Examples

>>> members = client.get_list_members(123456789)
>>> for member in members:
...     print(member)
<User id="...">
<User id="...">
...
...
>>> more_members = members.next()  # Retrieve more members
get_list_subscribers(list_id: str, count: int = 20, cursor: str | None = None) → Result[User][source]

Retrieves subscribers of a list.

Parameters:

  • list_id (str) – List ID.

  • count (int, default=20) – Number of subscribers to retrieve.

Returns:

Subscribers of a list

Return type:

Result[User]

Examples

>>> members = client.get_list_subscribers(123456789)
>>> for subscriber in subscribers:
...     print(subscriber)
<User id="...">
<User id="...">
...
...
>>> more_subscribers = members.next()  # Retrieve more subscribers
search_list(query: str, count: int = 20, cursor: str | None = None) → Result[List][source]

Search for lists based on the provided query.

Parameters:

  • query (str) – The search query.

  • count (int, default=20) – The number of lists to retrieve.

Returns:

An instance of the Result class containing the search results.

Return type:

Result[List]

Examples

>>> lists = client.search_list('query')
>>> for list in lists:
...     print(list)
<List id="...">
<List id="...">
...

>>> more_lists = lists.next()  # Retrieve more lists
get_notifications(type: Literal['All', 'Verified', 'Mentions'], count: int = 40, cursor: str | None = None) → Result[Notification][source]

Retrieve notifications based on the provided type.

Parameters:

  • type ({'All', 'Verified', 'Mentions'}) – Type of notifications to retrieve. All: All notifications Verified: Notifications relating to authenticated users Mentions: Notifications with mentions

  • count (int, default=40) – Number of notifications to retrieve.

Returns:

List of retrieved notifications.

Return type:

Result[Notification]

Examples

>>> notifications = client.get_notifications('All')
>>> for notification in notifications:
...     print(notification)
<Notification id="...">
<Notification id="...">
...
...

>>> # Retrieve more notifications
>>> more_notifications = notifications.next()
search_community(query: str, cursor: str | None = None) → Result[Community][source]

Searchs communities based on the specified query.

Parameters:

query (str) – The search query.

Returns:

List of retrieved communities.

Return type:

Result[Community]

Examples

>>> communities = client.search_communities('query')
>>> for community in communities:
...     print(community)
<Community id="...">
<Community id="...">
...

>>> more_communities = communities.next()  # Retrieve more communities
get_community(community_id: str) → Community[source]

Retrieves community by ID.

Parameters:

list_id (str) – The ID of the community to retrieve.

Returns:

Community object.

Return type:

Community

get_community_tweets(community_id: str, tweet_type: Literal['Top', 'Latest', 'Media'], count: int = 40, cursor: str | None = None) → Result[Tweet][source]

Retrieves tweets from a community.

Parameters:

  • community_id (str) – The ID of the community.

  • tweet_type ({'Top', 'Latest', 'Media'}) – The type of tweets to retrieve.

  • count (int, default=40) – The number of tweets to retrieve.

Returns:

List of retrieved tweets.

Return type:

Result[Tweet]

Examples

>>> community_id = '...'
>>> tweets = client.get_community_tweets(community_id, 'Latest')
>>> for tweet in tweets:
...     print(tweet)
<Tweet id="...">
<Tweet id="...">
...
>>> more_tweets = tweets.next()  # Retrieve more tweets
get_communities_timeline(count: int = 20, cursor: str | None = None) → Result[Tweet][source]

Retrieves tweets from communities timeline.

Parameters:

count (int, default=20) – The number of tweets to retrieve.

Returns:

List of retrieved tweets.

Return type:

Result[Tweet]

Examples

>>> tweets = client.get_communities_timeline()
>>> for tweet in tweets:
...     print(tweet)
<Tweet id="...">
<Tweet id="...">
...
>>> more_tweets = tweets.next()  # Retrieve more tweets
join_community(community_id: str) → Community[source]

Join a community.

Parameters:

community_id (str) – The ID of the community to join.

Returns:

The joined community.

Return type:

Community

leave_community(community_id: str) → Community[source]

Leave a community.

Parameters:

community_id (str) – The ID of the community to leave.

Returns:

The left community.

Return type:

Community

request_to_join_community(community_id: str, answer: str | None = None) → Community[source]

Request to join a community.

Parameters:

  • community_id (str) – The ID of the community to request to join.

  • answer (str, default=None) – The answer to the join request.

Returns:

The requested community.

Return type:

Community

get_community_members(community_id: str, count: int = 20, cursor: str | None = None) → Result[CommunityMember][source]

Retrieves members of a community.

Parameters:

  • community_id (str) – The ID of the community.

  • count (int, default=20) – The number of members to retrieve.

Returns:

List of retrieved members.

Return type:

Result[CommunityMember]

get_community_moderators(community_id: str, count: int = 20, cursor: str | None = None) → Result[CommunityMember][source]

Retrieves moderators of a community.

Parameters:

  • community_id (str) – The ID of the community.

  • count (int, default=20) – The number of moderators to retrieve.

Returns:

List of retrieved moderators.

Return type:

Result[CommunityMember]

search_community_tweet(community_id: str, query: str, count: int = 20, cursor: str | None = None) → Result[Tweet][source]

Searchs tweets in a community.

Parameters:

  • community_id (str) – The ID of the community.

  • query (str) – The search query.

  • count (int, default=20) – The number of tweets to retrieve.

Returns:

List of retrieved tweets.

Return type:

Result[Tweet]

twikit.tweet module

class twikit.tweet.Tweet(client: Client, data: dict, user: User = None)[source]

Bases: object

id

The unique identifier of the tweet.

Type:

str

created_at

The date and time when the tweet was created.

Type:

str

created_at_datetime

The created_at converted to datetime.

Type:

datetime

user

Author of the tweet.

Type:

User

text

The full text of the tweet.

Type:

str

lang

The language of the tweet.

Type:

str

in_reply_to

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

Type:

str

is_quote_status

Indicates if the tweet is a quote status.

Type:

bool

quote

The Tweet being quoted (if any)

Type:

Tweet

retweeted_tweet

Whether the tweet is a retweet

Type:

bool

possibly_sensitive

Indicates if the tweet content may be sensitive.

Type:

bool

possibly_sensitive_editable

Indicates if the tweet’s sensitivity can be edited.

Type:

bool

quote_count

The count of quotes for the tweet.

Type:

int

media

A list of media entities associated with the tweet.

Type:

list

reply_count

The count of replies to the tweet.

Type:

int

favorite_count

The count of favorites or likes for the tweet.

Type:

int

favorited

Indicates if the tweet is favorited.

Type:

bool

view_count

The count of views.

Type:

int | None

retweet_count

The count of retweets for the tweet.

Type:

int

editable_until_msecs

The timestamp until which the tweet is editable.

Type:

int

is_translatable

Indicates if the tweet is translatable.

Type:

bool

is_edit_eligible

Indicates if the tweet is eligible for editing.

Type:

bool

edits_remaining

The remaining number of edits allowed for the tweet.

Type:

int

state

The state of the tweet views.

Type:

str | None

replies

Replies to the tweet.

Type:

Result[Tweet] | None

reply_to

A list of Tweet objects representing the tweets to which to reply.

Type:

list[Tweet] | None

related_tweets

Related tweets.

Type:

list[Tweet] | None

hashtags

Hashtags included in the tweet text.

Type:

list[str]

poll

Poll attached to the tweet.

Type:

Poll

has_card

Indicates if the tweet contains a card.

Type:

bool

thumbnail_title

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

Type:

str | None

thumbnail_url

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

Type:

str | None

urls

Information about URLs contained in the tweet.

Type:

list

full_text

The full text of the tweet.

Type:

str | None

property created_at_datetime: datetime
property poll: Poll
delete() → Response[source]

Deletes the tweet.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

Examples

>>> tweet.delete()
favorite() → Response[source]

Favorites the tweet.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

See also

Client.favorite_tweet

unfavorite() → Response[source]

Favorites the tweet.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

See also

Client.unfavorite_tweet

retweet() → Response[source]

Retweets the tweet.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

See also

Client.retweet

delete_retweet() → Response[source]

Deletes the retweet.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

See also

Client.delete_retweet

bookmark() → Response[source]

Adds the tweet to bookmarks.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

See also

Client.bookmark_tweet

delete_bookmark() → Response[source]

Removes the tweet from bookmarks.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

See also

Client.delete_bookmark

reply(text: str = '', media_ids: list[str] | None = None, **kwargs) → Tweet[source]

Replies to the tweet.

Parameters:

  • text (str, default=’’) – The text content of the reply.

  • media_ids (list[str], 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:

The created tweet.

Return type:

Tweet

Examples

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

See also

None

get_retweeters(count: str = 40, cursor: str | None = None) → Result[User][source]

Retrieve users who retweeted the tweet.

Parameters:

  • count (int, default=40) – The maximum number of users to retrieve.

  • cursor (str, default=None) – A string indicating the position of the cursor for pagination.

Returns:

A list of users who retweeted the tweet.

Return type:

Result[User]

Examples

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

>>> more_retweeters = retweeters.next()  # Retrieve more retweeters.
>>> print(more_retweeters)
[<User id="...">, <User id="...">, ..., <User id="...">]
get_favoriters(count: str = 40, cursor: str | None = None) → Result[User][source]

Retrieve users who favorited a specific tweet.

Parameters:

  • tweet_id (str) – The ID of the tweet.

  • count (int, default=40) – The maximum number of users to retrieve.

  • cursor (str, default=None) – A string indicating the position of the cursor for pagination.

Returns:

A list of users who favorited the tweet.

Return type:

Result[User]

Examples

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

>>> more_favoriters = favoriters.next()  # Retrieve more favoriters.
>>> print(more_favoriters)
[<User id="...">, <User id="...">, ..., <User id="...">]
get_similar_tweets() → list[Tweet][source]

Retrieves tweets similar to the tweet (Twitter premium only).

Returns:

A list of Tweet objects representing tweets similar to the tweet.

Return type:

list[Tweet]

update() → None[source]
twikit.tweet.tweet_from_data(client: Client, data: dict) → Tweet[source]
class twikit.tweet.ScheduledTweet(client: Client, data: dict)[source]

Bases: object

delete() → Response[source]

Delete the scheduled tweet.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

class twikit.tweet.TweetTombstone(client: Client, tweet_id: str, data: dict)[source]

Bases: object

class twikit.tweet.Poll(client: Client, data: dict, tweet: Tweet | None = None)[source]

Bases: object

Represents a poll associated with a tweet.

tweet

The tweet associated with the poll.

Type:

Tweet

id

The unique identifier of the poll.

Type:

str

name

The name of the poll.

Type:

str

choices

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

Type:

list[dict]

duration_minutes

The duration of the poll in minutes.

Type:

int

end_datetime_utc

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

Type:

str

last_updated_datetime_utc

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

Type:

str

selected_choice

Number of the selected choice.

Type:

str | None

vote(selected_choice: str) → Poll[source]

Vote on the poll with the specified selected choice.

Parameters:

selected_choice (str) – The label of the selected choice for the vote.

Returns:

The Poll object representing the updated poll after voting.

Return type:

Poll

class twikit.tweet.CommunityNote(client: Client, data: dict)[source]

Bases: object

Represents a community note.

id

The ID of the community note.

Type:

str

text

The text content of the community note.

Type:

str

misleading_tags

A list of tags indicating misleading information.

Type:

list[str]

trustworthy_sources

Indicates if the sources are trustworthy.

Type:

bool

helpful_tags

A list of tags indicating helpful information.

Type:

list[str]

created_at

The timestamp when the note was created.

Type:

int

can_appeal

Indicates if the note can be appealed.

Type:

bool

appeal_status

The status of the appeal.

Type:

str

is_media_note

Indicates if the note is related to media content.

Type:

bool

media_note_matches

Matches related to media content.

Type:

str

birdwatch_profile

Birdwatch profile associated with the note.

Type:

dict

tweet_id

The ID of the tweet associated with the note.

Type:

str

update() → None[source]

twikit.user module

class twikit.user.User(client: Client, data: dict)[source]

Bases: object

id

The unique identifier of the user.

Type:

str

created_at

The date and time when the user account was created.

Type:

str

name

The user’s name.

Type:

str

screen_name

The user’s screen name.

Type:

str

profile_image_url

The URL of the user’s profile image (HTTPS version).

Type:

str

profile_banner_url

The URL of the user’s profile banner.

Type:

str

url

The user’s URL.

Type:

str

location

The user’s location information.

Type:

str

description

The user’s profile description.

Type:

str

description_urls

URLs found in the user’s profile description.

Type:

list

urls

URLs associated with the user.

Type:

list

pinned_tweet_ids

The IDs of tweets that the user has pinned to their profile.

Type:

str

is_blue_verified

Indicates if the user is verified with a blue checkmark.

Type:

bool

verified

Indicates if the user is verified.

Type:

bool

possibly_sensitive

Indicates if the user’s content may be sensitive.

Type:

bool

can_dm

Indicates whether the user can receive direct messages.

Type:

bool

can_media_tag

Indicates whether the user can be tagged in media.

Type:

bool

want_retweets

Indicates if the user wants retweets.

Type:

bool

default_profile

Indicates if the user has the default profile.

Type:

bool

default_profile_image

Indicates if the user has the default profile image.

Type:

bool

has_custom_timelines

Indicates if the user has custom timelines.

Type:

bool

followers_count

The count of followers.

Type:

int

fast_followers_count

The count of fast followers.

Type:

int

normal_followers_count

The count of normal followers.

Type:

int

following_count

The count of users the user is following.

Type:

int

favourites_count

The count of favorites or likes.

Type:

int

listed_count

The count of lists the user is a member of.

Type:

int

media_count

The count of media items associated with the user.

Type:

int

statuses_count

The count of tweets.

Type:

int

is_translator

Indicates if the user is a translator.

Type:

bool

translator_type

The type of translator.

Type:

str

profile_interstitial_type

The type of profile interstitial.

Type:

str

withheld_in_countries

Countries where the user’s content is withheld.

Type:

list[str]

property created_at_datetime: datetime
get_tweets(tweet_type: Literal['Tweets', 'Replies', 'Media', 'Likes'], count: int = 40) → Result[Tweet][source]

Retrieves the user’s tweets.

Parameters:

  • tweet_type ({'Tweets', 'Replies', 'Media', 'Likes'}) – The type of tweets to retrieve.

  • count (int, default=40) – The number of tweets to retrieve.

Returns:

A Result object containing a list of Tweet objects.

Return type:

Result[Tweet]

Examples

>>> user = client.get_user_by_screen_name('example_user')
>>> tweets = user.get_tweets('Tweets', count=20)
>>> for tweet in tweets:
...    print(tweet)
<Tweet id="...">
<Tweet id="...">
...
...

>>> more_tweets = tweets.next()  # Retrieve more tweets
>>> for tweet in more_tweets:
...     print(tweet)
<Tweet id="...">
<Tweet id="...">
...
...
follow() → Response[source]

Follows the user.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

See also

Client.follow_user

unfollow() → Response[source]

Unfollows the user.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

See also

Client.unfollow_user

block() → Response[source]

Blocks a user.

Parameters:

user_id (str) – The ID of the user to block.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

See also

unblock

unblock() → Response[source]

Unblocks a user.

Parameters:

user_id (str) – The ID of the user to unblock.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

See also

block

mute() → Response[source]

Mutes a user.

Parameters:

user_id (str) – The ID of the user to mute.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

See also

unmute

unmute() → Response[source]

Unmutes a user.

Parameters:

user_id (str) – The ID of the user to unmute.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

See also

mute

get_followers(count: int = 20) → Result[User][source]

Retrieves a list of followers for the user.

Parameters:

count (int, default=20) – The number of followers to retrieve.

Returns:

A list of User objects representing the followers.

Return type:

Result[User]

See also

Client.get_user_followers

get_verified_followers(count: int = 20) → Result[User][source]

Retrieves a list of verified followers for the user.

Parameters:

count (int, default=20) – The number of verified followers to retrieve.

Returns:

A list of User objects representing the verified followers.

Return type:

Result[User]

See also

Client.get_user_verified_followers

get_followers_you_know(count: int = 20) → Result[User][source]

Retrieves a list of followers whom the user might know.

Parameters:

count (int, default=20) – The number of followers you might know to retrieve.

Returns:

A list of User objects representing the followers you might know.

Return type:

Result[User]

See also

Client.get_user_followers_you_know

get_following(count: int = 20) → Result[User][source]

Retrieves a list of users whom the user is following.

Parameters:

count (int, default=20) – The number of following users to retrieve.

Returns:

A list of User objects representing the users being followed.

Return type:

Result[User]

See also

Client.get_user_following

get_subscriptions(count: int = 20) → Result[User][source]

Retrieves a list of users whom the user is subscribed to.

Parameters:

count (int, default=20) – The number of subscriptions to retrieve.

Returns:

A list of User objects representing the subscribed users.

Return type:

Result[User]

See also

Client.get_user_subscriptions

send_dm(text: str, media_id: str = None, reply_to=None) → Message[source]

Send a direct message to the user.

Parameters:

  • text (str) – 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 object containing information about the message sent.

Return type:

Message

Examples

>>> # send DM with media
>>> media_id = client.upload_media('image.png')
>>> message = user.send_dm('text', media_id)
>>> print(message)
<Message id='...'>

See also

Client.upload_media, Client.send_dm

get_dm_history(max_id: str = None) → Result[Message][source]

Retrieves the DM conversation history with the user.

Parameters:

max_id (str, default=None) – If specified, retrieves messages older than the specified max_id.

Returns:

A Result object containing a list of Message objects representing the DM conversation history.

Return type:

Result[Message]

Examples

>>> messages = user.get_dm_history()
>>> for message in messages:
>>>     print(message)
<Message id="...">
<Message id="...">
...
...

>>> more_messages = messages.next()  # Retrieve more messages
>>> for message in more_messages:
>>>     print(message)
<Message id="...">
<Message id="...">
...
...
update() → None[source]

twikit.message module

class twikit.message.Message(client: Client, data: dict, sender_id: str, recipient_id: str)[source]

Bases: object

Represents a direct message.

id

The ID of the message.

Type:

str

time

The timestamp of the message.

Type:

str

text

The text content of the message.

Type:

str

attachment

Attachment Information.

Type:

dict

reply(text: str, media_id: str | None = None) → Message[source]

Replies to the message.

Parameters:

  • text (str) – 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.

Returns:

Message object containing information about the message sent.

Return type:

Message

See also

Client.send_dm

add_reaction(emoji: str) → Response[source]

Adds a reaction to the message.

Parameters:

emoji (str) – The emoji to be added as a reaction.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

remove_reaction(emoji: str) → Response[source]

Removes a reaction from the message.

Parameters:

emoji (str) – The emoji to be removed.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

delete() → Response[source]

Deletes the message.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

See also

Client.delete_dm

twikit.trend module

class twikit.trend.Trend(client: Client, data: dict)[source]

Bases: object

name

The name of the trending topic.

Type:

str

tweets_count

The count of tweets associated with the trend.

Type:

int

domain_context

The context or domain associated with the trend.

Type:

str

A list of trend names grouped under the main trend.

Type:

list[str]

twikit.list module

class twikit.list.List(client: Client, data: dict)[source]

Bases: object

Class representing a Twitter List.

id

The unique identifier of the List.

Type:

str

created_at

The timestamp when the List was created.

Type:

int

default_banner

Information about the default banner of the List.

Type:

dict

banner

Information about the banner of the List. If custom banner is not set, it defaults to the default banner.

Type:

dict

description

The description of the List.

Type:

str

following

Indicates if the authenticated user is following the List.

Type:

bool

is_member

Indicates if the authenticated user is a member of the List.

Type:

bool

member_count

The number of members in the List.

Type:

int

mode

The mode of the List, either ‘Private’ or ‘Public’.

Type:

{‘Private’, ‘Public’}

muting

Indicates if the authenticated user is muting the List.

Type:

bool

name

The name of the List.

Type:

str

pinning

Indicates if the List is pinned.

Type:

bool

subscriber_count

The number of subscribers to the List.

Type:

int

property created_at_datetime: datetime
edit_banner(media_id: str) → Response[source]

Edit the banner image of the list.

Parameters:

media_id (str) – The ID of the media to use as the new banner image.

Returns:

Response returned from twitter api.

Return type:

httpx.Response

Examples

>>> media_id = client.upload_media('image.png')
>>> media.edit_banner(media_id)
delete_banner() → Response[source]

Deletes the list banner.

edit(name: str | None = None, description: str | None = None, is_private: bool | None = None) → List[source]

Edits list information.

Parameters:

  • name (str, default=None) – The new name for the list.

  • description (str, default=None) – The new description for the list.

  • is_private (bool, default=None) – Indicates whether the list should be private (True) or public (False).

Returns:

The updated Twitter list.

Return type:

List

Examples

>>> list.edit(
...     'new name', 'new description', True
... )
add_member(user_id: str) → Response[source]

Adds a member to the list.

remove_member(user_id: str) → Response[source]

Removes a member from the list.

get_tweets(count: int = 20, cursor: str | None = None) → Result[Tweet][source]

Retrieves tweets from the list.

Parameters:

  • count (int, default=20) – The number of tweets to retrieve.

  • cursor (str, default=None) – The cursor for pagination.

Returns:

A Result object containing the retrieved tweets.

Return type:

Result[Tweet]

Examples

>>> tweets = list.get_tweets()
>>> for tweet in tweets:
...    print(tweet)
<Tweet id="...">
<Tweet id="...">
...
...

>>> more_tweets = tweets.next()  # Retrieve more tweets
>>> for tweet in more_tweets:
...     print(tweet)
<Tweet id="...">
<Tweet id="...">
...
...
get_members(count: int = 20, cursor: str | None = None) → Result[User][source]

Retrieves members of the list.

Parameters:

count (int, default=20) – Number of members to retrieve.

Returns:

Members of the list

Return type:

Result[User]

Examples

>>> members = list_.get_members()
>>> for member in members:
...     print(member)
<User id="...">
<User id="...">
...
...
>>> more_members = members.next()  # Retrieve more members
get_subscribers(count: int = 20, cursor: str | None = None) → Result[User][source]

Retrieves subscribers of the list.

Parameters:

count (int, default=20) – Number of subscribers to retrieve.

Returns:

Subscribers of the list

Return type:

Result[User]

Examples

>>> subscribers = list_.get_subscribers()
>>> for subscriber in subscribers:
...     print(subscriber)
<User id="...">
<User id="...">
...
...
>>> more_subscribers = subscribers.next()  # Retrieve more subscribers
update() → None[source]

twikit.community module

class twikit.community.CommunityCreator(id, screen_name, verified)[source]

Bases: NamedTuple

id: str

Alias for field number 0

screen_name: str

Alias for field number 1

verified: bool

Alias for field number 2

class twikit.community.CommunityRule(id, name)[source]

Bases: NamedTuple

id: str

Alias for field number 0

name: str

Alias for field number 1

class twikit.community.CommunityMember(client: Client, data: dict)[source]

Bases: object

class twikit.community.Community(client: Client, data: dict)[source]

Bases: object

id

The ID of the community.

Type:

str

name

The name of the community.

Type:

str

member_count

The count of members in the community.

Type:

int

is_nsfw

Indicates if the community is NSFW.

Type:

bool

members_facepile_results

The profile image URLs of members.

Type:

list[str]

banner

The banner information of the community.

Type:

dict

is_member

Indicates if the user is a member of the community.

Type:

bool

role

The role of the user in the community.

Type:

str

description

The description of the community.

Type:

str

creator

The creator of the community.

Type:

User | CommunityCreator

admin

The admin of the community.

Type:

User

join_policy

The join policy of the community.

Type:

str

created_at

The timestamp of the community’s creation.

Type:

int

invites_policy

The invites policy of the community.

Type:

str

is_pinned

Indicates if the community is pinned.

Type:

bool

rules

The rules of the community.

Type:

list[CommunityRule]

get_tweets(tweet_type: Literal['Top', 'Latest', 'Media'], count: int = 40, cursor: str | None = None) → Result[Tweet][source]

Retrieves tweets from the community.

Parameters:

  • tweet_type ({'Top', 'Latest', 'Media'}) – The type of tweets to retrieve.

  • count (int, default=40) – The number of tweets to retrieve.

Returns:

List of retrieved tweets.

Return type:

Result[Tweet]

Examples

>>> tweets = community.get_tweets('Latest')
>>> for tweet in tweets:
...     print(tweet)
<Tweet id="...">
<Tweet id="...">
...
>>> more_tweets = tweets.next()  # Retrieve more tweets
join() → Community[source]

Join the community.

leave() → Community[source]

Leave the community.

request_to_join(answer: str | None = None) → Community[source]

Request to join the community.

get_members(count: int = 20, cursor: str | None = None) → Result[CommunityMember][source]

Retrieves members of the community.

Parameters:

count (int, default=20) – The number of members to retrieve.

Returns:

List of retrieved members.

Return type:

Result[CommunityMember]

get_moderators(count: int = 20, cursor: str | None = None) → Result[CommunityMember][source]

Retrieves moderators of the community.

Parameters:

count (int, default=20) – The number of moderators to retrieve.

Returns:

List of retrieved moderators.

Return type:

Result[CommunityMember]

search_tweet(query: str, count: int = 20, cursor: str | None = None) → Result[Tweet][source]

Searchs tweets in the community.

Parameters:

  • query (str) – The search query.

  • count (int, default=20) – The number of tweets to retrieve.

Returns:

List of retrieved tweets.

Return type:

Result[Tweet]

update() → None[source]

twikit.notification module

class twikit.notification.Notification(client: Client, data: dict, tweet: Tweet, from_user: User)[source]

Bases: object

id

The unique identifier of the notification.

Type:

str

timestamp_ms

The timestamp of the notification in milliseconds.

Type:

int

icon

Dictionary containing icon data for the notification.

Type:

dict

message

The message text of the notification.

Type:

str

tweet

The tweet associated with the notification.

Type:

Tweet

from_user

The user who triggered the notification.

Type:

User

twikit.utils module

class twikit.utils.Endpoint[source]

Bases: object

A class containing Twitter API endpoints.

LOGIN_FLOW = 'https://api.twitter.com/1.1/onboarding/task.json'
LOGOUT = 'https://api.twitter.com/1.1/account/logout.json'
CREATE_TWEET = 'https://twitter.com/i/api/graphql/SiM_cAu83R0wnrpmKQQSEw/CreateTweet'
CREATE_NOTE_TWEET = 'https://twitter.com/i/api/graphql/iCUB42lIfXf9qPKctjE5rQ/CreateNoteTweet'
DELETE_TWEET = 'https://twitter.com/i/api/graphql/VaenaVgh5q5ih7kvyVjgtg/DeleteTweet'
SEARCH_TIMELINE = 'https://twitter.com/i/api/graphql/flaR-PUMshxFWZWPNpq4zA/SearchTimeline'
UPLOAD_MEDIA = 'https://upload.twitter.com/i/media/upload.json'
UPLOAD_MEDIA_2 = 'https://upload.twitter.com/i/media/upload2.json'
CREATE_MEDIA_METADATA = 'https://api.twitter.com/1.1/media/metadata/create.json'
GUEST_TOKEN = 'https://api.twitter.com/1.1/guest/activate.json'
CREATE_CARD = 'https://caps.twitter.com/v2/cards/create.json'
USER_BY_SCREEN_NAME = 'https://twitter.com/i/api/graphql/NimuplG1OB7Fd2btCLdBOw/UserByScreenName'
USER_BY_REST_ID = 'https://twitter.com/i/api/graphql/tD8zKvQzwY3kdx5yz6YmOw/UserByRestId'
USER_TWEETS = 'https://twitter.com/i/api/graphql/QWF3SzpHmykQHsQMixG0cg/UserTweets'
USER_TWEETS_AND_REPLIES = 'https://twitter.com/i/api/graphql/vMkJyzx1wdmvOeeNG0n6Wg/UserTweetsAndReplies'
USER_MEDIA = 'https://twitter.com/i/api/graphql/2tLOJWwGuCTytDrGBg8VwQ/UserMedia'
USER_LIKES = 'https://twitter.com/i/api/graphql/IohM3gxQHfvWePH5E3KuNA/Likes'
TWEET_DETAIL = 'https://twitter.com/i/api/graphql/U0HTv-bAWTBYylwEMT7x5A/TweetDetail'
TREND = 'https://twitter.com/i/api/2/guide.json'
FAVORITE_TWEET = 'https://twitter.com/i/api/graphql/lI07N6Otwv1PhnEgXILM7A/FavoriteTweet'
UNFAVORITE_TWEET = 'https://twitter.com/i/api/graphql/ZYKSe-w7KEslx3JhSIk5LA/UnfavoriteTweet'
CREATE_RETWEET = 'https://twitter.com/i/api/graphql/ojPdsZsimiJrUGLR1sjUtA/CreateRetweet'
DELETE_RETWEET = 'https://twitter.com/i/api/graphql/iQtK4dl5hBmXewYZuEOKVw/DeleteRetweet'
CREATE_BOOKMARK = 'https://twitter.com/i/api/graphql/aoDbu3RHznuiSkQ9aNM67Q/CreateBookmark'
DELETE_BOOKMARK = 'https://twitter.com/i/api/graphql/Wlmlj2-xzyS1GN3a6cj-mQ/DeleteBookmark'
CREATE_FRIENDSHIPS = 'https://twitter.com/i/api/1.1/friendships/create.json'
DESTROY_FRIENDSHIPS = 'https://twitter.com/i/api/1.1/friendships/destroy.json'
HOME_TIMELINE = 'https://twitter.com/i/api/graphql/-X_hcgQzmHGl29-UXxz4sw/HomeTimeline'
HOME_LATEST_TIMELINE = 'https://twitter.com/i/api/graphql/U0cdisy7QFIoTfu3-Okw0A/HomeLatestTimeline'
FOLLOWERS = 'https://twitter.com/i/api/graphql/gC_lyAxZOptAMLCJX5UhWw/Followers'
BLUE_VERIFIED_FOLLOWERS = 'https://twitter.com/i/api/graphql/VmIlPJNEDVQ29HfzIhV4mw/BlueVerifiedFollowers'
FOLLOWING = 'https://twitter.com/i/api/graphql/2vUj-_Ek-UmBVDNtd8OnQA/Following'
FOLLOWERS_YOU_KNOW = 'https://twitter.com/i/api/graphql/f2tbuGNjfOE8mNUO5itMew/FollowersYouKnow'
SUBSCRIPTIONS = 'https://twitter.com/i/api/graphql/Wsm5ZTCYtg2eH7mXAXPIgw/UserCreatorSubscriptions'
SEND_DM = 'https://twitter.com/i/api/1.1/dm/new2.json'
DELETE_DM = 'https://twitter.com/i/api/graphql/BJ6DtxA2llfjnRoRjaiIiw/DMMessageDeleteMutation'
INBOX_INITIAL_STATE = 'https://twitter.com/i/api/1.1/dm/inbox_initial_state.json'
CONVERSASION = 'https://twitter.com/i/api/1.1/dm/conversation/{}.json'
CREATE_SCHEDULED_TWEET = 'https://twitter.com/i/api/graphql/LCVzRQGxOaGnOnYH01NQXg/CreateScheduledTweet'
BOOKMARKS = 'https://twitter.com/i/api/graphql/qToeLeMs43Q8cr7tRYXmaQ/Bookmarks'
BOOKMARKS_ALL_DELETE = 'https://twitter.com/i/api/graphql/skiACZKC1GDYli-M8RzEPQ/BookmarksAllDelete'
RETWEETERS = 'https://twitter.com/i/api/graphql/X-XEqG5qHQSAwmvy00xfyQ/Retweeters'
FAVORITERS = 'https://twitter.com/i/api/graphql/LLkw5EcVutJL6y-2gkz22A/Favoriters'
ADD_MEMBER_TO_GROUP = 'https://twitter.com/i/api/graphql/oBwyQ0_xVbAQ8FAyG0pCRA/AddParticipantsMutation'
CHANGE_GROUP_NAME = 'https://twitter.com/i/api/1.1/dm/conversation/{}/update_name.json'
CREATE_LIST = 'https://twitter.com/i/api/graphql/EYg7JZU3A1eJ-wr2eygPHQ/CreateList'
LIST_ADD_MEMBER = 'https://twitter.com/i/api/graphql/lLNsL7mW6gSEQG6rXP7TNw/ListAddMember'
LIST_LATEST_TWEETS = 'https://twitter.com/i/api/graphql/HjsWc-nwwHKYwHenbHm-tw/ListLatestTweetsTimeline'
UPDATE_LIST = 'https://twitter.com/i/api/graphql/dIEI1sbSAuZlxhE0ggrezA/UpdateList'
LIST_MEMBERS = 'https://twitter.com/i/api/graphql/BQp2IEYkgxuSxqbTAr1e1g/ListMembers'
LIST_SUBSCRIBERS = 'https://twitter.com/i/api/graphql/74wGEkaBxrdoXakWTWMxRQ/ListSubscribers'
MUTE_LIST = 'https://twitter.com/i/api/graphql/ZYyanJsskNUcltu9bliMLA/MuteList'
UNMUTE_LIST = 'https://twitter.com/i/api/graphql/pMZrHRNsmEkXgbn3tOyr7Q/UnmuteList'
EDIT_LIST_BANNER = 'https://twitter.com/i/api/graphql/t_DsROHldculsB0B9BUAWw/EditListBanner'
DELETE_LIST_BANNER = 'https://twitter.com/i/api/graphql/Y90WuxdWugtMRJhkXTdvzg/DeleteListBanner'
LIST_REMOVE_MEMBER = 'https://twitter.com/i/api/graphql/cvDFkG5WjcXV0Qw5nfe1qQ/ListRemoveMember'
LIST_BY_REST_ID = 'https://twitter.com/i/api/graphql/9hbYpeVBMq8-yB8slayGWQ/ListByRestId'
BLOCK_USER = 'https://twitter.com/i/api/1.1/blocks/create.json'
UNBLOCK_USER = 'https://twitter.com/i/api/1.1/blocks/destroy.json'
MUTE_USER = 'https://twitter.com/i/api/1.1/mutes/users/create.json'
UNMUTE_USER = 'https://twitter.com/i/api/1.1/mutes/users/destroy.json'
MESSAGE_ADD_REACTION = 'https://twitter.com/i/api/graphql/VyDyV9pC2oZEj6g52hgnhA/useDMReactionMutationAddMutation'
MESSAGE_REMOVE_REACTION = 'https://twitter.com/i/api/graphql/bV_Nim3RYHsaJwMkTXJ6ew/useDMReactionMutationRemoveMutation'
FETCH_SCHEDULED_TWEETS = 'https://twitter.com/i/api/graphql/ITtjAzvlZni2wWXwf295Qg/FetchScheduledTweets'
DELETE_SCHEDULED_TWEET = 'https://twitter.com/i/api/graphql/CTOVqej0JBXAZSwkp1US0g/DeleteScheduledTweet'
SETTINGS = 'https://api.twitter.com/1.1/account/settings.json'
LIST_MANAGEMENT = 'https://twitter.com/i/api/graphql/47170qwZCt5aFo9cBwFoNA/ListsManagementPageTimeline'
NOTIFICATIONS_ALL = 'https://twitter.com/i/api/2/notifications/all.json'
NOTIFICATIONS_VERIFIED = 'https://twitter.com/i/api/2/notifications/verified.json'
NOTIFICATIONS_MENTIONES = 'https://twitter.com/i/api/2/notifications/mentions.json'
VOTE = 'https://caps.twitter.com/v2/capi/passthrough/1'
REPORT_FLOW = 'https://twitter.com/i/api/1.1/report/flow.json'
FETCH_COMMUNITY_NOTE = 'https://twitter.com/i/api/graphql/fKWPPj271aTM-AB9Xp48IA/BirdwatchFetchOneNote'
SEARCH_COMMUNITY = 'https://twitter.com/i/api/graphql/daVUkhfHn7-Z8llpYVKJSw/CommunitiesSearchQuery'
GET_COMMUNITY = 'https://twitter.com/i/api/graphql/lUBKrilodgg9Nikaw3cIiA/CommunityQuery'
COMMUNITY_TWEETS = 'https://twitter.com/i/api/graphql/mhwSsmub4JZgHcs0dtsjrw/CommunityTweetsTimeline'
COMMUNITY_MEDIA = 'https://twitter.com/i/api/graphql/Ht5K2ckaZYAOuRFmFfbHig/CommunityMediaTimeline'
COMMUNITIES_TIMELINE = 'https://twitter.com/i/api/graphql/4-4iuIdaLPpmxKnA3mr2LA/CommunitiesMainPageTimeline'
JOIN_COMMUNITY = 'https://twitter.com/i/api/graphql/xZQLbDwbI585YTG0QIpokw/JoinCommunity'
REQUEST_TO_JOIN_COMMUNITY = 'https://twitter.com/i/api/graphql/XwWChphD_6g7JnsFus2f2Q/RequestToJoinCommunity'
LEAVE_COMMUNITY = 'https://twitter.com/i/api/graphql/OoS6Kd4-noNLXPZYHtygeA/LeaveCommunity'
COMMUNITY_MEMBERS = 'https://twitter.com/i/api/graphql/KDAssJ5lafCy-asH4wm1dw/membersSliceTimeline_Query'
COMMUNITY_MODERATORS = 'https://twitter.com/i/api/graphql/9KI_r8e-tgp3--N5SZYVjg/moderatorsSliceTimeline_Query'
SEARCH_COMMUNITY_TWEET = 'https://twitter.com/i/api/graphql/5341rmzzvdjqfmPKfoHUBw/CommunityTweetSearchModuleQuery'
SIMILAR_POSTS = 'https://twitter.com/i/api/graphql/EToazR74i0rJyZYalfVEAQ/SimilarPosts'
BOOKMARK_FOLDERS = 'https://twitter.com/i/api/graphql/i78YDd0Tza-dV4SYs58kRg/BookmarkFoldersSlice'
EDIT_BOOKMARK_FOLDER = 'https://twitter.com/i/api/graphql/a6kPp1cS1Dgbsjhapz1PNw/EditBookmarkFolder'
DELETE_BOOKMARK_FOLDER = 'https://twitter.com/i/api/graphql/2UTTsO-6zs93XqlEUZPsSg/DeleteBookmarkFolder'
CREATE_BOOKMARK_FOLDER = 'https://twitter.com/i/api/graphql/6Xxqpq8TM_CREYiuof_h5w/createBookmarkFolder'
BOOKMARK_FOLDER_TIMELINE = 'https://twitter.com/i/api/graphql/8HoabOvl7jl9IC1Aixj-vg/BookmarkFolderTimeline'
BOOKMARK_TO_FOLDER = 'https://twitter.com/i/api/graphql/4KHZvvNbHNf07bsgnL9gWA/bookmarkTweetToFolder'
class twikit.utils.Result(results: list[T], fetch_next_result: Callable | None = None, next_cursor: str | None = None, fetch_previous_result: Callable | None = None, previous_cursor: str | None = None)[source]

Bases: Generic[T]

This class is for storing multiple results. The next method can be used to retrieve further results. As with a regular list, you can access elements by specifying indexes and iterate over elements using a for loop.

next_cursor

Cursor used to obtain the next result.

Type:

str

previous_cursor

Cursor used to obtain the previous result.

Type:

str

token

Alias of next_cursor.

Type:

str

cursor

Alias of next_cursor.

Type:

str

next() → Result[T][source]

The next result.

previous() → Result[T][source]

The previous result.

property cursor: str

Alias of next_token

property token: str

Alias of next_token

class twikit.utils.Flow(client: Client, endpoint: str, headers: dict)[source]

Bases: object

execute_task(*subtask_inputs, **kwargs) → None[source]
property token: str | None
property task_id: str | None
twikit.utils.find_dict(obj: list | dict, key: str | int, find_one: bool = False) → list[Any][source]

Retrieves elements from a nested dictionary.

twikit.utils.get_query_id(url: str) → str[source]

Extracts the identifier from a URL.

Examples

>>> get_query_id('https://twitter.com/i/api/graphql/queryid/...')
'queryid'
twikit.utils.urlencode(data: dict[str, Any]) → str[source]

Encodes a dictionary into a URL-encoded string.

twikit.utils.timestamp_to_datetime(timestamp: str) → datetime[source]
twikit.utils.build_tweet_data(raw_data: dict) → dict[source]
twikit.utils.build_user_data(raw_data: dict) → dict[source]
twikit.utils.flatten_params(params: dict) → dict[source]
twikit.utils.b64_to_str(b64: str) → str[source]
class twikit.utils.SearchOptions[source]

Bases: TypedDict

exact_phrases: list[str]
or_keywords: list[str]
exclude_keywords: list[str]
hashtags: list[str]
from_user: str
to_user: str
mentioned_users: list[str]
filters: list[Literal['media', 'retweets', 'native_video', 'periscope', 'vine', 'images', 'twimg', 'links']]
exclude_filters: list[Literal['media', 'retweets', 'native_video', 'periscope', 'vine', 'images', 'twimg', 'links']]
urls: list[str]
since: str
until: str
positive: bool
negative: bool
question: bool
twikit.utils.build_query(text: str, options: SearchOptions) → str[source]

Builds a search query based on the given text and search options.

Parameters:

  • text (str) – The base text of the search query.

  • options (SearchOptions) –

    A dictionary containing various search options. - exact_phrases: list[str]

    List of exact phrases to include in the search query.

    • or_keywords: list[str]

      List of keywords where tweets must contain at least one of these keywords.

    • exclude_keywords: list[str]

      A list of keywords that the tweet must contain these keywords.

    • hashtags: list[str]

      List of hashtags to include in the search query.

    • from_user: str

      Specify a username. Only tweets from this user will be includedin the search.

    • to_user: str

      Specify a username. Only tweets sent to this user will be included in the search.

    • mentioned_users: list[str]

      List of usernames. Only tweets mentioning these users will be included in the search.

    • filters: list[FILTERS]

      List of tweet filters to include in the search query.

    • exclude_filters: list[FILTERS]

      List of tweet filters to exclude from the search query.

    • urls: list[str]

      List of URLs. Only tweets containing these URLs will be included in the search.

    • since: str

      Specify a date (formatted as ‘YYYY-MM-DD’). Only tweets since this date will be included in the search.

    • until: str

      Specify a date (formatted as ‘YYYY-MM-DD’). Only tweets until this date will be included in the search.

    • positive: bool

      Include positive sentiment in the search.

    • negative: bool

      Include negative sentiment in the search.

    • question: bool

      Search for tweets in questionable form.

    https://developer.twitter.com/en/docs/twitter-api/v1/rules-and-filtering/search-operators

Returns:

The constructed Twitter search query.

Return type:

str

twikit.errors module

exception twikit.errors.TwitterException(*args: object, headers: dict | None = None)[source]

Bases: Exception

Base class for Twitter API related exceptions.

exception twikit.errors.BadRequest(*args: object, headers: dict | None = None)[source]

Bases: TwitterException

Exception raised for 400 Bad Request errors.

exception twikit.errors.Unauthorized(*args: object, headers: dict | None = None)[source]

Bases: TwitterException

Exception raised for 401 Unauthorized errors.

exception twikit.errors.Forbidden(*args: object, headers: dict | None = None)[source]

Bases: TwitterException

Exception raised for 403 Forbidden errors.

exception twikit.errors.NotFound(*args: object, headers: dict | None = None)[source]

Bases: TwitterException

Exception raised for 404 Not Found errors.

exception twikit.errors.RequestTimeout(*args: object, headers: dict | None = None)[source]

Bases: TwitterException

Exception raised for 408 Request Timeout errors.

exception twikit.errors.TooManyRequests(*args, headers: dict | None = None)[source]

Bases: TwitterException

Exception raised for 429 Too Many Requests errors.

exception twikit.errors.ServerError(*args: object, headers: dict | None = None)[source]

Bases: TwitterException

Exception raised for 5xx Server Error responses.

exception twikit.errors.CouldNotTweet(*args: object, headers: dict | None = None)[source]

Bases: TwitterException

Exception raised when a tweet could not be sent.

exception twikit.errors.DuplicateTweet(*args: object, headers: dict | None = None)[source]

Bases: CouldNotTweet

Exception raised when a tweet is a duplicate of another.

exception twikit.errors.TweetNotAvailable(*args: object, headers: dict | None = None)[source]

Bases: TwitterException

Exceptions raised when a tweet is not available.

exception twikit.errors.InvalidMedia(*args: object, headers: dict | None = None)[source]

Bases: TwitterException

Exception raised when there is a problem with the media ID sent with the tweet.

exception twikit.errors.UserNotFound(*args: object, headers: dict | None = None)[source]

Bases: TwitterException

Exception raised when a user does not exsit.

exception twikit.errors.UserUnavailable(*args: object, headers: dict | None = None)[source]

Bases: TwitterException

Exception raised when a user is unavailable.

twikit.errors.raise_exceptions_from_response(errors: list[dict])[source]

Module contents

Twikit Twitter API Wrapper

A Python library for interacting with the Twitter API.