Twitter (X)

Connect to Twitter (X). Post and manage tweets, read timelines, handle direct messages, manage followers, like and bookmark content, work with lists, upload media, and monitor Spaces — all on behalf of your users via OAuth 2.0 PKCE.

Supports authentication: OAuth 2.0

What you can build with this connector

Use case	Tools involved
Automated social publishing	twitter_post_create → twitter_post_lookup (verify)
Audience growth agent	twitter_followers_get → twitter_user_follow → twitter_user_lookup
Content monitoring	twitter_recent_search → twitter_post_lookup → twitter_post_like
Thread composer	twitter_post_create (with reply.in_reply_to_tweet_id chain)
DM outreach automation	twitter_followers_get → twitter_dm_send
List curation agent	twitter_recent_search → twitter_list_create → twitter_list_member_add
Engagement tracker	twitter_post_likers_get + twitter_post_retweeters_get → aggregate stats
Content bookmarking	twitter_recent_search → twitter_bookmark_add
Spaces discovery	twitter_spaces_search → twitter_space_get → twitter_space_posts_get
Media-rich posting	twitter_media_upload → twitter_post_create (with media.media_ids)

Key concepts:

• Tweet IDs: All tweet operations use numeric string IDs (e.g., "1234567890123456789"). Fetch IDs from search or timeline results before updating or deleting.
• User fields: By default, user objects return only id, name, and username. Use user.fields expansions to request profile_image_url, description, public_metrics, verified, and more.
• Tweet fields: Request extra context with tweet.fields: author_id, created_at, public_metrics, entities, referenced_tweets.
• Pagination: List endpoints return a next_token in meta. Pass it as pagination_token to retrieve the next page. Maximum results per page is 100 for most endpoints.
• Rate limits: Twitter API v2 enforces per-endpoint rate limits. The free tier allows 1 500 tweet reads and 500 tweet writes per month. Monitor x-rate-limit-remaining response headers.
• OAuth scopes: Each tool requires specific OAuth scopes. Ensure the connection was authorized with all required scopes before calling write operations.
• Media uploads: Images under ~5 MB can use twitter_media_upload. For GIFs, videos, or larger files, use twitter_media_upload_large or the chunked flow (twitter_media_upload_init → twitter_media_upload_append → twitter_media_upload_status_get).
• Authenticated user ID: Many endpoints require the authenticated user’s own ID. Use twitter_user_me to retrieve it before calling those endpoints.

Set up the agent connector

Register your Twitter app credentials with Scalekit so it can manage the OAuth 2.0 authentication flow and token lifecycle on your behalf. You’ll need a Client ID and Client Secret from the Twitter Developer Portal.

1. Create a Twitter connection in Scalekit

   • In Scalekit dashboard, go to Agent Auth → Create Connection. Search for Twitter and click Create.

     

   • In the Configure Twitter Connection panel, copy the Redirect URI. It looks like https://<SCALEKIT_ENVIRONMENT_URL>/sso/v1/oauth/<CONNECTION_ID>/callback. You’ll paste this into Twitter in the next step.

     

2. Create an app in the Twitter Developer Portal

   • Go to the Twitter Developer Portal and sign in.

   • Click + Add App (or + Create Project to group apps by environment).

     

   • Select Production environment and give your app a name.

3. Configure user authentication settings

   • In your app’s overview, find User authentication settings and click Set up.

     

   • Set the following values:

     Setting	Value
     App permissions	Read and Write — needed to post and manage content on behalf of users
     Type of App	Web App, Automated App or Bot
     Callback URI / Redirect URL	Paste the Redirect URI from Scalekit
     Website URL	Your application’s public homepage

   • Click Save.

4. Copy OAuth 2.0 credentials

   • In your app, navigate to Keys and tokens.

   • Under OAuth 2.0 Client ID and Client Secret, click Generate (or Regenerate if credentials already exist).

   • Copy the Client ID and Client Secret.

     

   Client secret is shown once

   The Client Secret is masked after the initial creation. If you lose it, regenerate it in the Twitter Developer Portal — this invalidates all existing user tokens.

5. Add credentials in Scalekit

   • In Scalekit dashboard, go to Agent Auth → Connections and open the Twitter connection you created.

   • Enter your credentials:

     • Client ID — from the Twitter OAuth 2.0 section
     • Client Secret — copied in the previous step
     • Scopes — select the permissions your app needs:
       • tweet.read — read tweets and timelines
       • tweet.write — create, delete, and manage tweets
       • users.read — read user profile data
       • follows.read — read follower/following lists
       • follows.write — follow and unfollow users
       • like.read — read liked tweets
       • like.write — like and unlike tweets
       • bookmark.read — read bookmarked tweets
       • bookmark.write — add and remove bookmarks
       • list.read — read list membership and tweets
       • list.write — create, update, and delete lists
       • dm.read — read direct messages
       • dm.write — send direct messages
       • mute.read — read muted users
       • mute.write — mute and unmute users
       • block.read — read blocked users
       • block.write — block and unblock users
       • offline.access — obtain refresh tokens for long-lived access

     

   • Click Save.

Usage

Connect a user’s Twitter account and make API calls on their behalf — Scalekit handles OAuth 2.0 PKCE and token management automatically.

You can interact with Twitter in two ways: via direct proxy API calls or via Scalekit optimized tool calls. Scroll down to see the full list of available tools.

Proxy API calls

Node.js

import { ScalekitClient } from '@scalekit-sdk/node';
import 'dotenv/config';

