Skip to main content

​
Overview

Communities are spaces on Twitter/X where people with shared interests can connect. The Community class provides methods for joining, managing, and retrieving content from communities.

​
Community Class

​
Attributes

​
id
str
The ID of the community.
​
name
str
The name of the community.
​
member_count
int
The count of members in the community.
​
is_nsfw
bool
Indicates if the community is NSFW (Not Safe For Work).
​
members_facepile_results
list[str]
The profile image URLs of members (used for displaying member avatars).
​
banner
dict
The banner information of the community.
​
is_member
bool
Indicates if the authenticated user is a member of the community.
​
role
str
The role of the authenticated user in the community.
​
description
str
The description of the community.
​
creator
User | CommunityCreator
The creator of the community.
​
admin
User
The admin of the community.
​
join_policy
str
The join policy of the community (e.g., ‘Open’, ‘Approval required’).
​
created_at
int
The timestamp of the community’s creation.
​
invites_policy
str
The invites policy of the community.
​
is_pinned
bool
Indicates if the community is pinned.
​
rules
list[CommunityRule]
The rules of the community.

​
Methods

​
get_tweets()

Retrieves tweets from the community.
​
tweet_type
'Top' | 'Latest' | 'Media'
required
The type of tweets to retrieve.
​
count
int
default:"40"
The number of tweets to retrieve.
​
cursor
str | None
default:"None"
The cursor for pagination.
Returns: Result[Tweet] - List of retrieved tweets. 
tweets = await community.get_tweets('Latest', count=50)
for tweet in tweets:
    print(tweet)
# <Tweet id="...">
# <Tweet id="...">

more_tweets = await tweets.next()  # Retrieve more tweets

​
join()

Join the community. Returns: Community - Updated community object. 
await community.join()

​
leave()

Leave the community. Returns: Community - Updated community object. 
await community.leave()

​
request_to_join()

Request to join the community (for communities requiring approval).
​
answer
str | None
default:"None"
Answer to any membership questions.
Returns: Community - Updated community object. 
await community.request_to_join(answer='I love this topic!')

​
get_members()

Retrieves members of the community.
​
count
int
default:"20"
The number of members to retrieve.
​
cursor
str | None
default:"None"
The cursor for pagination.
Returns: Result[CommunityMember] - List of retrieved members. 
members = await community.get_members(count=50)
for member in members:
    print(f"@{member.screen_name} - {member.community_role}")

​
get_moderators()

Retrieves moderators of the community.
​
count
int
default:"20"
The number of moderators to retrieve.
​
cursor
str | None
default:"None"
The cursor for pagination.
Returns: Result[CommunityMember] - List of retrieved moderators. 
moderators = await community.get_moderators()
for mod in moderators:
    print(f"@{mod.screen_name} - {mod.community_role}")

​
search_tweet()

Searches tweets in the community.
​
query
str
required
The search query.
​
count
int
default:"20"
The number of tweets to retrieve.
​
cursor
str | None
default:"None"
The cursor for pagination.
Returns: Result[Tweet] - List of retrieved tweets. 
results = await community.search_tweet('python tutorial', count=20)
for tweet in results:
    print(tweet.text)

​
update()

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

​
CommunityMember Class

Represents a member of a community.

​
Attributes

​
id
str
The unique identifier of the member.
​
community_role
str
The member’s role in the community.
​
super_following
bool
Indicates if super following is enabled.
​
super_follow_eligible
bool
Indicates if the member is eligible for super follow.
​
super_followed_by
bool
Indicates if super followed by the authenticated user.
​
smart_blocking
bool
Indicates if smart blocking is enabled.
​
is_blue_verified
bool
Indicates if the member is blue verified.
​
screen_name
str
The member’s screen name.
​
name
str
The member’s display name.
​
follow_request_sent
bool
Indicates if a follow request has been sent.
​
protected
bool
Indicates if the member’s tweets are protected.
​
following
bool
Indicates if the authenticated user is following this member.
​
followed_by
bool
Indicates if this member follows the authenticated user.
​
blocking
bool
Indicates if the authenticated user is blocking this member.
​
profile_image_url_https
str
The URL of the member’s profile image.
​
verified
bool
Indicates if the member is verified.

