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.
OAuth scopes
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/x |
| Environment variables | X_CLIENT_ID, X_CLIENT_SECRET |
| Scope | Description |
|---|---|
tweet.read | Read tweets and timeline |
tweet.write | Post, repost, and delete tweets |
tweet.moderate.write | Hide and unhide replies to tweets |
users.read | Read user profiles and account information |
follows.read | View followers and following lists |
follows.write | Follow and unfollow users |
bookmark.read | View bookmarked tweets |
bookmark.write | Add and remove bookmarks |
like.read | View liked tweets and liking users |
like.write | Like and unlike tweets |
block.read | View blocked users |
block.write | Block and unblock users |
mute.read | View muted users |
mute.write | Mute and unmute users |
offline.access | Access account when not using the application |
Use the block
Search tweets, manage bookmarks, follow/block/mute users, like and retweet, view trends, and more.
Actions
X Create Tweet
Create a new tweet, reply, or quote tweet on X
Inputs and outputs
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
text | string | Yes | The text content of the tweet (max 280 characters) |
replyToTweetId | string | No | Tweet ID to reply to |
quoteTweetId | string | No | Tweet ID to quote |
mediaIds | string | No | Comma-separated media IDs to attach (up to 4) |
replySettings | string | No | Who can reply: "mentionedUsers", "following", "subscribers", or "verified" |
Output
| Parameter | Type | Description |
|---|---|---|
id | string | The ID of the created tweet |
text | string | The text of the created tweet |
X Delete Tweet
Delete a tweet authored by the authenticated user
Inputs and outputs
X Search Tweets
Search for recent tweets using keywords, hashtags, or advanced query operators
Inputs and outputs
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Search query (supports operators like "from:", "to:", "#hashtag", "has:images", "is:retweet", "lang:") |
maxResults | number | No | Maximum number of results (10-100, default 10) |
startTime | string | No | Oldest UTC timestamp in ISO 8601 format (e.g., 2024-01-01T00:00:00Z) |
endTime | string | No | Newest UTC timestamp in ISO 8601 format |
sinceId | string | No | Returns tweets with ID greater than this |
untilId | string | No | Returns tweets with ID less than this |
sortOrder | string | No | Sort order: "recency" or "relevancy" |
nextToken | string | No | Pagination token for next page of results |
Output
| Parameter | Type | Description |
|---|---|---|
tweets | array | 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 |
includes | object | 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 |
meta | object | 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 |
X Get Tweets By IDs
Look up multiple tweets by their IDs (up to 100)
Inputs and outputs
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
ids | string | Yes | Comma-separated tweet IDs (up to 100) |
Output
| Parameter | Type | Description |
|---|---|---|
tweets | array | 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 |
includes | object | 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 |
X Get Quote Tweets
Get tweets that quote a specific tweet
Inputs and outputs
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
tweetId | string | Yes | The tweet ID to get quote tweets for |
maxResults | number | No | Maximum number of results (10-100, default 10) |
paginationToken | string | No | Pagination token for next page |
Output
| Parameter | Type | Description |
|---|---|---|
tweets | array | 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 |
meta | object | Pagination metadata |
↳ resultCount | number | Number of results returned |
↳ nextToken | string | Token for next page |
X Hide Reply
Hide or unhide a reply to a tweet authored by the authenticated user
Inputs and outputs
X Get User Tweets
Get tweets authored by a specific user
Inputs and outputs
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | The user ID whose tweets to retrieve |
maxResults | number | No | Maximum number of results (5-100, default 10) |
paginationToken | string | No | Pagination token for next page of results |
startTime | string | No | Oldest UTC timestamp in ISO 8601 format |
endTime | string | No | Newest UTC timestamp in ISO 8601 format |
sinceId | string | No | Returns tweets with ID greater than this |
untilId | string | No | Returns tweets with ID less than this |
exclude | string | No | Comma-separated types to exclude: "retweets", "replies" |
Output
| Parameter | Type | Description |
|---|---|---|
tweets | array | 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 |
includes | object | 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 |
meta | object | 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 |
X Get User Mentions
Get tweets that mention a specific user
Inputs and outputs
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | The user ID whose mentions to retrieve |
maxResults | number | No | Maximum number of results (5-100, default 10) |
paginationToken | string | No | Pagination token for next page of results |
startTime | string | No | Oldest UTC timestamp in ISO 8601 format |
endTime | string | No | Newest UTC timestamp in ISO 8601 format |
sinceId | string | No | Returns tweets with ID greater than this |
untilId | string | No | Returns tweets with ID less than this |
Output
| Parameter | Type | Description |
|---|---|---|
tweets | array | 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 |
includes | object | 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 |
meta | object | 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 |
X Get User Timeline
Get the reverse chronological home timeline for the authenticated user
Inputs and outputs
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | The authenticated user ID |
maxResults | number | No | Maximum number of results (1-100, default 10) |
paginationToken | string | No | Pagination token for next page of results |
startTime | string | No | Oldest UTC timestamp in ISO 8601 format |
endTime | string | No | Newest UTC timestamp in ISO 8601 format |
sinceId | string | No | Returns tweets with ID greater than this |
untilId | string | No | Returns tweets with ID less than this |
exclude | string | No | Comma-separated types to exclude: "retweets", "replies" |
Output
| Parameter | Type | Description |
|---|---|---|
tweets | array | 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 |
includes | object | 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 |
meta | object | 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 |
X Manage Like
Like or unlike a tweet on X
Inputs and outputs
X Manage Retweet
Retweet or unretweet a tweet on X
Inputs and outputs
X Get Liked Tweets
Get tweets liked by a specific user
Inputs and outputs
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | The user ID whose liked tweets to retrieve |
maxResults | number | No | Maximum number of results (5-100) |
paginationToken | string | No | Pagination token for next page |
Output
| Parameter | Type | Description |
|---|---|---|
tweets | array | Array of liked tweets |
↳ id | string | Tweet ID |
↳ text | string | Tweet content |
↳ createdAt | string | Creation timestamp |
↳ authorId | string | Author user ID |
meta | object | Pagination metadata |
↳ resultCount | number | Number of results returned |
↳ nextToken | string | Token for next page |
X Get Liking Users
Get the list of users who liked a specific tweet
Inputs and outputs
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
tweetId | string | Yes | The tweet ID to get liking users for |
maxResults | number | No | Maximum number of results (1-100, default 100) |
paginationToken | string | No | Pagination token for next page |
Output
| Parameter | Type | Description |
|---|---|---|
users | array | 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 |
meta | object | Pagination metadata |
↳ resultCount | number | Number of results returned |
↳ nextToken | string | Token for next page |
X Get Retweeted By
Get the list of users who retweeted a specific tweet
Inputs and outputs
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
tweetId | string | Yes | The tweet ID to get retweeters for |
maxResults | number | No | Maximum number of results (1-100, default 100) |
paginationToken | string | No | Pagination token for next page |
Output
| Parameter | Type | Description |
|---|---|---|
users | array | 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 |
meta | object | Metadata |
↳ resultCount | number | Number of results returned |
↳ nextToken | string | Token for next page |
X Get Bookmarks
Get bookmarked tweets for the authenticated user
Inputs and outputs
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | The authenticated user ID |
maxResults | number | No | Maximum number of results (1-100) |
paginationToken | string | No | Pagination token for next page of results |
Output
| Parameter | Type | Description |
|---|---|---|
tweets | array | 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 |
includes | object | 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 |
meta | object | 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 |
X Create Bookmark
Bookmark a tweet for the authenticated user
Inputs and outputs
X Delete Bookmark
Remove a tweet from the authenticated user's bookmarks
Inputs and outputs
X Get Me
Get the authenticated user's profile information
Inputs and outputs
Input
| Parameter | Type | Required | Description |
|---|
Output
| Parameter | Type | Description |
|---|---|---|
user | object | 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 |
X Search Users
Search for X users by name, username, or bio
Inputs and outputs
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Search keyword (1-50 chars, matches name, username, or bio) |
maxResults | number | No | Maximum number of results (1-1000, default 100) |
nextToken | string | No | Pagination token for next page |
Output
| Parameter | Type | Description |
|---|---|---|
users | array | 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 |
meta | object | Search metadata |
↳ resultCount | number | Number of results returned |
↳ nextToken | string | Pagination token for next page |
X Get Followers
Get the list of followers for a user
Inputs and outputs
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | The user ID whose followers to retrieve |
maxResults | number | No | Maximum number of results (1-1000, default 100) |
paginationToken | string | No | Pagination token for next page |
Output
| Parameter | Type | Description |
|---|---|---|
users | array | 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 |
meta | object | Pagination metadata |
↳ resultCount | number | Number of results returned |
↳ nextToken | string | Token for next page |
X Get Following
Get the list of users that a user is following
Inputs and outputs
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | The user ID whose following list to retrieve |
maxResults | number | No | Maximum number of results (1-1000, default 100) |
paginationToken | string | No | Pagination token for next page |
Output
| Parameter | Type | Description |
|---|---|---|
users | array | 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 |
meta | object | Pagination metadata |
↳ resultCount | number | Number of results returned |
↳ nextToken | string | Token for next page |
X Manage Follow
Follow or unfollow a user on X
Inputs and outputs
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | The authenticated user ID |
targetUserId | string | Yes | The user ID to follow or unfollow |
action | string | Yes | Action to perform: "follow" or "unfollow" |
Output
| Parameter | Type | Description |
|---|---|---|
following | boolean | Whether you are now following the user |
pendingFollow | boolean | Whether the follow request is pending (for protected accounts) |
X Manage Block
Block or unblock a user on X
Inputs and outputs
X Get Blocking
Get the list of users blocked by the authenticated user
Inputs and outputs
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | The authenticated user ID |
maxResults | number | No | Maximum number of results (1-1000) |
paginationToken | string | No | Pagination token for next page |
Output
| Parameter | Type | Description |
|---|---|---|
users | array | 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 |
meta | object | Pagination metadata |
↳ resultCount | number | Number of results returned |
↳ nextToken | string | Token for next page |
X Manage Mute
Mute or unmute a user on X
Inputs and outputs
X Get Trends By WOEID
Get trending topics for a specific location by WOEID (e.g., 1 for worldwide, 23424977 for US)
Inputs and outputs
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
woeid | string | Yes | Yahoo Where On Earth ID (e.g., "1" for worldwide, "23424977" for US, "23424975" for UK) |
maxTrends | number | No | Maximum number of trends to return (1-50, default 20) |
Output
| Parameter | Type | Description |
|---|---|---|
trends | array | Array of trending topics |
↳ trendName | string | Name of the trending topic |
↳ tweetCount | number | Number of tweets for this trend |
X Get Personalized Trends
Get personalized trending topics for the authenticated user
Inputs and outputs
Input
| Parameter | Type | Required | Description |
|---|
Output
| Parameter | Type | Description |
|---|---|---|
trends | array | 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 |
X Get Usage
Get the API usage data for your X project
Inputs and outputs
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
days | number | No | Number of days of usage data to return (1-90, default 7) |
Output
| Parameter | Type | Description |
|---|---|---|
capResetDay | number | Day of month when usage cap resets |
projectId | string | The project ID |
projectCap | number | The project tweet consumption cap |
projectUsage | number | Total tweets consumed in current period |
dailyProjectUsage | array | Daily project usage breakdown |
↳ date | string | Usage date in ISO 8601 format |
↳ usage | number | Number of tweets consumed |
dailyClientAppUsage | array | 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 |