const connectionName = 'twitter'; // connection name from Agent Auth → Connections
const identifier = 'user_123';    // your unique user identifier

// Get credentials from app.scalekit.com → Developers → Settings → API Credentials
const scalekit = new ScalekitClient(
  process.env.SCALEKIT_ENV_URL,
  process.env.SCALEKIT_CLIENT_ID,
  process.env.SCALEKIT_CLIENT_SECRET
);
const actions = scalekit.actions;

// Step 1: Generate an authorization link and redirect your user to it
const { link } = await actions.getAuthorizationLink({
  connectionName,
  identifier,
});
console.log('Authorize Twitter:', link);
process.stdout.write('Press Enter after authorizing...');
await new Promise(r => process.stdin.once('data', r));

// Step 2: Make Twitter API v2 requests via the Scalekit proxy
// No token management needed — Scalekit handles refresh automatically
const me = await actions.request({
  connectionName,
  identifier,
  path: '/2/users/me',
  method: 'GET',
  params: { 'user.fields': 'name,username,profile_image_url,description' },
});
console.log('Authenticated user:', me);

// Example: post a tweet
const tweet = await actions.request({
  connectionName,
  identifier,
  path: '/2/tweets',
  method: 'POST',
  body: { text: 'Hello from Scalekit Agent Auth!' },
});
console.log('Posted tweet:', tweet);

// Example: search recent tweets
const search = await actions.request({
  connectionName,
  identifier,
  path: '/2/tweets/search/recent',
  method: 'GET',
  params: { query: 'from:twitterdev', max_results: '10' },
});
console.log('Search results:', search);

Python

import os
import scalekit.client
from dotenv import load_dotenv
load_dotenv()

connection_name = "twitter"  # connection name from Agent Auth → Connections
identifier = "user_123"      # your unique user identifier

# Get credentials from app.scalekit.com → Developers → Settings → API Credentials
scalekit_client = scalekit.client.ScalekitClient(
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
    env_url=os.getenv("SCALEKIT_ENV_URL"),
)
actions = scalekit_client.actions

# Step 1: Generate an authorization link and redirect your user to it
link_response = actions.get_authorization_link(
    connection_name=connection_name,
    identifier=identifier
)
print("Authorize Twitter:", link_response.link)
input("Press Enter after authorizing...")

# Step 2: Make Twitter API v2 requests via the Scalekit proxy
me = actions.request(
    connection_name=connection_name,
    identifier=identifier,
    path="/2/users/me",
    method="GET",
    params={"user.fields": "name,username,profile_image_url,description"}
)
print("Authenticated user:", me)

# Example: post a tweet
tweet = actions.request(
    connection_name=connection_name,
    identifier=identifier,
    path="/2/tweets",
    method="POST",
    body={"text": "Hello from Scalekit Agent Auth!"}
)
print("Posted tweet:", tweet)

# Example: search recent tweets
search = actions.request(
    connection_name=connection_name,
    identifier=identifier,
    path="/2/tweets/search/recent",
    method="GET",
    params={"query": "from:twitterdev", "max_results": "10"}
)
print("Search results:", search)

Tool list

twitter_user_me

Returns profile information for the currently authenticated X user. Use this to get the authenticated user’s ID before calling endpoints that require it.

Name	Type	Required	Description
user.fields	string	No	Comma-separated extra user fields: created_at, description, entities, location, pinned_tweet_id, profile_image_url, protected, public_metrics, url, verified
expansions	string	No	Expand related objects. Use pinned_tweet_id to include the pinned tweet object.
tweet.fields	string	No	Fields to return for expanded tweet objects.

twitter_user_lookup

Retrieves detailed public information for a Twitter user by their ID. Optionally expand related data (e.g., pinned tweets) and specify particular user or tweet fields to return.

Name	Type	Required	Description
id	string	Yes	Twitter user ID (e.g., "783214").
user.fields	string	No	Comma-separated extra user fields.
expansions	string	No	Expand related objects (e.g., pinned_tweet_id).
tweet.fields	string	No	Fields for expanded tweet objects.

twitter_user_lookup_by_username

Fetches public profile information for a valid and existing Twitter user by their username. Results may be limited for protected profiles not followed by the authenticated user.

Name	Type	Required	Description
username	string	Yes	Twitter handle without the @ prefix (e.g., "twitter").
user.fields	string	No	Comma-separated extra user fields.
expansions	string	No	Expand related objects.
tweet.fields	string	No	Fields for expanded tweet objects.

twitter_users_lookup

Retrieves detailed information for specified X user IDs. Optionally customize returned fields and expand related entities like pinned tweets.

Name	Type	Required	Description
ids	string	Yes	Comma-separated list of user IDs (max 100).
user.fields	string	No	Comma-separated extra user fields.
expansions	string	No	Expand related objects.
tweet.fields	string	No	Fields for expanded tweet objects.

twitter_users_lookup_by_username

Retrieves detailed information for 1 to 100 Twitter users by their usernames (each 1–15 alphanumeric characters or underscores). Allows customizable user/tweet fields and expansion of related data.

Name	Type	Required	Description
usernames	string	Yes	Comma-separated list of Twitter usernames (max 100, without @).
user.fields	string	No	Comma-separated extra user fields.
expansions	string	No	Expand related objects.
tweet.fields	string	No	Fields for expanded tweet objects.

twitter_post_lookup

Fetches comprehensive details for a single Tweet by its unique ID, provided the Tweet exists and is accessible.