​
CommunityCreator Class

A named tuple representing basic information about a community creator.

​
Attributes

​
id
str
The ID of the creator.
​
screen_name
str
The screen name of the creator.
​
verified
bool
Indicates if the creator is verified.

​
CommunityRule Class

A named tuple representing a community rule.

​
Attributes

​
id
str
The ID of the rule.
​
name
str
The name/text of the rule.

​
Examples

​
Browse and Join a Community

# Search for a community
communities = await client.search_community('Python')

if communities:
    community = communities[0]
    print(f"Community: {community.name}")
    print(f"Members: {community.member_count:,}")
    print(f"Description: {community.description}")
    
    # Join the community
    if not community.is_member:
        await community.join()
        print("Successfully joined the community!")

​
Get Community Tweets

# Get a community
community = await client.get_community('1234567890')

print(f"Latest tweets from {community.name}:")
print("-" * 50)

# Get latest tweets
tweets = await community.get_tweets('Latest', count=20)
for tweet in tweets:
    print(f"@{tweet.user.screen_name}: {tweet.text}")
    print(f"  ❤️ {tweet.favorite_count} | 🔁 {tweet.retweet_count}")
    print()

​
View Community Information

# Get a community
community = await client.get_community('1234567890')

print(f"Community: {community.name}")
print(f"Description: {community.description}")
print(f"Members: {community.member_count:,}")
print(f"Created: {community.created_at}")
print(f"Is member: {community.is_member}")
print(f"Join policy: {community.join_policy}")
print(f"NSFW: {community.is_nsfw}")

# Show rules
if community.rules:
    print("\nCommunity Rules:")
    for rule in community.rules:
        print(f"  {rule.name}")

# Show creator
if community.creator:
    if hasattr(community.creator, 'screen_name'):
        print(f"\nCreated by: @{community.creator.screen_name}")

​
Get Community Members

# Get a community and its members
community = await client.get_community('1234567890')

print(f"Members of {community.name}:")
print("-" * 50)

members = await community.get_members(count=50)
for member in members:
    role_badge = "🛡️" if member.community_role == "admin" else ""
    verified_badge = "✓" if member.verified or member.is_blue_verified else ""
    
    print(f"{role_badge} @{member.screen_name} {verified_badge} - {member.name}")
    print(f"  Role: {member.community_role}")
    if member.following:
        print("  Following")
    print()

​
Get Community Moderators

# Get community moderators
community = await client.get_community('1234567890')

print(f"Moderators of {community.name}:")
print("-" * 50)

moderators = await community.get_moderators()
for mod in moderators:
    print(f"@{mod.screen_name} - {mod.name}")
    print(f"  Role: {mod.community_role}")
    print()

​
Search Within a Community

# Search for tweets within a community
community = await client.get_community('1234567890')

search_query = 'tutorial'
results = await community.search_tweet(search_query, count=30)

print(f"Search results for '{search_query}' in {community.name}:")
print("-" * 50)

for tweet in results:
    print(f"@{tweet.user.screen_name}: {tweet.text}")
    print(f"  {tweet.created_at}")
    print()

​
Monitor Community Activity

import asyncio

# Monitor a community for new tweets
community = await client.get_community('1234567890')

print(f"Monitoring {community.name} for new tweets...")
print("Press Ctrl+C to stop\n")

seen_tweet_ids = set()

while True:
    tweets = await community.get_tweets('Latest', 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()
    
    await asyncio.sleep(60)  # Check every minute
Communities are a great way to engage with focused groups of users who share common interests. Some communities may require approval to join, while others are open to all users.

Build docs developers (and LLMs) love

Get started for freeTalk to us