Overview
The List class represents a Twitter/X List and provides methods for managing list members, retrieving tweets, and modifying list settings.
List Class
Attributes
The unique identifier of the List.
The timestamp when the List was created.
The created_at converted to datetime object.
Information about the default banner of the List.
Information about the banner of the List. If custom banner is not set, it defaults to the default banner.
The description of the List.
Indicates if the authenticated user is following the List.
Indicates if the authenticated user is a member of the List.
The number of members in the List.
The mode of the List, either ‘Private’ or ‘Public’.
Indicates if the authenticated user is muting the List.
Indicates if the List is pinned.
The number of subscribers to the List.
Methods
edit_banner()
Edit the banner image of the list.
The ID of the media to use as the new banner image.
httpx.Response
media_id = await client.upload_media('banner.png')
await list.edit_banner(media_id)
delete_banner()
Deletes the list banner.
Returns: httpx.Response
await list.delete_banner()
edit()
Edits list information.
The new name for the list.
The new description for the list.
is_private
bool | None
default:"None"
Indicates whether the list should be private (True) or public (False).
List - The updated Twitter list.
updated_list = await list.edit(
name='New List Name',
description='Updated description',
is_private=True
)
add_member()
Adds a member to the list.
The ID of the user to add to the list.
httpx.Response
user = await client.get_user_by_screen_name('example_user')
await list.add_member(user.id)
remove_member()
Removes a member from the list.
The ID of the user to remove from the list.
httpx.Response
user = await client.get_user_by_screen_name('example_user')
await list.remove_member(user.id)
The number of tweets to retrieve.
The cursor for pagination.
Result[Tweet] - A Result object containing the retrieved tweets.
tweets = await list.get_tweets(count=50)
for tweet in tweets:
print(tweet)
# <Tweet id="...">
# <Tweet id="...">
more_tweets = await tweets.next() # Retrieve more tweets
for tweet in more_tweets:
print(tweet)
# <Tweet id="...">
# <Tweet id="...">
get_members()
Retrieves members of the list.
Number of members to retrieve.
The cursor for pagination.
Result[User] - Members of the list.
members = await list.get_members(count=50)
for member in members:
print(member)
# <User id="...">
# <User id="...">
more_members = await members.next() # Retrieve more members
get_subscribers()
Retrieves subscribers of the list.
Number of subscribers to retrieve.
The cursor for pagination.
Result[User] - Subscribers of the list.
subscribers = await list.get_subscribers(count=50)
for subscriber in subscribers:
print(subscriber)
# <User id="...">
# <User id="...">
more_subscribers = await subscribers.next() # Retrieve more subscribers
update()
Updates the list object with fresh data from the API.
Examples
Create and Manage a List
# Create a new list
list = await client.create_list(
name='Tech News',
description='Accounts that share tech news',
is_private=False
)
print(f"Created list: {list.name}")
print(f"List ID: {list.id}")
print(f"Description: {list.description}")
Add Members to a List
# Get a list
list = await client.get_list('1234567890')
# Add multiple users to the list
usernames = ['techcrunch', 'verge', 'wired', 'arstechnica']
for username in usernames:
user = await client.get_user_by_screen_name(username)
await list.add_member(user.id)
print(f"Added @{username} to the list")
print(f"List now has {list.member_count} members")
# Get a list and retrieve its tweets
list = await client.get_list('1234567890')
print(f"Tweets from '{list.name}':")
print("-" * 50)
tweets = await list.get_tweets(count=20)
for tweet in tweets:
print(f"@{tweet.user.screen_name}: {tweet.text}")
print(f" ❤️ {tweet.favorite_count} | 🔁 {tweet.retweet_count}")
print()
Manage List Settings
# Get a list
list = await client.get_list('1234567890')
# Update list information
updated_list = await list.edit(
name='Tech News & Updates',
description='Latest tech news and product updates',
is_private=False
)
print(f"Updated list name: {updated_list.name}")
print(f"Updated description: {updated_list.description}")
# Upload and set a custom banner
media_id = await client.upload_media('list_banner.jpg')
await updated_list.edit_banner(media_id)
View List Members and Subscribers
# Get a list
list = await client.get_list('1234567890')
print(f"List: {list.name}")
print(f"Members: {list.member_count}")
print(f"Subscribers: {list.subscriber_count}")
print("-" * 50)
# Get all members
members = await list.get_members(count=100)
print("\nMembers:")
for member in members:
print(f" @{member.screen_name} - {member.name}")
print(f" Followers: {member.followers_count:,}")
# Get all subscribers
subscribers = await list.get_subscribers(count=100)
print("\nSubscribers:")
for subscriber in subscribers:
print(f" @{subscriber.screen_name} - {subscriber.name}")
Remove Members from a List
# Get a list and its members
list = await client.get_list('1234567890')
members = await list.get_members()
# Remove inactive members (example criteria)
for member in members:
# Remove if they haven't tweeted in a while or other criteria
if member.statuses_count < 10:
await list.remove_member(member.id)
print(f"Removed @{member.screen_name} from the list")
Monitor List Activity
import asyncio
# Monitor a list for new tweets
list = await client.get_list('1234567890')
print(f"Monitoring list: {list.name}")
print("Press Ctrl+C to stop\n")
seen_tweet_ids = set()
while True:
tweets = await list.get_tweets(count=10)
for tweet in tweets:
if tweet.id not in seen_tweet_ids:
seen_tweet_ids.add(tweet.id)
print(f"New tweet from @{tweet.user.screen_name}:")
print(f" {tweet.text}")
print()
# Wait before checking again
await asyncio.sleep(60) # Check every minute
Lists are a powerful way to organize and monitor specific groups of users. You can create up to 1,000 lists, and each list can have up to 5,000 members.