Name	Type	Required	Description
id	string	Yes	The tweet ID to retrieve.
tweet.fields	string	No	Comma-separated tweet fields: author_id, created_at, entities, public_metrics, referenced_tweets, reply_settings, source
expansions	string	No	Expand related objects: author_id, referenced_tweets.id, attachments.media_keys
user.fields	string	No	Fields for expanded author objects.
media.fields	string	No	Fields for expanded media objects: url, preview_image_url, alt_text

twitter_posts_lookup

Retrieves detailed information for one or more Posts (Tweets) identified by their unique IDs. Allows selection of specific fields and expansions.

Name	Type	Required	Description
ids	string	Yes	Comma-separated list of tweet IDs (max 100).
tweet.fields	string	No	Comma-separated tweet fields to include.
expansions	string	No	Expand related objects.
user.fields	string	No	Fields for expanded user objects.
media.fields	string	No	Fields for expanded media objects.

twitter_post_create

Creates a Tweet on Twitter. The text field is required unless card_uri, media_media_ids, poll_options, or quote_tweet_id is provided. Supports media, polls, geo, and reply targeting.

Name	Type	Required	Description
text	string	No*	The text content of the tweet. Maximum 280 characters. Required unless providing card_uri, media.media_ids, poll.options, or quote_tweet_id.
reply.in_reply_to_tweet_id	string	No	Tweet ID to reply to. Creates a threaded reply.
quote_tweet_id	string	No	Tweet ID to quote-tweet.
reply_settings	string	No	Who can reply: mentionedUsers, following, or subscribers. Defaults to everyone.
media.media_ids	array<string>	No	Media IDs from the Twitter media upload API to attach.
poll.options	array<string>	No	Poll option labels (2–4 options). Must be paired with poll.duration_minutes.
poll.duration_minutes	integer	No	Poll duration in minutes (5–10080). Required when poll.options is set.
card_uri	string	No	Card URI for attaching a Twitter card.

*At least one of text, card_uri, media.media_ids, poll.options, or quote_tweet_id is required.

twitter_post_delete

Irreversibly deletes a specific Tweet by its ID. The Tweet may persist in third-party caches after deletion.

Name	Type	Required	Description
id	string	Yes	The ID of the tweet to delete.

twitter_post_retweet

Retweets a Tweet for the authenticated user. The user ID is automatically fetched from the authenticated session — you only need to provide the tweet_id.

Name	Type	Required	Description
tweet_id	string	Yes	The ID of the tweet to retweet.

twitter_post_unretweet

Removes a user’s retweet of a specified Post, if the user had previously retweeted it.

Name	Type	Required	Description
tweet_id	string	Yes	The ID of the tweet to un-retweet.

twitter_post_like

Allows the authenticated user to like a specific, accessible Tweet. The authenticated user’s ID is automatically determined from the OAuth token — you only need to provide the tweet_id.

Name	Type	Required	Description
tweet_id	string	Yes	The ID of the tweet to like.

twitter_post_unlike

Allows an authenticated user to remove their like from a specific post. The action is idempotent and completes successfully even if the post was not liked.

Name	Type	Required	Description
tweet_id	string	Yes	The ID of the tweet to unlike.

twitter_post_likers_get

Retrieves users who have liked the Post (Tweet) identified by the provided ID.

Name	Type	Required	Description
id	string	Yes	The tweet ID whose liking users to retrieve.
max_results	integer	No	Number of results (1–100). Defaults to 100.
pagination_token	string	No	Token from a previous response to retrieve the next page.
user.fields	string	No	Extra user fields to include.
expansions	string	No	Expand related objects.

twitter_post_retweeters_get

Retrieves users who publicly retweeted a specified public Post ID, excluding Quote Tweets and retweets from private accounts.

Name	Type	Required	Description
id	string	Yes	The tweet ID whose retweeters to retrieve.
max_results	integer	No	Number of results (1–100). Defaults to 100.
pagination_token	string	No	Token from a previous response to retrieve the next page.
user.fields	string	No	Extra user fields to include.
expansions	string	No	Expand related objects.

twitter_post_retweets_get

Retrieves Tweets that Retweeted a specified public or authenticated-user-accessible Tweet ID. Optionally customize the response with fields and expansions.

Name	Type	Required	Description
id	string	Yes	The tweet ID whose retweets to retrieve.
max_results	integer	No	Number of results (1–100). Defaults to 100.
pagination_token	string	No	Token from a previous response to retrieve the next page.
tweet.fields	string	No	Tweet fields to include.
expansions	string	No	Expand related objects.
user.fields	string	No	Fields for expanded user objects.

twitter_post_quotes_get

Retrieves Tweets that quote a specified Tweet. Requires a valid Tweet ID.

Name	Type	Required	Description
id	string	Yes	The tweet ID whose quote tweets to retrieve.
max_results	integer	No	Number of results (1–100). Defaults to 10.
pagination_token	string	No	Token from a previous response to retrieve the next page.
tweet.fields	string	No	Tweet fields to include.
expansions	string	No	Expand related objects.
user.fields	string	No	Fields for expanded user objects.

twitter_post_analytics_get

Retrieves analytics data for specified Posts within a defined time range. Returns engagement metrics, impressions, and other analytics. Requires OAuth 2.0 with tweet.read and users.read scopes.

Name	Type	Required	Description
tweet_ids	array<string>	Yes	List of tweet IDs to retrieve analytics for.
start_time	string	Yes	Start of the time range. ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.
end_time	string	Yes	End of the time range. ISO 8601 format.

twitter_recent_search

