Use X through an OAuth connection to manage posts and bookmarks, search content, inspect user relationships, and retrieve trends and account usage. The actions below document the available posting and account controls.
Sim requests these scopes when someone connects a X account. For a self-hosted deployment, register your own app with the provider using the settings below. See Integrations and OAuth for setup.
Setting Value Redirect URI <NEXT_PUBLIC_APP_URL>/api/auth/oauth2/callback/xEnvironment variables X_CLIENT_ID, X_CLIENT_SECRET
Scope Description tweet.readRead tweets and timeline tweet.writePost, repost, and delete tweets tweet.moderate.writeHide and unhide replies to tweets users.readRead user profiles and account information follows.readView followers and following lists follows.writeFollow and unfollow users bookmark.readView bookmarked tweets bookmark.writeAdd and remove bookmarks like.readView liked tweets and liking users like.writeLike and unlike tweets block.readView blocked users block.writeBlock and unblock users mute.readView muted users mute.writeMute and unmute users offline.accessAccess account when not using the application
Search tweets, manage bookmarks, follow/block/mute users, like and retweet, view trends, and more.
Create a new tweet, reply, or quote tweet on X
Parameter Type Required Description textstring Yes The text content of the tweet (max 280 characters) replyToTweetIdstring No Tweet ID to reply to quoteTweetIdstring No Tweet ID to quote mediaIdsstring No Comma-separated media IDs to attach (up to 4) replySettingsstring No Who can reply: "mentionedUsers", "following", "subscribers", or "verified"
Parameter Type Description idstring The ID of the created tweet textstring The text of the created tweet
Delete a tweet authored by the authenticated user
Parameter Type Required Description tweetIdstring Yes The ID of the tweet to delete
Parameter Type Description deletedboolean Whether the tweet was successfully deleted
Search for recent tweets using keywords, hashtags, or advanced query operators
Parameter Type Required Description querystring Yes Search query (supports operators like "from:", "to:", "#hashtag", "has:images", "is:retweet", "lang:") maxResultsnumber No Maximum number of results (10-100, default 10) startTimestring No Oldest UTC timestamp in ISO 8601 format (e.g., 2024-01-01T00:00:00Z) endTimestring No Newest UTC timestamp in ISO 8601 format sinceIdstring No Returns tweets with ID greater than this untilIdstring No Returns tweets with ID less than this sortOrderstring No Sort order: "recency" or "relevancy" nextTokenstring No Pagination token for next page of results
Parameter Type Description tweetsarray Array of tweets matching the search query ↳ id string Tweet ID ↳ text string Tweet text content ↳ createdAt string Tweet creation timestamp ↳ authorId string Author user ID ↳ conversationId string Conversation thread ID ↳ inReplyToUserId string User ID being replied to ↳ publicMetrics object Engagement metrics ↳ retweetCount number Number of retweets ↳ replyCount number Number of replies ↳ likeCount number Number of likes ↳ quoteCount number Number of quotes includesobject Additional data including user profiles ↳ users array Array of user objects referenced in tweets ↳ id string User ID ↳ username string Username without @ symbol ↳ name string Display name ↳ description string User bio ↳ profileImageUrl string Profile image URL ↳ verified boolean Whether the user is verified ↳ metrics object User statistics ↳ followersCount number Number of followers ↳ followingCount number Number of users following ↳ tweetCount number Total number of tweets metaobject Search metadata including result count and pagination tokens ↳ resultCount number Number of results returned ↳ newestId string ID of the newest tweet ↳ oldestId string ID of the oldest tweet ↳ nextToken string Pagination token for next page
Look up multiple tweets by their IDs (up to 100)
Parameter Type Required Description idsstring Yes Comma-separated tweet IDs (up to 100)
Parameter Type Description tweetsarray Array of tweets matching the provided IDs ↳ id string Tweet ID ↳ text string Tweet text content ↳ createdAt string Tweet creation timestamp ↳ authorId string Author user ID ↳ conversationId string Conversation thread ID ↳ inReplyToUserId string User ID being replied to ↳ publicMetrics object Engagement metrics ↳ retweetCount number Number of retweets ↳ replyCount number Number of replies ↳ likeCount number Number of likes ↳ quoteCount number Number of quotes includesobject Additional data including user profiles ↳ users array Array of user objects referenced in tweets ↳ id string User ID ↳ username string Username without @ symbol ↳ name string Display name ↳ description string User bio ↳ profileImageUrl string Profile image URL ↳ verified boolean Whether the user is verified ↳ metrics object User statistics ↳ followersCount number Number of followers ↳ followingCount number Number of users following ↳ tweetCount number Total number of tweets
Get tweets that quote a specific tweet
Parameter Type Required Description tweetIdstring Yes The tweet ID to get quote tweets for maxResultsnumber No Maximum number of results (10-100, default 10) paginationTokenstring No Pagination token for next page
Parameter Type Description tweetsarray Array of quote tweets ↳ id string Tweet ID ↳ text string Tweet text content ↳ createdAt string Tweet creation timestamp ↳ authorId string Author user ID ↳ conversationId string Conversation thread ID ↳ inReplyToUserId string User ID being replied to ↳ publicMetrics object Engagement metrics ↳ retweetCount number Number of retweets ↳ replyCount number Number of replies ↳ likeCount number Number of likes ↳ quoteCount number Number of quotes metaobject Pagination metadata ↳ resultCount number Number of results returned ↳ nextToken string Token for next page
Hide or unhide a reply to a tweet authored by the authenticated user
Parameter Type Required Description tweetIdstring Yes The reply tweet ID to hide or unhide hiddenboolean Yes Set to true to hide the reply, false to unhide
Parameter Type Description hiddenboolean Whether the reply is now hidden
Get tweets authored by a specific user
Parameter Type Required Description userIdstring Yes The user ID whose tweets to retrieve maxResultsnumber No Maximum number of results (5-100, default 10) paginationTokenstring No Pagination token for next page of results startTimestring No Oldest UTC timestamp in ISO 8601 format endTimestring No Newest UTC timestamp in ISO 8601 format sinceIdstring No Returns tweets with ID greater than this untilIdstring No Returns tweets with ID less than this excludestring No Comma-separated types to exclude: "retweets", "replies"
Parameter Type Description tweetsarray Array of tweets by the user ↳ id string Tweet ID ↳ text string Tweet text content ↳ createdAt string Tweet creation timestamp ↳ authorId string Author user ID ↳ conversationId string Conversation thread ID ↳ inReplyToUserId string User ID being replied to ↳ publicMetrics object Engagement metrics ↳ retweetCount number Number of retweets ↳ replyCount number Number of replies ↳ likeCount number Number of likes ↳ quoteCount number Number of quotes includesobject Additional data including user profiles ↳ users array Array of user objects referenced in tweets ↳ id string User ID ↳ username string Username without @ symbol ↳ name string Display name ↳ description string User bio ↳ profileImageUrl string Profile image URL ↳ verified boolean Whether the user is verified ↳ metrics object User statistics ↳ followersCount number Number of followers ↳ followingCount number Number of users following ↳ tweetCount number Total number of tweets metaobject Pagination metadata ↳ resultCount number Number of results returned ↳ newestId string ID of the newest tweet ↳ oldestId string ID of the oldest tweet ↳ nextToken string Token for next page ↳ previousToken string Token for previous page
Get tweets that mention a specific user
Parameter Type Required Description userIdstring Yes The user ID whose mentions to retrieve maxResultsnumber No Maximum number of results (5-100, default 10) paginationTokenstring No Pagination token for next page of results startTimestring No Oldest UTC timestamp in ISO 8601 format endTimestring No Newest UTC timestamp in ISO 8601 format sinceIdstring No Returns tweets with ID greater than this untilIdstring No Returns tweets with ID less than this
Parameter Type Description tweetsarray Array of tweets mentioning the user ↳ id string Tweet ID ↳ text string Tweet text content ↳ createdAt string Tweet creation timestamp ↳ authorId string Author user ID ↳ conversationId string Conversation thread ID ↳ inReplyToUserId string User ID being replied to ↳ publicMetrics object Engagement metrics ↳ retweetCount number Number of retweets ↳ replyCount number Number of replies ↳ likeCount number Number of likes ↳ quoteCount number Number of quotes includesobject Additional data including user profiles ↳ users array Array of user objects referenced in tweets ↳ id string User ID ↳ username string Username without @ symbol ↳ name string Display name ↳ description string User bio ↳ profileImageUrl string Profile image URL ↳ verified boolean Whether the user is verified ↳ metrics object User statistics ↳ followersCount number Number of followers ↳ followingCount number Number of users following ↳ tweetCount number Total number of tweets metaobject Pagination metadata ↳ resultCount number Number of results returned ↳ newestId string ID of the newest tweet ↳ oldestId string ID of the oldest tweet ↳ nextToken string Token for next page ↳ previousToken string Token for previous page
Get the reverse chronological home timeline for the authenticated user
Parameter Type Required Description userIdstring Yes The authenticated user ID maxResultsnumber No Maximum number of results (1-100, default 10) paginationTokenstring No Pagination token for next page of results startTimestring No Oldest UTC timestamp in ISO 8601 format endTimestring No Newest UTC timestamp in ISO 8601 format sinceIdstring No Returns tweets with ID greater than this untilIdstring No Returns tweets with ID less than this excludestring No Comma-separated types to exclude: "retweets", "replies"
Parameter Type Description tweetsarray Array of timeline tweets ↳ id string Tweet ID ↳ text string Tweet text content ↳ createdAt string Tweet creation timestamp ↳ authorId string Author user ID ↳ conversationId string Conversation thread ID ↳ inReplyToUserId string User ID being replied to ↳ publicMetrics object Engagement metrics ↳ retweetCount number Number of retweets ↳ replyCount number Number of replies ↳ likeCount number Number of likes ↳ quoteCount number Number of quotes includesobject Additional data including user profiles ↳ users array Array of user objects referenced in tweets ↳ id string User ID ↳ username string Username without @ symbol ↳ name string Display name ↳ description string User bio ↳ profileImageUrl string Profile image URL ↳ verified boolean Whether the user is verified ↳ metrics object User statistics ↳ followersCount number Number of followers ↳ followingCount number Number of users following ↳ tweetCount number Total number of tweets metaobject Pagination metadata ↳ resultCount number Number of results returned ↳ newestId string ID of the newest tweet ↳ oldestId string ID of the oldest tweet ↳ nextToken string Token for next page ↳ previousToken string Token for previous page
Like or unlike a tweet on X
Parameter Type Required Description userIdstring Yes The authenticated user ID tweetIdstring Yes The tweet ID to like or unlike actionstring Yes Action to perform: "like" or "unlike"
Parameter Type Description likedboolean Whether the tweet is now liked
Retweet or unretweet a tweet on X
Parameter Type Required Description userIdstring Yes The authenticated user ID tweetIdstring Yes The tweet ID to retweet or unretweet actionstring Yes Action to perform: "retweet" or "unretweet"
Parameter Type Description retweetedboolean Whether the tweet is now retweeted
Get tweets liked by a specific user
Parameter Type Required Description userIdstring Yes The user ID whose liked tweets to retrieve maxResultsnumber No Maximum number of results (5-100) paginationTokenstring No Pagination token for next page
Parameter Type Description tweetsarray Array of liked tweets ↳ id string Tweet ID ↳ text string Tweet content ↳ createdAt string Creation timestamp ↳ authorId string Author user ID metaobject Pagination metadata ↳ resultCount number Number of results returned ↳ nextToken string Token for next page
Get the list of users who liked a specific tweet
Parameter Type Required Description tweetIdstring Yes The tweet ID to get liking users for maxResultsnumber No Maximum number of results (1-100, default 100) paginationTokenstring No Pagination token for next page
Parameter Type Description usersarray Array of users who liked the tweet ↳ id string User ID ↳ username string Username without @ symbol ↳ name string Display name ↳ description string User bio ↳ profileImageUrl string Profile image URL ↳ verified boolean Whether the user is verified ↳ metrics object User statistics ↳ followersCount number Number of followers ↳ followingCount number Number of users following ↳ tweetCount number Total number of tweets metaobject Pagination metadata ↳ resultCount number Number of results returned ↳ nextToken string Token for next page
Get the list of users who retweeted a specific tweet
Parameter Type Required Description tweetIdstring Yes The tweet ID to get retweeters for maxResultsnumber No Maximum number of results (1-100, default 100) paginationTokenstring No Pagination token for next page
Parameter Type Description usersarray Array of users who retweeted the tweet ↳ id string User ID ↳ username string Username without @ symbol ↳ name string Display name ↳ description string User bio ↳ profileImageUrl string Profile image URL ↳ verified boolean Whether the user is verified ↳ metrics object User statistics ↳ followersCount number Number of followers ↳ followingCount number Number of users following ↳ tweetCount number Total number of tweets metaobject Metadata ↳ resultCount number Number of results returned ↳ nextToken string Token for next page
Get bookmarked tweets for the authenticated user
Parameter Type Required Description userIdstring Yes The authenticated user ID maxResultsnumber No Maximum number of results (1-100) paginationTokenstring No Pagination token for next page of results
Parameter Type Description tweetsarray Array of bookmarked tweets ↳ id string Tweet ID ↳ text string Tweet text content ↳ createdAt string Tweet creation timestamp ↳ authorId string Author user ID ↳ conversationId string Conversation thread ID ↳ inReplyToUserId string User ID being replied to ↳ publicMetrics object Engagement metrics ↳ retweetCount number Number of retweets ↳ replyCount number Number of replies ↳ likeCount number Number of likes ↳ quoteCount number Number of quotes includesobject Additional data including user profiles ↳ users array Array of user objects referenced in tweets ↳ id string User ID ↳ username string Username without @ symbol ↳ name string Display name ↳ description string User bio ↳ profileImageUrl string Profile image URL ↳ verified boolean Whether the user is verified ↳ metrics object User statistics ↳ followersCount number Number of followers ↳ followingCount number Number of users following ↳ tweetCount number Total number of tweets metaobject Pagination metadata ↳ resultCount number Number of results returned ↳ newestId string ID of the newest tweet ↳ oldestId string ID of the oldest tweet ↳ nextToken string Token for next page ↳ previousToken string Token for previous page
Bookmark a tweet for the authenticated user
Parameter Type Required Description userIdstring Yes The authenticated user ID tweetIdstring Yes The tweet ID to bookmark
Parameter Type Description bookmarkedboolean Whether the tweet was successfully bookmarked
Remove a tweet from the authenticated user's bookmarks
Parameter Type Required Description userIdstring Yes The authenticated user ID tweetIdstring Yes The tweet ID to remove from bookmarks
Parameter Type Description bookmarkedboolean Whether the tweet is still bookmarked (should be false after deletion)
Get the authenticated user's profile information
Parameter Type Required Description
Parameter Type Description userobject Authenticated user profile ↳ id string User ID ↳ username string Username without @ symbol ↳ name string Display name ↳ description string User bio ↳ profileImageUrl string Profile image URL ↳ verified boolean Whether the user is verified ↳ metrics object User statistics ↳ followersCount number Number of followers ↳ followingCount number Number of users following ↳ tweetCount number Total number of tweets
Search for X users by name, username, or bio
Parameter Type Required Description querystring Yes Search keyword (1-50 chars, matches name, username, or bio) maxResultsnumber No Maximum number of results (1-1000, default 100) nextTokenstring No Pagination token for next page
Parameter Type Description usersarray Array of users matching the search query ↳ id string User ID ↳ username string Username without @ symbol ↳ name string Display name ↳ description string User bio ↳ profileImageUrl string Profile image URL ↳ verified boolean Whether the user is verified ↳ metrics object User statistics ↳ followersCount number Number of followers ↳ followingCount number Number of users following ↳ tweetCount number Total number of tweets metaobject Search metadata ↳ resultCount number Number of results returned ↳ nextToken string Pagination token for next page
Get the list of followers for a user
Parameter Type Required Description userIdstring Yes The user ID whose followers to retrieve maxResultsnumber No Maximum number of results (1-1000, default 100) paginationTokenstring No Pagination token for next page
Parameter Type Description usersarray Array of follower user profiles ↳ id string User ID ↳ username string Username without @ symbol ↳ name string Display name ↳ description string User bio ↳ profileImageUrl string Profile image URL ↳ verified boolean Whether the user is verified ↳ metrics object User statistics ↳ followersCount number Number of followers ↳ followingCount number Number of users following ↳ tweetCount number Total number of tweets metaobject Pagination metadata ↳ resultCount number Number of results returned ↳ nextToken string Token for next page
Get the list of users that a user is following
Parameter Type Required Description userIdstring Yes The user ID whose following list to retrieve maxResultsnumber No Maximum number of results (1-1000, default 100) paginationTokenstring No Pagination token for next page
Parameter Type Description usersarray Array of users being followed ↳ id string User ID ↳ username string Username without @ symbol ↳ name string Display name ↳ description string User bio ↳ profileImageUrl string Profile image URL ↳ verified boolean Whether the user is verified ↳ metrics object User statistics ↳ followersCount number Number of followers ↳ followingCount number Number of users following ↳ tweetCount number Total number of tweets metaobject Pagination metadata ↳ resultCount number Number of results returned ↳ nextToken string Token for next page
Follow or unfollow a user on X
Parameter Type Required Description userIdstring Yes The authenticated user ID targetUserIdstring Yes The user ID to follow or unfollow actionstring Yes Action to perform: "follow" or "unfollow"
Parameter Type Description followingboolean Whether you are now following the user pendingFollowboolean Whether the follow request is pending (for protected accounts)
Block or unblock a user on X
Parameter Type Required Description userIdstring Yes The authenticated user ID targetUserIdstring Yes The user ID to block or unblock actionstring Yes Action to perform: "block" or "unblock"
Parameter Type Description blockingboolean Whether you are now blocking the user
Get the list of users blocked by the authenticated user
Parameter Type Required Description userIdstring Yes The authenticated user ID maxResultsnumber No Maximum number of results (1-1000) paginationTokenstring No Pagination token for next page
Parameter Type Description usersarray Array of blocked user profiles ↳ id string User ID ↳ username string Username without @ symbol ↳ name string Display name ↳ description string User bio ↳ profileImageUrl string Profile image URL ↳ verified boolean Whether the user is verified ↳ metrics object User statistics ↳ followersCount number Number of followers ↳ followingCount number Number of users following ↳ tweetCount number Total number of tweets metaobject Pagination metadata ↳ resultCount number Number of results returned ↳ nextToken string Token for next page
Mute or unmute a user on X
Parameter Type Required Description userIdstring Yes The authenticated user ID targetUserIdstring Yes The user ID to mute or unmute actionstring Yes Action to perform: "mute" or "unmute"
Parameter Type Description mutingboolean Whether you are now muting the user
Get trending topics for a specific location by WOEID (e.g., 1 for worldwide, 23424977 for US)
Parameter Type Required Description woeidstring Yes Yahoo Where On Earth ID (e.g., "1" for worldwide, "23424977" for US, "23424975" for UK) maxTrendsnumber No Maximum number of trends to return (1-50, default 20)
Parameter Type Description trendsarray Array of trending topics ↳ trendName string Name of the trending topic ↳ tweetCount number Number of tweets for this trend
Get personalized trending topics for the authenticated user
Parameter Type Required Description
Parameter Type Description trendsarray Array of personalized trending topics ↳ trendName string Name of the trending topic ↳ postCount number Number of posts for this trend ↳ category string Category of the trend ↳ trendingSince string ISO 8601 timestamp of when the topic started trending
Get the API usage data for your X project
Parameter Type Required Description daysnumber No Number of days of usage data to return (1-90, default 7)
Parameter Type Description capResetDaynumber Day of month when usage cap resets projectIdstring The project ID projectCapnumber The project tweet consumption cap projectUsagenumber Total tweets consumed in current period dailyProjectUsagearray Daily project usage breakdown ↳ date string Usage date in ISO 8601 format ↳ usage number Number of tweets consumed dailyClientAppUsagearray Daily per-app usage breakdown ↳ clientAppId string Client application ID ↳ usage array Daily usage entries for this app ↳ date string Usage date in ISO 8601 format ↳ usage number Number of tweets consumed