Skip to content

xapi

xapi dm

Manage X direct messages.

xapi dm conversations

List your DM conversations.

Environment Variables

NameTypeRequiredDefaultDescription
X_BEARER_TOKENstringno
X_ACCESS_TOKENstringno

Options

FlagTypeDefaultDescription
--maxResultsnumber20Maximum conversations to return

Output

FieldTypeRequiredDescription
conversationsarrayyes
conversations[].dm_conversation_idstringyes
conversations[].participant_idsarrayyes
countnumberyes

Examples

sh
# List your DM conversations
xapi dm conversations

xapi dm send

Send a direct message to a user.

Arguments

NameTypeRequiredDescription
participantIdstringyesUser ID to send message to

Environment Variables

NameTypeRequiredDefaultDescription
X_ACCESS_TOKENstringyesX OAuth 2.0 user access token (required for write endpoints)
X_BEARER_TOKENstringno

Options

FlagTypeDefaultDescription
--textstringMessage text

Output

FieldTypeRequiredDescription
dm_conversation_idstringyes
dm_event_idstringyes

Examples

sh
# Send a DM to a user
xapi dm send 12345 --text Hey there!

xapi lists

Manage and browse X lists.

xapi lists add-member

Add a member to an X list.

Arguments

NameTypeRequiredDescription
idstringyesList ID
memberstringyesMember to target (username with or without @, or user ID)

Environment Variables

NameTypeRequiredDefaultDescription
X_ACCESS_TOKENstringyesX OAuth 2.0 user access token (required for write endpoints)
X_BEARER_TOKENstringno

Output

FieldTypeRequiredDescription
idstringyes
member_idstringyes
member_usernamestringno
is_memberbooleanyes

Examples

sh
# Add @jack to a list
xapi lists add-member 1234567890 jack

xapi lists create

Create a new list.

Environment Variables

NameTypeRequiredDefaultDescription
X_ACCESS_TOKENstringyesX OAuth 2.0 user access token (required for write endpoints)
X_BEARER_TOKENstringno

Options

FlagTypeDefaultDescription
--namestringList name (1-25 characters)
--descriptionstringOptional list description (1-100 characters)
--privatebooleanfalseCreate as a private list

Output

FieldTypeRequiredDescription
idstringyes
namestringyes

Examples

sh
# Create a private list
xapi lists create --name Core devs --description Builders only --private true

xapi lists delete

Delete a list by ID.

Arguments

NameTypeRequiredDescription
idstringyesList ID to delete

Environment Variables

NameTypeRequiredDefaultDescription
X_ACCESS_TOKENstringyesX OAuth 2.0 user access token (required for write endpoints)
X_BEARER_TOKENstringno

Output

FieldTypeRequiredDescription
deletedbooleanyes
idstringyes

Examples

sh
# Delete a list
xapi lists delete 1234567890

xapi lists get

Get a list by ID.

Arguments

NameTypeRequiredDescription
idstringyesList ID

Environment Variables

NameTypeRequiredDefaultDescription
X_BEARER_TOKENstringno
X_ACCESS_TOKENstringno

Output

FieldTypeRequiredDescription
idstringyes
namestringyes
descriptionstringno
owner_idstringno
member_countnumberno

Examples

sh
# Get list details
xapi lists get 1234567890

xapi lists members

List members of an X list.

Arguments

NameTypeRequiredDescription
idstringyesList ID

Environment Variables

NameTypeRequiredDefaultDescription
X_BEARER_TOKENstringno
X_ACCESS_TOKENstringno

Options

FlagTypeDefaultDescription
--maxResultsnumber100Maximum members to return

Output

FieldTypeRequiredDescription
usersarrayyes
users[].idstringyes
users[].namestringyes
users[].usernamestringyes
users[].followersnumberno
countnumberyes

Examples

sh
# List all members
xapi lists members 1234567890

xapi lists posts

Get posts from an X list.

Arguments

NameTypeRequiredDescription
idstringyesList ID

Environment Variables

NameTypeRequiredDefaultDescription
X_BEARER_TOKENstringno
X_ACCESS_TOKENstringno

Options

FlagTypeDefaultDescription
--maxResultsnumber25Maximum posts to return
--verbosebooleanShow full text

Output