Searches Tweets from the last 7 days matching a query using X’s search syntax. Ideal for real-time analysis, trend monitoring, or retrieving posts from specific users (e.g., from:username).

Impression count limitation

impression_count returns 0 for other users’ tweets. Use retweet_count, like_count, or quote_count for engagement filtering instead.

Name	Type	Required	Description
query	string	Yes	Search query using Twitter query syntax. Max 512 characters. Example: "from:twitter -is:retweet"
max_results	integer	No	Number of results per page (10–100). Defaults to 10.
pagination_token	string	No	Token from a previous response to retrieve the next page.
start_time	string	No	Oldest UTC timestamp. ISO 8601 format.
end_time	string	No	Newest UTC timestamp. ISO 8601 format.
since_id	string	No	Return tweets with IDs greater than this value (newer).
until_id	string	No	Return tweets with IDs less than this value (older).
tweet.fields	string	No	Comma-separated tweet fields to include.
expansions	string	No	Expand related objects: author_id, referenced_tweets.id
user.fields	string	No	Fields for expanded author objects.

twitter_recent_tweet_counts

Retrieves the count of Tweets matching a specified search query within the last 7 days, aggregated by minute, hour, or day.

Name	Type	Required	Description
query	string	Yes	Search query using Twitter query syntax.
granularity	string	No	Time granularity for aggregation: minute, hour, or day. Defaults to hour.
start_time	string	No	Oldest UTC timestamp. ISO 8601 format.
end_time	string	No	Newest UTC timestamp. ISO 8601 format.
since_id	string	No	Count tweets newer than this tweet ID.
until_id	string	No	Count tweets older than this tweet ID.

twitter_full_archive_search

Academic Research access required

This endpoint requires Academic Research or Enterprise access on your Twitter Developer account. It is not available on Free, Basic, or Pro plans.

Searches the full archive of public Tweets from March 2006 onwards. Use start_time and end_time together for a defined time window. Requires Academic Research access.

Name	Type	Required	Description
query	string	Yes	Search query using Twitter query syntax. Max 1024 characters.
max_results	integer	No	Number of results per page (10–500). Defaults to 10.
next_token	string	No	Token from a previous response to retrieve the next page.
start_time	string	No	Oldest UTC timestamp. ISO 8601 format. Cannot be used with since_id.
end_time	string	No	Newest UTC timestamp. ISO 8601 format. Cannot be used with until_id.
since_id	string	No	Return tweets newer than this ID. Cannot be used with start_time.
until_id	string	No	Return tweets older than this ID. Cannot be used with end_time.
tweet.fields	string	No	Tweet fields to include.
expansions	string	No	Expand related objects.
user.fields	string	No	Fields for expanded user objects.

twitter_full_archive_search_counts

Academic Research access required

This endpoint requires Academic Research or Enterprise access on your Twitter Developer account. It is not available on Free, Basic, or Pro plans.

Returns a count of Tweets from the full archive that match a specified query, aggregated by day, hour, or minute. start_time must be before end_time if both are provided. since_id/until_id cannot be used with start_time/end_time.

Name	Type	Required	Description
query	string	Yes	Search query using Twitter query syntax.
granularity	string	No	Time granularity: minute, hour, or day. Defaults to hour.
start_time	string	No	Oldest UTC timestamp. ISO 8601 format.
end_time	string	No	Newest UTC timestamp. ISO 8601 format.
since_id	string	No	Count tweets newer than this ID.
until_id	string	No	Count tweets older than this ID.
next_token	string	No	Token for pagination.

twitter_user_timeline_get

Retrieves the home timeline (reverse chronological feed) for the authenticated Twitter user. Returns tweets from accounts the user follows and the user’s own tweets.

Use authenticated user's ID

The id parameter must be the authenticated user’s own numeric Twitter user ID. Use twitter_user_me to get your ID first. This endpoint cannot fetch another user’s home timeline.

Name	Type	Required	Description
id	string	Yes	The authenticated user’s own Twitter user ID.
max_results	integer	No	Number of tweets to return (1–100). Defaults to 100.
pagination_token	string	No	Token from a previous response to retrieve the next page.
since_id	string	No	Return tweets newer than this tweet ID. Use for incremental polling.
until_id	string	No	Return tweets older than this tweet ID.
start_time	string	No	Oldest tweet creation time. ISO 8601 format.
end_time	string	No	Newest tweet creation time. ISO 8601 format.
exclude	string	No	Comma-separated types to exclude: retweets, replies.
tweet.fields	string	No	Tweet fields to include.
expansions	string	No	Expand related objects.
user.fields	string	No	Fields for expanded user objects.
media.fields	string	No	Fields for expanded media objects.

twitter_user_liked_tweets_get

Retrieves Tweets liked by a specified Twitter user, provided their liked tweets are public or accessible. Requires like.read scope.

Name	Type	Required	Description
id	string	Yes	Twitter user ID whose liked tweets to retrieve.
max_results	integer	No	Number of results (1–100). Defaults to 100.
pagination_token	string	No	Token from a previous response to retrieve the next page.
tweet.fields	string	No	Tweet fields to include.
expansions	string	No	Expand related objects.
user.fields	string	No	Fields for expanded user objects.

twitter_followers_get

Retrieves a list of users who follow a specified public Twitter user ID. Requires follows.read scope.

Name	Type	Required	Description
id	string	Yes	Twitter user ID whose followers to retrieve.
max_results	integer	No	Number of results (1–1000). Defaults to 100.
pagination_token	string	No	Token from a previous response to retrieve the next page.
user.fields	string	No	Extra user fields to include.
expansions	string	No	Expand related objects.
tweet.fields	string	No	Fields for expanded pinned tweet objects.

