Skip to main content

​
Overview

The GuestClient class provides unauthenticated access to public Twitter data. It’s designed for read-only operations without requiring login credentials. All methods are asynchronous and must be executed using await.
GuestClient has limited functionality compared to the authenticated Client. It can only access public information and cannot perform write operations like posting tweets or sending DMs.

​
Initialization

from twikit.guest import GuestClient

client = GuestClient(
    language='en-US',
    proxy='http://proxy.example.com:8080'  # optional
)

# Activate the client to generate a guest token
await client.activate()
​
language
str
default:"en-US"
The language code to use in API requests (e.g., ‘en-US’, ‘ja-JP’).
​
proxy
str | None
default:"None"
The proxy server URL to use for requests (e.g., ‘http://0.0.0.0:8080’).
You must call await client.activate() after initialization to generate a guest token before making any API requests.

​
Activation

​
activate

Activates the client by generating a guest token. This must be called before making any API requests. 
from twikit.guest import GuestClient

client = GuestClient()
guest_token = await client.activate()
print(f"Guest token: {guest_token}")
​
return
str
The generated guest token.

​
User Operations

​
get_user_by_screen_name

Retrieves a user object based on the screen name (username). 
user = await client.get_user_by_screen_name('elonmusk')

print(f"Name: {user.name}")
print(f"Followers: {user.followers_count}")
print(f"Following: {user.following_count}")
print(f"Bio: {user.description}")
​
screen_name
str
required
The screen name (username) of the user to retrieve.
​
return
User
User object containing user details.

​
get_user_by_id

Retrieves a user object based on the user ID. 
user = await client.get_user_by_id('44196397')
print(f"Screen name: {user.screen_name}")
print(f"Name: {user.name}")
​
user_id
str
required
The ID of the user to retrieve.
​
return
User
User object containing user details.

​
Tweet Operations

​
get_user_tweets

Fetches tweets from a specific user’s public timeline. 
# First, get the user
user = await client.get_user_by_screen_name('example_user')

# Then get their tweets
tweets = await client.get_user_tweets(
    user_id=user.id,
    tweet_type='Tweets',
    count=40
)

for tweet in tweets:
    print(f"{tweet.created_at}: {tweet.text}")
    print(f"Likes: {tweet.favorite_count}, Retweets: {tweet.retweet_count}")
    print("---")
​
user_id
str
required
The ID of the Twitter user whose tweets to retrieve.
​
tweet_type
'Tweets'
default:"'Tweets'"
The type of tweets to retrieve. Currently only ‘Tweets’ is supported for guest access.
​
count
int
default:"40"
The number of tweets to retrieve.
​
return
list[Tweet]
List of Tweet objects.
Unlike the authenticated Client, GuestClient does not support pagination for tweets and returns a list instead of a Result object.

​
get_tweet_by_id

Fetches a single tweet by its ID. 
tweet = await client.get_tweet_by_id('1234567890')

print(f"Author: {tweet.user.name}")
print(f"Text: {tweet.text}")
print(f"Likes: {tweet.favorite_count}")
print(f"Retweets: {tweet.retweet_count}")

if tweet.media:
    print(f"Media: {len(tweet.media)} items")
​
tweet_id
str
required
The ID of the tweet to retrieve.
​
return
Tweet
Tweet object containing the tweet data.

​
get_user_highlights_tweets

Retrieves highlighted tweets from a user’s timeline. 
user = await client.get_user_by_screen_name('example_user')

highlights = await client.get_user_highlights_tweets(
    user_id=user.id,
    count=20
)

for tweet in highlights:
    print(tweet.text)

more_highlights = await highlights.next()
​
user_id
str
required
The user ID.
​
count
int
default:"20"
The number of tweets to retrieve.
​
cursor
str | None
default:"None"
Cursor for pagination.
​
return
Result[Tweet]
Result object containing highlighted tweets with pagination support.

​
Limitations

The GuestClient has several limitations compared to the authenticated Client:

​
Read-Only Access

  • Cannot create, delete, or modify tweets
  • Cannot follow/unfollow users
  • Cannot like or retweet tweets
  • Cannot send direct messages
  • Cannot access private accounts or protected tweets

​
Limited Functionality

  • No access to authenticated timeline (For You, Following)
  • No access to bookmarks
  • No access to notifications
  • No access to direct messages
  • Limited tweet search capabilities
  • No access to trends
  • Cannot access user lists
  • Cannot access communities

​
Rate Limits

  • Guest tokens may have stricter rate limits
  • Guest sessions may expire more quickly
  • Some endpoints may return less data

​
Example Usage

from twikit.guest import GuestClient

async def main():
    client = GuestClient()
    await client.activate()
    
    # Get user information
    user = await client.get_user_by_screen_name('elonmusk')
    print(f"{user.name} has {user.followers_count:,} followers")

await main()

​
When to Use GuestClient

Use GuestClient when:
  • You only need to read public data
  • You don’t have Twitter credentials
  • You want to build a read-only monitoring tool
  • You’re analyzing public tweets or user profiles
  • You need to fetch public information without authentication
Use the authenticated Client when:
  • You need to post tweets or interact with content
  • You need access to private or protected accounts
  • You need to use authenticated endpoints
  • You need access to your timeline, bookmarks, or DMs
  • You need higher rate limits

​
Migration to Authenticated Client

If you need more functionality, you can easily migrate from GuestClient to Client: 
from twikit import Client

# Replace GuestClient with Client
client = Client(language='en-US')

# Login instead of activate
await client.login(
    auth_info_1='username',
    auth_info_2='[email protected]',
    password='your_password'
)

# Now you have access to all authenticated features
user = await client.get_user_by_screen_name('example')
await client.follow_user(user.id)
await client.create_tweet('Hello from authenticated client!')
The API for common operations (like get_user_by_screen_name and get_tweet_by_id) is the same between GuestClient and Client, making migration straightforward.

Build docs developers (and LLMs) love

Get started for freeTalk to us