FieldTypeRequiredDescription
postsarrayyes
posts[].idstringyes
posts[].textstringyes
posts[].author_idstringno
posts[].created_atstringno
posts[].likesnumberno
countnumberyes

Examples

sh
# Get posts from a list
xapi lists posts 1234567890

xapi lists remove-member

Remove a member from an X list.

Arguments

NameTypeRequiredDescription
idstringyesList ID
memberstringyesMember to target (username with or without @, or user ID)

Environment Variables

NameTypeRequiredDefaultDescription
X_ACCESS_TOKENstringyesX OAuth 2.0 user access token (required for write endpoints)
X_BEARER_TOKENstringno

Output

FieldTypeRequiredDescription
idstringyes
member_idstringyes
member_usernamestringno
is_memberbooleanyes

Examples

sh
# Remove @jack from a list
xapi lists remove-member 1234567890 jack

xapi posts

Manage and search X posts.

xapi posts bookmark

Bookmark a post by ID.

Arguments

NameTypeRequiredDescription
idstringyesPost ID to bookmark

Environment Variables

NameTypeRequiredDefaultDescription
X_ACCESS_TOKENstringyesX OAuth 2.0 user access token (required for write endpoints)
X_BEARER_TOKENstringno

Output

FieldTypeRequiredDescription
bookmarkedbooleanyes
idstringyes

Examples

sh
# Bookmark a post
xapi posts bookmark 1234567890

xapi posts create

Create a new post.

Environment Variables

NameTypeRequiredDefaultDescription
X_ACCESS_TOKENstringyesX OAuth 2.0 user access token (required for write endpoints)
X_BEARER_TOKENstringno

Options

FlagTypeDefaultDescription
--textstringPost text
--replyTostringReply to post ID
--quotestringQuote post ID

Output

FieldTypeRequiredDescription
idstringyes
textstringyes

Examples

sh
# Post a simple message
xapi posts create --text Hello world!

# Reply to a post
xapi posts create --text Great point! --replyTo 1234567890

xapi posts delete

Delete a post by ID.

Arguments

NameTypeRequiredDescription
idstringyesPost ID to delete

Environment Variables

NameTypeRequiredDefaultDescription
X_ACCESS_TOKENstringyesX OAuth 2.0 user access token (required for write endpoints)
X_BEARER_TOKENstringno

Output

FieldTypeRequiredDescription
deletedbooleanyes
idstringyes

Examples

sh
# Delete a post
xapi posts delete 1234567890

xapi posts get

Get a post by ID.

Arguments

NameTypeRequiredDescription
idstringyesPost ID

Environment Variables

NameTypeRequiredDefaultDescription
X_BEARER_TOKENstringno
X_ACCESS_TOKENstringno

Options

FlagTypeDefaultDescription
--verbosebooleanShow full text without truncation

Output

FieldTypeRequiredDescription
idstringyes
textstringyes
author_idstringno
created_atstringno
likesnumberno
retweetsnumberno
repliesnumberno

Examples

sh
# Get a post by ID
xapi posts get 1234567890

xapi posts like

Like a post by ID.

Arguments

NameTypeRequiredDescription
idstringyesPost ID to like

Environment Variables

NameTypeRequiredDefaultDescription
X_ACCESS_TOKENstringyesX OAuth 2.0 user access token (required for write endpoints)
X_BEARER_TOKENstringno

Output

FieldTypeRequiredDescription
likedbooleanyes
idstringyes

Examples

sh
# Like a post
xapi posts like 1234567890

xapi posts likes

List users who liked a post.

Arguments

NameTypeRequiredDescription
idstringyesPost ID

Environment Variables

NameTypeRequiredDefaultDescription
X_BEARER_TOKENstringno
X_ACCESS_TOKENstringno

Options

FlagTypeDefaultDescription
--maxResultsnumber100Maximum users to return

Output

FieldTypeRequiredDescription
usersarrayyes
users[].idstringyes
users[].namestringyes
users[].usernamestringyes
users[].followersnumberno
countnumberyes

Examples

sh
# See who liked a post
xapi posts likes 1234567890

xapi posts retweet

Retweet a post by ID.

Arguments

NameTypeRequiredDescription
idstringyesPost ID to retweet

Environment Variables

NameTypeRequiredDefaultDescription
X_ACCESS_TOKENstringyesX OAuth 2.0 user access token (required for write endpoints)
X_BEARER_TOKENstringno