twitter_following_get

Retrieves users followed by a specific Twitter user. Allows pagination and customization of returned user and tweet data fields via expansions. Requires follows.read scope.

Name	Type	Required	Description
id	string	Yes	Twitter user ID whose following list to retrieve.
max_results	integer	No	Number of results (1–1000). Defaults to 100.
pagination_token	string	No	Token from a previous response to retrieve the next page.
user.fields	string	No	Extra user fields to include.
expansions	string	No	Expand related objects.
tweet.fields	string	No	Fields for expanded pinned tweet objects.

twitter_user_follow

Allows an authenticated user to follow another user. Results in a pending request if the target user’s tweets are protected. Requires follows.write scope.

Name	Type	Required	Description
target_user_id	string	Yes	The Twitter user ID of the account to follow.

twitter_user_unfollow

Allows the authenticated user to unfollow an existing Twitter user, removing the follow relationship. The source user ID is automatically determined from the authenticated session. Requires follows.write scope.

Name	Type	Required	Description
target_user_id	string	Yes	The Twitter user ID of the account to unfollow.

twitter_bookmark_add

Adds a specified, existing, and accessible Tweet to a user’s bookmarks. Success is indicated by the bookmarked field in the response. Requires bookmark.write scope.

Name	Type	Required	Description
tweet_id	string	Yes	The ID of the tweet to bookmark.

twitter_bookmark_remove

Removes a Tweet from the authenticated user’s bookmarks. The Tweet must have been previously bookmarked by the user for the action to have an effect. Requires bookmark.write scope.

Name	Type	Required	Description
tweet_id	string	Yes	The ID of the tweet to remove from bookmarks.

twitter_bookmarks_get

Retrieves Tweets bookmarked by the authenticated user. The provided User ID must match the authenticated user’s ID. Requires bookmark.read scope.

Name	Type	Required	Description
id	string	Yes	The authenticated user’s own Twitter user ID.
max_results	integer	No	Number of results (1–100). Defaults to 100.
pagination_token	string	No	Token from a previous response to retrieve the next page.
tweet.fields	string	No	Tweet fields to include.
expansions	string	No	Expand related objects.
user.fields	string	No	Fields for expanded user objects.

twitter_list_create

Creates a new, empty List on X (formerly Twitter). The provided name must be unique for the authenticated user. Accounts are added separately. Requires list.write scope.

Name	Type	Required	Description
name	string	Yes	The name for the new list.
description	string	No	A brief description of the list.
private	boolean	No	Set to true to make the list private. Defaults to false (public).

twitter_list_update

Updates an existing Twitter List’s name, description, or privacy status. Requires the List ID and at least one mutable property. Requires list.write scope.

Name	Type	Required	Description
id	string	Yes	The list ID to update.
name	string	No	New name for the list.
description	string	No	New description for the list.
private	boolean	No	Update the privacy setting of the list.

twitter_list_delete

Permanently deletes a specified Twitter List using its ID. The list must be owned by the authenticated user. This action is irreversible. Requires list.write scope.

Name	Type	Required	Description
id	string	Yes	The list ID to delete.

twitter_list_lookup

Returns metadata for a specific Twitter List, identified by its ID. Does not return list members. Can expand the owner’s User object via the expansions parameter. Requires list.read scope.

Name	Type	Required	Description
id	string	Yes	The list ID to retrieve.
list.fields	string	No	Extra list fields: created_at, follower_count, member_count, owner_id, private
expansions	string	No	Expand related objects (e.g., owner_id).
user.fields	string	No	Fields for expanded owner user objects.

twitter_list_timeline_get

Fetches the most recent Tweets posted by members of a specified Twitter List. Requires list.read and tweet.read scopes.

Name	Type	Required	Description
id	string	Yes	The list ID whose timeline to retrieve.
max_results	integer	No	Number of tweets to return (1–100). Defaults to 100.
pagination_token	string	No	Token from a previous response to retrieve the next page.
tweet.fields	string	No	Tweet fields to include.
expansions	string	No	Expand related objects.
user.fields	string	No	Fields for expanded author objects.
media.fields	string	No	Fields for expanded media objects.

twitter_list_members_get

Fetches members of a specific Twitter List, identified by its unique ID. Requires list.read scope.

Name	Type	Required	Description
id	string	Yes	The list ID whose members to retrieve.
max_results	integer	No	Number of results (1–100). Defaults to 100.
pagination_token	string	No	Token from a previous response to retrieve the next page.
user.fields	string	No	Extra user fields to include.
expansions	string	No	Expand related objects.

twitter_list_member_add

Adds a user to a specified Twitter List. The list must be owned by the authenticated user. Requires list.write scope.

Name	Type	Required	Description
id	string	Yes	The list ID to add the member to.
user_id	string	Yes	The Twitter user ID to add as a member.

twitter_list_member_remove

Removes a user from a Twitter List. The response is_member field will be false if removal was successful or the user was not a member. Requires list.write scope.

Name	Type	Required	Description
id	string	Yes	The list ID to remove the member from.
user_id	string	Yes	The Twitter user ID to remove from the list.

twitter_list_follow

Allows the authenticated user to follow a specific Twitter List they are permitted to access, subscribing them to the list’s timeline. This does not automatically follow individual list members. Requires list.write scope.

Name	Type	Required	Description
list_id	string	Yes	The list ID to follow.

twitter_list_unfollow

