X

X_AddListMember

Add one or more users to an X List owned by the authenticated user. Provide user_ids, usernames, or both. Adding a user who is already a member is treated as success. On a mid-loop rate-limit, the run short-circuits and remaining targets are marked as not attempted. On retry, drop the targets that already succeeded; otherwise polling re-arms X's bucket and extends the lockout. X is eventually consistent on list membership: a success status here does not mean a subsequent read of the list's members will immediately return the new member. Allow a few seconds before relying on the read endpoint to reflect the mutation. Serialize dependent list mutations: do not add members in parallel with deleting the list, removing its members, or updating it against the same list_id. Concurrent dependent mutations race and surface spurious not_found errors when the member call lands after the list is gone. Await each mutation before issuing the next one on the same list.

X_CreateList

Create a new X List owned by the authenticated user.

X_DeleteList

Delete an X List owned by the authenticated user. The list and its memberships are removed. The tool distinguishes "I just deleted it" from "it was already gone" rather than collapsing both into the same idempotent-success envelope. Serialize dependent list mutations: do not delete a list in parallel with adding or removing its members, updating it, or pinning it. The list-membership endpoints will race against the delete and surface a spurious not_found when the member call lands after the list is gone. Await each mutation before issuing the next one on the same list.

X_DeleteTweetById

Delete one of the authenticated user's tweets. The tool distinguishes "I just deleted it" from "it was already gone" rather than collapsing both into the same idempotent-success envelope.

X_GetConversation

Fetch the conversation thread containing tweet_id. Returns every tweet that shares the same conversation_id as the given tweet, ordered oldest-first so a caller can render the thread top to bottom. The conversation root sits at position 0 whenever accessible. Replies are pulled from the recent-search index (~7-day window) which can lag real time by several minutes. To verify a specific reply, look it up by id instead.

X_GetHomeTimeline

Fetch the authenticated user's reverse-chronological home timeline. Returns recent tweets from accounts the user follows.

X_GetListMembers

List members of an X List. The members endpoint is eventually consistent: after members are added to or removed from a list, the membership read endpoints (this list's members and a user's list memberships) can take several seconds to surface the change. The list-tweets endpoint is typically refreshed faster than the members endpoint, so an empty page immediately after an add is more likely a consistency window than a genuine empty list. Re-query after a brief wait when verifying a just-applied mutation.

X_GetListMembershipsForUser

List the X Lists the target user is a member of. Pass user_id or username (exactly one). With username, the handle is resolved to a numeric id first; passing user_id skips that hop.

X_GetListTweets

List recent tweets from members of an X List, newest first.

X_GetMyMentions

Fetch recent @-mentions of the authenticated user, newest first.

X_GetOwnedLists

List the X Lists a user owns. Omitting both user_id and username defaults to the authenticated user (the common "show me my lists" workflow after creating a list). Each list record carries id, name, private, description, member_count, follower_count, owner_id, and created_at.

X_GetQuoteTweets

Fetch public quote tweets of the given tweet.

X_GetRepliesToTweet

Fetch public DIRECT replies to a given tweet (last ~7 days). Returns only tweets whose referenced_tweets carry a replied_to edge pointing at tweet_id -- not the whole conversation thread. Sibling replies and nested replies further down the tree are filtered out so the result reflects what a reader would see when expanding "replies to this tweet" in the X UI. Use the conversation tool to get the full thread surrounding a tweet instead. The recent-search index can lag real time by several minutes, so a just-posted reply may not appear yet. To verify a reply you just posted, look it up by id instead. Pagination note: each page is fetched as max_results from X's recent-search index, then locally filtered down to direct replies. Pages where every tweet is an indirect reply (sibling or nested) come back with data=[] plus a next_token -- continue paginating to surface the direct replies further into the conversation.

X_GetSpacesByCreator

List the live or scheduled X Spaces created by a set of users. Useful for monitoring whether a set of accounts has any Space currently airing or queued. Ended Spaces are not returned.

X_GetUserLikedTweets

List tweets a user has liked, newest-liked first. Omitting both user_id and username defaults to the authenticated user. Each tweet carries tweet_url, author_username, author_name, and any media or poll enrichment. When the target user's likes are private, the response is an empty page indistinguishable from "no liked tweets."

X_GetUserTweets

Fetch tweets authored by a specific X user, newest first. Paginates through the author's full tweet history (no 7-day window). Results include original tweets, replies (unless exclude_replies=True), retweets (unless exclude_retweets=True), and quote tweets. Author handle, name, and media or poll details are flattened onto each tweet.

X_LikeTweet

Like a tweet as the authenticated user. Idempotent: liking an already-liked tweet succeeds.

X_LookupSpaceById

Look up a single X Space by its id. Returns the Space's lifecycle state, title, creator, host and speaker ids, language, and participant and subscriber counts. X gates several Space metadata fields behind ownership: most non-host callers cannot read a Space's full metadata, even when the Space surfaces in a search or by-creator listing.

X_LookupTweetEngagers

List the users who liked or retweeted a tweet. Each user record carries the standard handle, name, and profile metadata so callers can render an engager row without a follow-up lookup. When the tweet shows non-zero engagement in public_metrics but X's engagers endpoint returns zero users on the first page, the call returns an errors[0].type = "data_unavailable" envelope. This signals that the account's X access tier does not expose engager lists for this tweet; treat public_metrics.like_count / retweet_count from LookupTweetById as the authoritative engagement total in that case.