Output

FieldTypeRequiredDescription
retweetedbooleanyes
idstringyes

Examples

sh
# Retweet a post
xapi posts retweet 1234567890

xapi posts retweets

List users who retweeted a post.

Arguments

NameTypeRequiredDescription
idstringyesPost ID

Environment Variables

NameTypeRequiredDefaultDescription
X_BEARER_TOKENstringno
X_ACCESS_TOKENstringno

Options

FlagTypeDefaultDescription
--maxResultsnumber100Maximum users to return

Output

FieldTypeRequiredDescription
usersarrayyes
users[].idstringyes
users[].namestringyes
users[].usernamestringyes
users[].followersnumberno
countnumberyes

Examples

sh
# See who retweeted a post
xapi posts retweets 1234567890

Search recent posts.

Arguments

NameTypeRequiredDescription
querystringyesSearch query

Environment Variables

NameTypeRequiredDefaultDescription
X_BEARER_TOKENstringno
X_ACCESS_TOKENstringno

Options

FlagTypeDefaultDescription
--maxResultsnumber10Maximum results to return (10–100)
--sortstringrecencySort order
--verbosebooleanShow full text without truncation

Output

FieldTypeRequiredDescription
postsarrayyes
posts[].idstringyes
posts[].textstringyes
posts[].created_atstringno
posts[].likesnumberno
posts[].retweetsnumberno
countnumberyes

Examples

sh
# Search for TypeScript posts
xapi posts search TypeScript

# Search by relevance
xapi posts search AI --sort relevancy --maxResults 20

xapi posts unbookmark

Remove bookmark from a post by ID.

Arguments

NameTypeRequiredDescription
idstringyesPost ID to unbookmark

Environment Variables

NameTypeRequiredDefaultDescription
X_ACCESS_TOKENstringyesX OAuth 2.0 user access token (required for write endpoints)
X_BEARER_TOKENstringno

Output

FieldTypeRequiredDescription
bookmarkedbooleanyes
idstringyes

Examples

sh
# Remove a bookmark from a post
xapi posts unbookmark 1234567890

xapi posts unlike

Unlike a post by ID.

Arguments

NameTypeRequiredDescription
idstringyesPost ID to unlike

Environment Variables

NameTypeRequiredDefaultDescription
X_ACCESS_TOKENstringyesX OAuth 2.0 user access token (required for write endpoints)
X_BEARER_TOKENstringno

Output

FieldTypeRequiredDescription
likedbooleanyes
idstringyes

Examples

sh
# Unlike a post
xapi posts unlike 1234567890

xapi timeline

View your X timeline.

xapi timeline home

View your home timeline.

Environment Variables

NameTypeRequiredDefaultDescription
X_BEARER_TOKENstringno
X_ACCESS_TOKENstringno

Options

FlagTypeDefaultDescription
--maxResultsnumber25Maximum posts to return (5–100)
--sinceIdstringOnly return posts newer than this post ID
--verbosebooleanShow full text without truncation

Output

FieldTypeRequiredDescription
postsarrayyes
posts[].idstringyes
posts[].textstringyes
posts[].author_idstringno
posts[].created_atstringno
posts[].likesnumberno
posts[].retweetsnumberno
countnumberyes

Examples

sh
# View your home timeline
xapi timeline home

# View 50 posts
xapi timeline home --maxResults 50

# Resume from last-seen post ID
xapi timeline home --sinceId 1900123456789012345

xapi timeline mentions

View your recent mentions.

Environment Variables

NameTypeRequiredDefaultDescription
X_BEARER_TOKENstringno
X_ACCESS_TOKENstringno

Options

FlagTypeDefaultDescription
--maxResultsnumber25Maximum mentions to return
--sinceIdstringOnly return mentions newer than this post ID
--verbosebooleanShow full text without truncation

Output

FieldTypeRequiredDescription
postsarrayyes
posts[].idstringyes
posts[].textstringyes
posts[].author_idstringno
posts[].created_atstringno
countnumberyes

Examples

sh
# View your recent mentions
xapi timeline mentions

# Resume mentions from last-seen post ID
xapi timeline mentions --sinceId 1900123456789012345

Explore trending topics on X.

Get trending topics for a specific location (WOEID).

Arguments