Enables a user to unfollow a specific Twitter List, removing its tweets from their timeline and stopping related notifications. Reports following: false on success, even if the user was not initially following the list. Requires list.write scope.

Name	Type	Required	Description
list_id	string	Yes	The list ID to unfollow.

twitter_list_pin

Pins a specified List to the authenticated user’s profile. The List must exist, the user must have access rights, and the pin limit (typically 5 Lists) must not be exceeded. Requires list.write scope.

Name	Type	Required	Description
list_id	string	Yes	The list ID to pin.

twitter_list_unpin

Unpins a List from the authenticated user’s profile. The user ID is automatically retrieved if not provided. Requires list.write scope.

Name	Type	Required	Description
list_id	string	Yes	The list ID to unpin.

twitter_list_followers_get

Fetches a list of users who follow a specific Twitter List, identified by its ID. Ensure the authenticated user has access if the list is private. Requires list.read scope.

Name	Type	Required	Description
id	string	Yes	The list ID whose followers to retrieve.
max_results	integer	No	Number of results (1–100). Defaults to 100.
pagination_token	string	No	Token from a previous response to retrieve the next page.
user.fields	string	No	Extra user fields to include.
expansions	string	No	Expand related objects.

twitter_user_owned_lists_get

Retrieves Lists created (owned) by a specific Twitter user — not Lists they follow or are subscribed to. Requires list.read scope.

Name	Type	Required	Description
id	string	Yes	Twitter user ID whose owned lists to retrieve.
max_results	integer	No	Number of results (1–100). Defaults to 100.
pagination_token	string	No	Token from a previous response to retrieve the next page.
list.fields	string	No	Extra list fields to include.
expansions	string	No	Expand related objects (e.g., owner_id).
user.fields	string	No	Fields for expanded owner user objects.

twitter_user_followed_lists_get

Returns metadata (not Tweets) for lists a specific Twitter user follows. Optionally includes expanded owner details. Requires list.read scope.

Name	Type	Required	Description
id	string	Yes	Twitter user ID whose followed lists to retrieve.
max_results	integer	No	Number of results (1–100). Defaults to 100.
pagination_token	string	No	Token from a previous response to retrieve the next page.
list.fields	string	No	Extra list fields to include.
expansions	string	No	Expand related objects.
user.fields	string	No	Fields for expanded owner user objects.

twitter_user_list_memberships_get

Retrieves all Twitter Lists a specified user is a member of, including public Lists and private Lists the authenticated user is authorized to view. Requires list.read scope.

Name	Type	Required	Description
id	string	Yes	Twitter user ID whose list memberships to retrieve.
max_results	integer	No	Number of results (1–100). Defaults to 100.
pagination_token	string	No	Token from a previous response to retrieve the next page.
list.fields	string	No	Extra list fields to include.
expansions	string	No	Expand related objects.
user.fields	string	No	Fields for expanded user objects.

twitter_user_pinned_lists_get

Retrieves the Lists a specific, existing Twitter user has pinned to their profile to highlight them. Requires list.read scope.

Name	Type	Required	Description
id	string	Yes	Twitter user ID whose pinned lists to retrieve.
list.fields	string	No	Extra list fields to include.
expansions	string	No	Expand related objects.
user.fields	string	No	Fields for expanded owner user objects.

twitter_dm_send

Sends a new Direct Message with text and/or media to a specified Twitter user. Creates a new DM and does not modify existing messages. Media must be pre-uploaded using a media upload tool. Requires dm.write scope.

Name	Type	Required	Description
participant_id	string	Yes	The Twitter user ID of the DM recipient.
text	string	No*	The text content of the direct message.
media_id	string	No*	Media ID from a prior upload to attach to the message.

*At least one of text or media_id is required.

twitter_dm_conversation_send

Sends a message with optional text and/or media attachments to a specified Twitter Direct Message conversation. Requires dm.write scope.

Name	Type	Required	Description
dm_conversation_id	string	Yes	The DM conversation ID to send the message to.
text	string	No*	The text content of the message.
media_id	string	No*	Media ID from a prior upload to attach.

*At least one of text or media_id is required.

twitter_dm_events_get

Returns recent Direct Message events for the authenticated user, such as new messages or changes in conversation participants. Requires dm.read scope.

Name	Type	Required	Description
max_results	integer	No	Number of events to return (1–100). Defaults to 100.
pagination_token	string	No	Token from a previous response to retrieve the next page.
dm_event.fields	string	No	Extra DM event fields: created_at, sender_id, text, attachments
expansions	string	No	Expand related objects: sender_id, attachments.media_keys
user.fields	string	No	Fields for expanded participant objects.
media.fields	string	No	Fields for expanded media objects.

twitter_dm_conversation_events_get

Fetches Direct Message (DM) events for a one-on-one conversation with a specified participant ID, ordered chronologically newest to oldest. Does not support group DMs. Requires dm.read scope.

Name	Type	Required	Description
participant_id	string	Yes	The Twitter user ID of the conversation participant.
max_results	integer	No	Number of events to return (1–100). Defaults to 100.
pagination_token	string	No	Token from a previous response to retrieve the next page.
dm_event.fields	string	No	Extra DM event fields to include.
expansions	string	No	Expand related objects.

twitter_dm_conversation_retrieve

Retrieves Direct Message (DM) events for a specific conversation ID. Useful for analyzing messages and participant activities. Requires dm.read scope.