X_LookupTweets

Look up tweets by id (single or batched) on X. Pass one id or up to 100 ids; the response is always a list. Each entry carries referenced_tweets (type of replied_to, quoted, or retweeted plus the parent id), conversation_id, and the convenience fields tweet_url / author_username / author_name. Set include_author_only_metrics=True to retrieve non_public_metrics (impressions, user_profile_clicks, url_link_clicks) and organic_metrics for tweets the authenticated caller authored. X drops third-party tweets from data when those fields are requested, so leave the flag false unless every id in the batch is known to be authored by the caller.

X_LookupUsers

Look up X (Twitter) users by handle and/or numeric user id. Provide usernames, user_ids, or both. Up to 100 of each per call.

X_PinList

Pin an X List to the authenticated user's profile. Idempotent: pinning an already-pinned list succeeds.

X_PostThread

Post a multi-tweet thread as the authenticated user. Posts the first tweet, then chains every subsequent entry as a reply to the prior tweet's id. tweets must contain 2-25 entries when posting a new thread, or 1-25 entries when resuming an existing thread via parent_tweet_id (the 1-entry case lets a caller append one more reply to the tail of a prior thread). poll_options / poll_duration_minutes / quote_tweet_id / reply_settings apply to the head tweet only. Pre-flight validation runs on every entry before any post is created. If any entry fails validation, the call posts nothing. On a mid-thread interruption, posted carries the rows that landed and next_position is the 1-based index of the first non-posted entry (0 when every entry posted). Resume the chain with:: tweets = (tweets[next_position - 1 :],) parent_tweet_id = posted[-1]["tweet_id"] from the prior call Without parent_tweet_id, a resume call would re-create a fresh head tweet and silently split the thread into two disconnected chains. X also rejects mid-thread entries with status='invalid_input' when the text passes local validation but contains codepoints that X counts as multiple weighted characters (emoji, many CJK glyphs) pushing the weighted total above 280, or when the text contains control characters X disallows. Simplify the entry at tweets[next_position - 1] (plain ASCII is the safest reset) and resume.

X_PostTweet

Post a new tweet as the authenticated user. The same tool covers top-level posts, replies, and quote tweets. Supply reply_to_tweet_id to post the new tweet as a reply; supply quote_tweet_id to quote another tweet; supply both to post a reply that also quotes a tweet. Pass reply_settings to restrict who can reply. Pass poll_options plus poll_duration_minutes to attach a poll (polls cannot be combined with quote_tweet_id). For multi-tweet threads, use the post-thread tool.

X_RemoveListMember

Remove one or more users from an X List owned by the authenticated user. Provide user_ids, usernames, or both. Removing a user who is not a member is treated as success. On a mid-loop rate-limit, the run short-circuits and remaining targets are marked as not attempted. On retry, drop the targets that already succeeded; otherwise polling re-arms X's bucket and extends the lockout. X is eventually consistent on list membership: a success status here does not mean a subsequent read of the list's members will immediately stop returning the removed member. Allow a few seconds before relying on the read endpoint to reflect the mutation. Serialize dependent list mutations: do not remove members in parallel with deleting the same list_id (a known race that produces spurious not_found when the remove lands after the delete). Await each mutation before issuing the next one on the same list.

X_Retweet

Retweet a tweet as the authenticated user. Idempotent: retweeting an already-retweeted tweet succeeds.

X_SearchSpaces

Search live and scheduled X Spaces by title. Matches the query against Space titles only (not transcripts). Filter state controls whether to return live, scheduled, or both. This endpoint does not paginate; max_results is the maximum page size.

X_SearchTweetsByKeywords

Search tweets on X by structured filters across X's recent ~7-day index. Searches the last ~7 days of public tweets. For deeper historical windows, X gates the full-archive search endpoint behind a paid plan; this toolkit only offers the recent variant. All supplied filters are ANDed together. At least one positive filter is required: a non-empty keyword or phrase, a non-empty from_username / to_username, or a has_ / is_ flag set to True. lang, exclude_replies, sort_order, start_time / end_time, and False-valued flags are qualifiers, not positive filters. Pagination: X's cursor is inclusive at the boundary, so consecutive pages may overlap by one tweet. De-duplicate by tweet id when merging pages. X's sharded search backend sometimes returns data=[] with a non-null next_token when the slice it scanned produced no hits; auto_follow_empty_pages controls how many such empty pages the tool follows internally before returning, and pages_scanned in the response reports how far it scanned.

X_UndoRetweet

Undo a previous retweet by the authenticated user. Idempotent: undoing a retweet that doesn't exist succeeds.

X_UnlikeTweet

Remove the authenticated user's like from a tweet. The tweet itself is unaffected; only the like relationship is removed. Idempotent: unliking a tweet that isn't liked succeeds.

X_UnpinList

Unpin an X List from the authenticated user's profile. Idempotent: unpinning a list that isn't pinned succeeds.

X_UpdateList

Rename a list, edit its description, or toggle its visibility. At least one of name, description, or private must be provided. Unchanged fields keep their pre-existing values. Serialize dependent list mutations: do not update a list in parallel with deleting it, adding or removing its members, or another update to the same list_id. Concurrent dependent mutations race against X's distributed state and surface spurious not_found errors. Await each mutation before issuing the next one on the same list.

X_WhoAmI

Get the authenticated X (Twitter) user's profile.