NameTypeRequiredDescription
woeidstringyesWhere On Earth ID (from trends places)

Environment Variables

NameTypeRequiredDefaultDescription
X_BEARER_TOKENstringno
X_ACCESS_TOKENstringno

Output

FieldTypeRequiredDescription
trendsarrayyes
trends[].namestringyes
trends[].querystringyes
trends[].tweet_volumenumberno
countnumberyes

Examples

sh
# Get worldwide trends
xapi trends location 1

# Get trends for New York
xapi trends location 2459115

List places where trending topics are available.

Environment Variables

NameTypeRequiredDefaultDescription
X_BEARER_TOKENstringno
X_ACCESS_TOKENstringno

Output

FieldTypeRequiredDescription
placesarrayyes
places[].woeidnumberyes
places[].namestringyes
places[].countrystringyes
countnumberyes

Examples

sh
# List all trending places
xapi trends places

xapi users

Look up X users.

xapi users block

Block a user by username or ID.

Arguments

NameTypeRequiredDescription
usernamestringyesUsername (with or without @) or user ID

Environment Variables

NameTypeRequiredDefaultDescription
X_ACCESS_TOKENstringyesX OAuth 2.0 user access token (required for write endpoints)
X_BEARER_TOKENstringno

Output

FieldTypeRequiredDescription
idstringyes
usernamestringyes
blockingbooleanyes

Examples

sh
# Block @jack
xapi users block jack

xapi users follow

Follow a user by username or ID.

Arguments

NameTypeRequiredDescription
usernamestringyesUsername (with or without @) or user ID

Environment Variables

NameTypeRequiredDefaultDescription
X_ACCESS_TOKENstringyesX OAuth 2.0 user access token (required for write endpoints)
X_BEARER_TOKENstringno

Output

FieldTypeRequiredDescription
idstringyes
usernamestringyes
followingbooleanyes
pending_followbooleanno

Examples

sh
# Follow @jack
xapi users follow jack

xapi users followers

List followers of a user. Supports optional client-side baseline diffing for new follower detection.

Arguments

NameTypeRequiredDescription
usernamestringyesUsername or user ID

Environment Variables

NameTypeRequiredDefaultDescription
X_BEARER_TOKENstringno
X_ACCESS_TOKENstringno

Options

FlagTypeDefaultDescription
--maxResultsnumber100Maximum followers to return
--seenIdsFilestringPath to newline-delimited follower IDs used as a baseline for client-side diffing
--newOnlybooleanfalseReturn only followers not found in --seen-ids-file (client-side baseline diff; not API-native since_id)

Output

FieldTypeRequiredDescription
usersarrayyes
users[].idstringyes
users[].namestringyes
users[].usernamestringyes
users[].followersnumberno
countnumberyes

Examples

sh
# List followers of jack
xapi users followers jack

# Show only followers not in your baseline file (client-side diffing; the X API does not support since_id here)
xapi users followers jack --seenIdsFile ./seen-followers.txt --newOnly true

xapi users following

List accounts a user is following.

Arguments

NameTypeRequiredDescription
usernamestringyesUsername or user ID

Environment Variables

NameTypeRequiredDefaultDescription
X_BEARER_TOKENstringno
X_ACCESS_TOKENstringno

Options

FlagTypeDefaultDescription
--maxResultsnumber100Maximum accounts to return

Output

FieldTypeRequiredDescription
usersarrayyes
users[].idstringyes
users[].namestringyes
users[].usernamestringyes
users[].followersnumberno
countnumberyes

Examples

sh
# List accounts jack follows
xapi users following jack

xapi users get

Get a user by username or ID.

Arguments

NameTypeRequiredDescription
usernamestringyesUsername (with or without @) or user ID

Environment Variables

NameTypeRequiredDefaultDescription
X_BEARER_TOKENstringno
X_ACCESS_TOKENstringno

Options

FlagTypeDefaultDescription
--verbosebooleanShow full bio without truncation

Output

FieldTypeRequiredDescription
idstringyes
namestringyes
usernamestringyes
descriptionstringno
followersnumberno
followingnumberno
tweetsnumberno
joinedstringno

Examples

sh
# Get a user by username
xapi users get jack

# Get a user by ID
xapi users get 12345

xapi users me

Get the authenticated user profile and metrics.

Environment Variables