Name	Type	Required	Description
dm_conversation_id	string	Yes	The DM conversation ID to retrieve.
max_results	integer	No	Number of events to return (1–100). Defaults to 100.
pagination_token	string	No	Token from a previous response to retrieve the next page.
dm_event.fields	string	No	Extra DM event fields to include.
expansions	string	No	Expand related objects.

twitter_dm_event_get

Fetches a specific Direct Message (DM) event by its unique ID. Allows optional expansion of related data like users or tweets. Requires dm.read scope.

Name	Type	Required	Description
event_id	string	Yes	The unique DM event ID to retrieve.
dm_event.fields	string	No	Extra DM event fields to include.
expansions	string	No	Expand related objects.
user.fields	string	No	Fields for expanded user objects.
media.fields	string	No	Fields for expanded media objects.

twitter_dm_delete

Permanently deletes a specific Twitter Direct Message (DM) event using its event_id, if the authenticated user sent it. This action is irreversible and does not delete entire conversations. Requires dm.write scope.

Name	Type	Required	Description
event_id	string	Yes	The unique DM event ID to delete.

twitter_dm_group_conversation_create

Creates a new group Direct Message (DM) conversation on Twitter. The conversation_type must be Group. Include participant_ids and an initial message with text and optional media attachments using media_id (not media_url). Media must be uploaded first. Requires dm.write scope.

Name	Type	Required	Description
participant_ids	array<string>	Yes	List of Twitter user IDs to include in the group DM (max 49 participants plus yourself).
text	string	No*	The initial message text for the group conversation.
media_id	string	No*	Media ID from a prior upload to attach to the initial message.

*At least one of text or media_id is required.

twitter_user_mute

Mutes a target user on behalf of an authenticated user, preventing the target’s Tweets and Retweets from appearing in the authenticated user’s home timeline without notifying the target. Requires mute.write scope.

Name	Type	Required	Description
target_user_id	string	Yes	The Twitter user ID to mute.

twitter_user_unmute

Unmutes a target user for the authenticated user, allowing them to see Tweets and notifications from the target user again. The source_user_id is automatically populated from the authenticated user’s credentials. Requires mute.write scope.

Name	Type	Required	Description
target_user_id	string	Yes	The Twitter user ID to unmute.

twitter_muted_users_get

Returns user objects muted by the X user identified by the id path parameter. Requires mute.read scope.

Name	Type	Required	Description
id	string	Yes	The authenticated user’s own Twitter user ID.
max_results	integer	No	Number of results (1–1000). Defaults to 100.
pagination_token	string	No	Token from a previous response to retrieve the next page.
user.fields	string	No	Extra user fields to include.
expansions	string	No	Expand related objects.

twitter_blocked_users_get

Retrieves the authenticated user’s block list. The id parameter must be the authenticated user’s ID. Use twitter_user_me to obtain your user ID. Requires block.read scope.

Name	Type	Required	Description
id	string	Yes	The authenticated user’s own Twitter user ID.
max_results	integer	No	Number of results (1–1000). Defaults to 100.
pagination_token	string	No	Token from a previous response to retrieve the next page.
user.fields	string	No	Extra user fields to include.
expansions	string	No	Expand related objects.

twitter_reply_visibility_set

Hides or unhides an existing reply Tweet. Allows the authenticated user to hide or unhide a reply to a conversation they own. You can only hide replies to posts you authored. Requires tweet.moderate.write OAuth scope.

Name	Type	Required	Description
tweet_id	string	Yes	The ID of the reply tweet to hide or unhide.
hidden	boolean	Yes	Set to true to hide the reply, false to unhide it.

twitter_media_upload

Uploads media (images only) to X/Twitter using the v2 API. Only supports images (tweet_image, dm_image) and subtitle files. For GIFs, videos, or any file larger than ~5 MB, use twitter_media_upload_large instead.

Name	Type	Required	Description
media	string	Yes	The media file content as a binary string or URL.
media_type	string	Yes	MIME type of the media (e.g., image/jpeg, image/png).
media_category	string	No	Category for the media: tweet_image or dm_image.
alt_text	string	No	Accessibility description for the image.

twitter_media_upload_base64

Uploads media to X/Twitter using base64-encoded data. Use when you have media content as a base64 string. Only supports images and subtitle files. For videos or GIFs, use twitter_media_upload_large.

Name	Type	Required	Description
media_data	string	Yes	Base64-encoded media content.
media_type	string	Yes	MIME type of the media (e.g., image/jpeg).
media_category	string	No	Category for the media: tweet_image or dm_image.
alt_text	string	No	Accessibility description for the image.

twitter_media_upload_large

Uploads media files to X/Twitter using the v2 media upload API. Supports images, GIFs, and videos via base64-encoded data. For very large files requiring chunked upload, use twitter_media_upload_init → twitter_media_upload_append → twitter_media_upload_status_get.

Name	Type	Required	Description
media_data	string	Yes	Base64-encoded media content.
media_type	string	Yes	MIME type of the media (e.g., video/mp4, image/gif).
media_category	string	Yes	Category: tweet_gif, tweet_video, amplify_video, dm_gif, dm_video, tweet_image, or dm_image.
alt_text	string	No	Accessibility description for the image.

twitter_media_upload_init

Initializes a media upload session for X/Twitter. Returns a media_id for subsequent APPEND and FINALIZE commands. Required for uploading large files or when using the chunked upload workflow.

Name	Type	Required	Description
total_bytes	integer	Yes	Total size of the media file in bytes.
media_type	string	Yes	MIME type of the media to upload.
media_category	string	No	Category for the media. Determines allowed media types.

twitter_media_upload_append

