Skip to main content
The UsersClient provides methods for interacting with user-related endpoints of the X API. Access it via client.users.

​
get_me

Retrieves details of the authenticated user. 
response = client.users.get_me(
    user_fields=["created_at", "description", "profile_image_url"],
    expansions=["pinned_tweet_id"],
    tweet_fields=["created_at", "text"]
)

​
Parameters

​
user_fields
List[str]
A comma separated list of User fields to display. Available fields include:
  • created_at
  • description
  • entities
  • id
  • location
  • name
  • pinned_tweet_id
  • profile_image_url
  • protected
  • public_metrics
  • url
  • username
  • verified
  • verified_type
​
expansions
List[str]
A comma separated list of fields to expand. Available expansions include:
  • pinned_tweet_id
​
tweet_fields
List[str]
A comma separated list of Tweet fields to display when expanding pinned tweets.

​
Response

​
data
User
The authenticated User object containing user details.
​
errors
List
Any errors encountered during the request.
​
includes
Expansions
Expanded data such as pinned tweets.

​
get_by_id

Retrieves details of a specific User by their ID. 
response = client.users.get_by_id(
    id="12345678",
    user_fields=["created_at", "description", "public_metrics"]
)

​
Parameters

​
id
str
required
The ID of the User to lookup.
​
user_fields
List[str]
A comma separated list of User fields to display.
​
expansions
List[str]
A comma separated list of fields to expand.
​
tweet_fields
List[str]
A comma separated list of Tweet fields to display.

​
Response

​
data
User
The User object matching the specified ID.
​
errors
List
Any errors encountered during the request.
​
includes
Expansions
Expanded data if requested.

​
get_by_username

Retrieves details of a specific User by their username. 
response = client.users.get_by_username(
    username="xdevelopers",
    user_fields=["created_at", "description", "public_metrics"]
)

​
Parameters

​
username
str
required
The username of the User to lookup (without the @ symbol).
​
user_fields
List[str]
A comma separated list of User fields to display.
​
expansions
List[str]
A comma separated list of fields to expand.
​
tweet_fields
List[str]
A comma separated list of Tweet fields to display.

​
Response

​
data
User
The User object matching the specified username.
​
errors
List
Any errors encountered during the request.
​
includes
Expansions
Expanded data if requested.
Retrieves a list of Users matching a search query. This method automatically paginates through all results. 
# Iterate through all results
for page in client.users.search(
    query="developer",
    max_results=10,
    user_fields=["created_at", "description", "public_metrics"]
):
    for user in page.data:
        print(user)

# Get just the first page
pages = client.users.search(query="developer", max_results=10)
first_page = next(pages)

​
Parameters

​
query
str
required
The query string by which to search for users.
​
max_results
int
The maximum number of results per page (1-100). Defaults to 10.
​
next_token
str
This parameter is used to get the next ‘page’ of results. The value is pulled directly from the response.
​
user_fields
List[str]
A comma separated list of User fields to display.
​
expansions
List[str]
A comma separated list of fields to expand.
​
tweet_fields
List[str]
A comma separated list of Tweet fields to display.

​
Response

Returns an iterator that yields SearchResponse objects for each page.
​
data
List[User]
A list of User objects matching the search query.
​
meta
object
Metadata about the response including pagination tokens.
​
errors
List
Any errors encountered during the request.

​
follow_user

Causes the authenticated user to follow a specific user by their ID. 
from xdk.users.models import FollowUserRequest

response = client.users.follow_user(
    id="12345678",  # Your authenticated user ID
    body=FollowUserRequest(target_user_id="87654321")
)

​
Parameters

​
id
str
required
The ID of the authenticated source User that is requesting to follow the target User.
​
body
FollowUserRequest
Request body containing the target user ID.

​
Response

​
data
object
Response data indicating the follow status.
​
errors
List
Any errors encountered during the request.

​
get_followers

Retrieves a list of Users who follow a specific User by their ID. This method automatically paginates through all results. 
# Iterate through all followers
for page in client.users.get_followers(
    id="12345678",
    max_results=100,
    user_fields=["created_at", "description", "public_metrics"]
):
    for follower in page.data:
        print(follower)

# Get just the first page
pages = client.users.get_followers(id="12345678", max_results=100)
first_page = next(pages)

​
Parameters

​
id
str
required
The ID of the User to lookup followers for.
​
max_results
int
The maximum number of results per page (1-1000). Defaults to 100.
​
pagination_token
str
This parameter is used to get a specified ‘page’ of results.
​
user_fields
List[str]
A comma separated list of User fields to display.
​
expansions
List[str]
A comma separated list of fields to expand.
​
tweet_fields
List[str]
A comma separated list of Tweet fields to display.

​
Response

Returns an iterator that yields GetFollowersResponse objects for each page.
​
data
List[User]
A list of User objects representing followers.
​
meta
object
Metadata about the response including pagination tokens.
​
errors
List
Any errors encountered during the request.
​
includes
Expansions
Expanded data if requested.

​
get_following

Retrieves a list of Users followed by a specific User by their ID. This method automatically paginates through all results. 
# Iterate through all users being followed
for page in client.users.get_following(
    id="12345678",
    max_results=100,
    user_fields=["created_at", "description", "public_metrics"]
):
    for user in page.data:
        print(user)

# Get just the first page
pages = client.users.get_following(id="12345678", max_results=100)
first_page = next(pages)

​
Parameters

​
id
str
required
The ID of the User to lookup following for.
​
max_results
int
The maximum number of results per page (1-1000). Defaults to 100.
​
pagination_token
str
This parameter is used to get a specified ‘page’ of results.
​
user_fields
List[str]
A comma separated list of User fields to display.
​
expansions
List[str]
A comma separated list of fields to expand.
​
tweet_fields
List[str]
A comma separated list of Tweet fields to display.

​
Response

Returns an iterator that yields GetFollowingResponse objects for each page.
​
data
List[User]
A list of User objects being followed.
​
meta
object
Metadata about the response including pagination tokens.
​
errors
List
Any errors encountered during the request.
​
includes
Expansions
Expanded data if requested.

​
Authentication

All methods in the UsersClient require authentication. The authentication method used depends on the endpoint:
  • OAuth 2.0 User Context: Required for get_me, follow_user, and search
  • OAuth 1.0a User Context: Supported as an alternative for most endpoints
  • App-only (Bearer Token): Supported for read-only endpoints like get_by_id, get_by_username, get_followers, and get_following
See the Authentication guide for setup instructions.

Build docs developers (and LLMs) love

Get started for freeTalk to us