NameTypeRequiredDefaultDescription
X_BEARER_TOKENstringno
X_ACCESS_TOKENstringno

Options

FlagTypeDefaultDescription
--verbosebooleanShow full bio without truncation

Output

FieldTypeRequiredDescription
idstringyes
namestringyes
usernamestringyes
descriptionstringno
followersnumberno
followingnumberno
tweetsnumberno
joinedstringno

Examples

sh
# Get your authenticated profile
xapi users me

xapi users mentions

List recent mentions of a user.

Arguments

NameTypeRequiredDescription
usernamestringyesUsername or user ID

Environment Variables

NameTypeRequiredDefaultDescription
X_BEARER_TOKENstringno
X_ACCESS_TOKENstringno

Options

FlagTypeDefaultDescription
--maxResultsnumber10Maximum mentions to return
--verbosebooleanShow full text

Output

FieldTypeRequiredDescription
postsarrayyes
posts[].idstringyes
posts[].textstringyes
posts[].created_atstringno
countnumberyes

Examples

sh
# Get mentions of jack
xapi users mentions jack

xapi users mute

Mute a user by username or ID.

Arguments

NameTypeRequiredDescription
usernamestringyesUsername (with or without @) or user ID

Environment Variables

NameTypeRequiredDefaultDescription
X_ACCESS_TOKENstringyesX OAuth 2.0 user access token (required for write endpoints)
X_BEARER_TOKENstringno

Output

FieldTypeRequiredDescription
idstringyes
usernamestringyes
mutingbooleanyes

Examples

sh
# Mute @jack
xapi users mute jack

xapi users posts

List a user's posts.

Arguments

NameTypeRequiredDescription
usernamestringyesUsername or user ID

Environment Variables

NameTypeRequiredDefaultDescription
X_BEARER_TOKENstringno
X_ACCESS_TOKENstringno

Options

FlagTypeDefaultDescription
--maxResultsnumber10Maximum posts to return
--verbosebooleanShow full text without truncation

Output

FieldTypeRequiredDescription
postsarrayyes
posts[].idstringyes
posts[].textstringyes
posts[].created_atstringno
posts[].likesnumberno
posts[].retweetsnumberno
countnumberyes

Examples

sh
# Get jack's recent posts
xapi users posts jack

Search for users by keyword.

Arguments

NameTypeRequiredDescription
querystringyesSearch query

Environment Variables

NameTypeRequiredDefaultDescription
X_BEARER_TOKENstringno
X_ACCESS_TOKENstringno

Output

FieldTypeRequiredDescription
usersarrayyes
users[].idstringyes
users[].namestringyes
users[].usernamestringyes
users[].followersnumberno
countnumberyes

Examples

sh
# Search for users about TypeScript
xapi users search TypeScript

xapi users unblock

Unblock a user by username or ID.

Arguments

NameTypeRequiredDescription
usernamestringyesUsername (with or without @) or user ID

Environment Variables

NameTypeRequiredDefaultDescription
X_ACCESS_TOKENstringyesX OAuth 2.0 user access token (required for write endpoints)
X_BEARER_TOKENstringno

Output

FieldTypeRequiredDescription
idstringyes
usernamestringyes
blockingbooleanyes

Examples

sh
# Unblock @jack
xapi users unblock jack

xapi users unfollow

Unfollow a user by username or ID.

Arguments

NameTypeRequiredDescription
usernamestringyesUsername (with or without @) or user ID

Environment Variables

NameTypeRequiredDefaultDescription
X_ACCESS_TOKENstringyesX OAuth 2.0 user access token (required for write endpoints)
X_BEARER_TOKENstringno

Output

FieldTypeRequiredDescription
idstringyes
usernamestringyes
followingbooleanyes

Examples

sh
# Unfollow @jack
xapi users unfollow jack

xapi users unmute

Unmute a user by username or ID.

Arguments

NameTypeRequiredDescription
usernamestringyesUsername (with or without @) or user ID

Environment Variables

NameTypeRequiredDefaultDescription
X_ACCESS_TOKENstringyesX OAuth 2.0 user access token (required for write endpoints)
X_BEARER_TOKENstringno

Output

FieldTypeRequiredDescription
idstringyes
usernamestringyes
mutingbooleanyes

Examples

sh
# Unmute @jack
xapi users unmute jack