Appends a data chunk to an ongoing media upload session on X/Twitter. Use during chunked media uploads to append each segment of media data in sequence.

Name	Type	Required	Description
media_id	string	Yes	The media_id returned by twitter_media_upload_init.
media_data	string	Yes	Base64-encoded chunk of the media data.
segment_index	integer	Yes	Zero-based index of this chunk in the upload sequence.

twitter_media_upload_status_get

Gets the status of a media upload for X/Twitter. Use to check the processing status of uploaded media, especially for videos and GIFs. Only needed if the FINALIZE command returned processing_info.

Name	Type	Required	Description
media_id	string	Yes	The media_id to check processing status for.

twitter_space_get

Retrieves details for a Twitter Space by its ID, allowing for customization and expansion of related data.

Name	Type	Required	Description
id	string	Yes	The Space ID to retrieve.
space.fields	string	No	Extra space fields: created_at, creator_id, ended_at, host_ids, lang, participant_count, scheduled_start, speaker_ids, started_at, state, subscriber_count, title, topic_ids
expansions	string	No	Expand related objects (e.g., creator_id, host_ids).
user.fields	string	No	Fields for expanded user objects.

twitter_spaces_get

Fetches detailed information for one or more Twitter Spaces (live, scheduled, or ended) by their unique IDs. At least one Space ID must be provided.

Name	Type	Required	Description
ids	string	Yes	Comma-separated list of Space IDs (max 100).
space.fields	string	No	Extra space fields to include.
expansions	string	No	Expand related objects.
user.fields	string	No	Fields for expanded user objects.

twitter_spaces_search

Searches for Twitter Spaces by a textual query. Optionally filter by state (live, scheduled, all) to discover audio conversations.

Name	Type	Required	Description
query	string	Yes	Text query to search for Spaces.
state	string	No	Filter by state: live, scheduled, or all. Defaults to live.
max_results	integer	No	Number of results (1–100). Defaults to 100.
space.fields	string	No	Extra space fields to include.
expansions	string	No	Expand related objects.
user.fields	string	No	Fields for expanded user objects.

twitter_spaces_by_creator_get

Retrieves Twitter Spaces created by a list of specified User IDs, with options to customize returned data fields.

Name	Type	Required	Description
user_ids	string	Yes	Comma-separated list of user IDs whose Spaces to retrieve (max 100).
space.fields	string	No	Extra space fields to include.
expansions	string	No	Expand related objects.
user.fields	string	No	Fields for expanded user objects.

twitter_space_posts_get

Retrieves Tweets that were shared/posted during a Twitter Space broadcast. Returns Tweets that participants explicitly shared during the Space session, not audio transcripts. Most Spaces have zero associated Tweets — empty results are normal.

Name	Type	Required	Description
id	string	Yes	The Space ID whose associated tweets to retrieve.
max_results	integer	No	Number of results (1–100). Defaults to 100.
tweet.fields	string	No	Tweet fields to include.
expansions	string	No	Expand related objects.
user.fields	string	No	Fields for expanded user objects.

twitter_space_ticket_buyers_get

Retrieves a list of users who purchased tickets for a specific, valid, and ticketed Twitter Space.

Name	Type	Required	Description
id	string	Yes	The Space ID whose ticket buyers to retrieve.
user.fields	string	No	Extra user fields to include.
expansions	string	No	Expand related objects.

twitter_tweet_usage_get

Fetches Tweet usage statistics for a Project (e.g., consumption, caps, daily breakdowns for Project and Client Apps) to monitor API limits. Data can be retrieved for 1 to 90 days.

Name	Type	Required	Description
days	integer	No	Number of days of usage data to retrieve (1–90). Defaults to 7.

twitter_tweet_label_stream

Stream real-time Tweet label events (apply/remove). Requires Enterprise access and App-Only OAuth 2.0 auth. Returns PublicTweetNotice or PublicTweetUnviewable events.

Enterprise access required

This endpoint requires Enterprise access. A 403 error indicates missing Enterprise access or incorrect auth type — App-Only OAuth 2.0 is required, not user-context OAuth.

Name	Type	Required	Description
backfill_minutes	integer	No	Number of minutes of backfill data to receive on reconnect (0–5).

twitter_compliance_job_create

Creates a new compliance job to check the status of Tweet or user IDs. Upload IDs as a plain text file (one ID per line) to the upload_url received in the response.

Name	Type	Required	Description
type	string	Yes	Type of compliance job: tweets or users.
name	string	No	Descriptive label for the job.
resumable	boolean	No	Whether the upload supports resumable uploads.

twitter_compliance_job_get

Retrieves status, download/upload URLs, and other details for an existing Twitter compliance job specified by its unique ID.

Name	Type	Required	Description
id	string	Yes	The compliance job ID to retrieve.

twitter_compliance_jobs_list

Returns a list of recent compliance jobs, filtered by type (tweets or users) and optionally by status.

Name	Type	Required	Description
type	string	Yes	Type of compliance jobs to retrieve: tweets or users.
status	string	No	Filter by job status: created, in_progress, failed, complete.

twitter_activity_subscription_create

Creates a subscription for an X activity event. Use when you need to monitor specific user activities like profile updates, follows, or Spaces events.

Name	Type	Required	Description
event_type	string	Yes	The activity event type to subscribe to.
user_id	string	No	The Twitter user ID to monitor for activity events.

twitter_openapi_spec_get

Fetches the OpenAPI specification (JSON) for Twitter’s API v2. Used to programmatically understand the API’s structure for developing client libraries or tools. Takes no parameters.