Twitter (X)

Connect to Twitter (X). Read and write tweets, manage users, follows, bookmarks, spaces, and more using the Twitter API v2.

Supports authentication: OAuth 2.0

Set up the agent connector

Register your Twitter (X) app credentials with Scalekit so it can manage the OAuth 2.0 (PKCE) 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 developer project and app

   • Go to the Twitter Developer Portal and sign in with your Twitter account.

     

   • Click + Create Project, give your project a meaningful name, select a use case, and add a description.

   • Create an app within the project. Give your app a name (e.g., Scalekit-Agent).

     

2. Configure user authentication settings

   • Inside your app, go to User authentication settings and click Set up.

   • Configure the following:

     • App permissions — select Read and write (or Read if your agent only reads data)
     • Type of App — select Web App, Automated App or Bot
     • Website URL — enter your application’s homepage URL

3. Get the redirect URI from Scalekit

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

     

   • Copy the Redirect URI from the connection configuration panel. It looks like https://<SCALEKIT_ENVIRONMENT_URL>/sso/v1/oauth/<CONNECTION_ID>/callback.

     

4. Add the callback URL in Twitter

   • Back in the Twitter Developer Portal, inside User authentication settings, paste the Scalekit Redirect URI into the Callback URI / Redirect URL field.

   • Click Save to apply the authentication settings.

     

   Redirect URI must match exactly

   Twitter performs an exact string match on the redirect URI. Any mismatch — including a trailing slash — will cause the OAuth flow to fail with an invalid_redirect_uri error.

5. Copy your client credentials

   • In the Twitter Developer Portal, go to Keys and tokens for your app.

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

   • Copy the Client ID and Client Secret immediately. The secret will not be shown again.

     

6. Add credentials in Scalekit

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

   • Enter your credentials:

     • Client ID — the Client ID from your Twitter app

     • Client Secret — the secret you generated in step 5

     • Scopes — select the scopes your agent needs. Common scopes:

       Scope	What it grants
       tweet.read	Read tweets and timelines
       tweet.write	Post, delete, and manage tweets
       users.read	Read user profile information
       follows.read	Read following and follower 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
       offline.access	Obtain refresh tokens for long-lived access

   • Click Save.

   Request only the scopes you need

   Twitter displays a consent screen listing every requested scope. Requesting unnecessary scopes reduces user trust and may cause authorization to be denied.

Usage

Connect a user’s Twitter (X) account and make API calls on their behalf — Scalekit handles OAuth 2.0 (PKCE), token storage, and refresh automatically.

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

Proxy API calls

Node.js

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

const connectionName = 'twitter'; // get your connection name from connection configurations
const identifier = 'user_123';    // your unique user identifier

// Get your 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;

// Authenticate the user — send this link to your user
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));

// Fetch the authenticated user's Twitter profile via Scalekit proxy
const user = await actions.request({
  connectionName,
  identifier,
  path: '/2/users/me',
  method: 'GET',
});
console.log(user);

Python

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

connection_name = "twitter"  # get your connection name from connection configurations
identifier = "user_123"      # your unique user identifier

# Get your 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

# Authenticate the user — present this link to your user
link_response = actions.get_authorization_link(
    connection_name=connection_name,
    identifier=identifier
)
print("Authorize Twitter:", link_response.link)
input("Press Enter after authorizing...")

# Fetch the authenticated user's Twitter profile via Scalekit proxy
user = actions.request(
    connection_name=connection_name,
    identifier=identifier,
    path="/2/users/me",
    method="GET"
)
print(user)

Scalekit tools

Tool list

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_types	array<string>	Yes	List of event types to subscribe to, e.g. profile.updated, follows, spaces
user_id	string	Yes	Twitter user ID to subscribe to activities for

twitter_blocked_users_get

Retrieves the authenticated user’s block list. The id parameter must be the authenticated user’s ID. Use Get Authenticated User action first to obtain your user ID.

Name	Type	Required	Description
expansions	string	No	Comma-separated expansions
id	string	Yes	Authenticated user’s Twitter ID — must match the authenticated user
max_results	integer	No	Max results per page (1-1000)
pagination_token	string	No	Pagination token for next page
user_fields	string	No	Comma-separated user fields

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.

Name	Type	Required	Description
id	string	Yes	Authenticated user’s Twitter ID
tweet_id	string	Yes	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.

Name	Type	Required	Description
id	string	Yes	Authenticated user’s Twitter ID
tweet_id	string	Yes	ID of the bookmarked tweet to remove

twitter_bookmarks_get

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

Name	Type	Required	Description
expansions	string	No	Comma-separated expansions
id	string	Yes	Authenticated user’s Twitter ID
max_results	integer	No	Max results per page (1-100)
pagination_token	string	No	Pagination token for next page
tweet_fields	string	No	Comma-separated tweet fields

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
resumable	boolean	No	Whether the job should be resumable
type	string	Yes	Type of compliance job

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	Compliance job ID

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
status	string	No	Filter by job status
type	string	Yes	Type of compliance jobs to list

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.

Name	Type	Required	Description
dm_event_fields	string	No	Comma-separated DM event fields
event_types	string	No	Filter by event types
expansions	string	No	Comma-separated expansions
max_results	integer	No	Max results per page (1-100)
pagination_token	string	No	Pagination token for next page
participant_id	string	Yes	User ID of the DM conversation participant

twitter_dm_conversation_retrieve

Retrieves Direct Message (DM) events for a specific conversation ID on Twitter. Useful for analyzing messages and participant activities.

Name	Type	Required	Description
dm_conversation_id	string	Yes	DM conversation ID
dm_event_fields	string	No	Comma-separated DM event fields
expansions	string	No	Comma-separated expansions
max_results	integer	No	Max results per page (1-100)
pagination_token	string	No	Pagination token for next page

twitter_dm_conversation_send

Sends a message with optional text and/or media attachments (using pre-uploaded media_ids) to a specified Twitter Direct Message conversation.

Name	Type	Required	Description
dm_conversation_id	string	Yes	DM conversation ID to send the message to
media_id	string	No	Pre-uploaded media ID to attach
text	string	No	Message text

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.

Name	Type	Required	Description
event_id	string	Yes	ID of the DM event to delete
participant_id	string	Yes	User ID of the DM conversation participant

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.

Name	Type	Required	Description
dm_event_fields	string	No	Comma-separated DM event fields
event_id	string	Yes	DM event ID
expansions	string	No	Comma-separated expansions

twitter_dm_events_get

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

Name	Type	Required	Description
dm_event_fields	string	No	Comma-separated DM event fields
event_types	string	No	Filter by event types
expansions	string	No	Comma-separated expansions
max_results	integer	No	Max results per page (1-100)
pagination_token	string	No	Pagination token for next page

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.

Name	Type	Required	Description
message_media_ids	array<string>	No	Media IDs to attach to initial message
message_text	string	Yes	Initial message text
participant_ids	array<string>	Yes	List of Twitter user IDs to include

twitter_dm_send

Sends a new Direct Message with text and/or media (media_id for attachments must be pre-uploaded) to a specified Twitter user. Creates a new DM and does not modify existing messages.

Name	Type	Required	Description
media_id	string	No	Pre-uploaded media ID to attach
participant_id	string	Yes	Twitter user ID of the DM recipient
text	string	No	Message text

twitter_followers_get

Retrieves a list of users who follow a specified public Twitter user ID.

Name	Type	Required	Description
expansions	string	No	Comma-separated expansions
id	string	Yes	Twitter user ID to get followers for
max_results	integer	No	Max results per page (1-1000)
pagination_token	string	No	Pagination token for next page
user_fields	string	No	Comma-separated user fields

twitter_following_get

Retrieves users followed by a specific Twitter user, allowing pagination and customization of returned user and tweet data fields via expansions.

Name	Type	Required	Description
expansions	string	No	Comma-separated expansions
id	string	Yes	Twitter user ID
max_results	integer	No	Max results per page (1-1000)
pagination_token	string	No	Pagination token for next page
user_fields	string	No	Comma-separated user fields

twitter_full_archive_search

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
end_time	string	No	ISO 8601 end time
expansions	string	No	Comma-separated expansions
max_results	integer	No	Max results per page (10-500)
next_token	string	No	Next page token
query	string	Yes	Search query using X search syntax
since_id	string	No	Minimum tweet ID
start_time	string	No	ISO 8601 start time e.g. 2021-01-01T00:00:00Z
tweet_fields	string	No	Comma-separated tweet fields
until_id	string	No	Maximum tweet ID
user_fields	string	No	Comma-separated user fields

twitter_full_archive_search_counts

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
end_time	string	No	ISO 8601 end time
granularity	string	No	Aggregation granularity
next_token	string	No	Next page token
query	string	Yes	Search query
since_id	string	No	Minimum tweet ID
start_time	string	No	ISO 8601 start time
until_id	string	No	Maximum tweet ID

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.

Name	Type	Required	Description
description	string	No	Description of the list
name	string	Yes	Unique name for the new list
private	boolean	No	Whether the list should be private

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.

Name	Type	Required	Description
list_id	string	Yes	ID of the Twitter List to delete

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.

Name	Type	Required	Description
id	string	Yes	Authenticated user’s Twitter ID
list_id	string	Yes	ID of the list to follow

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.

Name	Type	Required	Description
expansions	string	No	Comma-separated expansions
id	string	Yes	Twitter List ID
max_results	integer	No	Max results per page (1-100)
pagination_token	string	No	Pagination token for next page
user_fields	string	No	Comma-separated user fields

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.

Name	Type	Required	Description
expansions	string	No	Comma-separated expansions
id	string	Yes	Twitter List ID
list_fields	string	No	Comma-separated list fields
user_fields	string	No	Comma-separated user fields

twitter_list_member_add

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

Name	Type	Required	Description
list_id	string	Yes	ID of the Twitter List
user_id	string	Yes	ID of the user to add

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. The updated list of members is not returned.

Name	Type	Required	Description
id	string	Yes	Twitter List ID
user_id	string	Yes	ID of the user to remove from the list

twitter_list_members_get

Fetches members of a specific Twitter List, identified by its unique ID.

Name	Type	Required	Description
expansions	string	No	Comma-separated expansions
id	string	Yes	Twitter List ID
max_results	integer	No	Max results per page (1-100)
pagination_token	string	No	Pagination token for next page
user_fields	string	No	Comma-separated user fields

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.

Name	Type	Required	Description
id	string	Yes	Authenticated user’s Twitter ID
list_id	string	Yes	ID of the list to pin

twitter_list_timeline_get

Fetches the most recent Tweets posted by members of a specified Twitter List.

Name	Type	Required	Description
expansions	string	No	Comma-separated expansions
id	string	Yes	Twitter List ID
max_results	integer	No	Max results per page (1-100)
pagination_token	string	No	Pagination token for next page
tweet_fields	string	No	Comma-separated tweet fields
user_fields	string	No	Comma-separated user fields

twitter_list_unfollow

Enables a user to unfollow a specific Twitter List, which removes its tweets from their timeline and stops related notifications. Reports following: false on success, even if the user was not initially following the list.

Name	Type	Required	Description
id	string	Yes	Authenticated user’s Twitter ID
list_id	string	Yes	ID of the list to unfollow

twitter_list_unpin

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

Name	Type	Required	Description
id	string	Yes	Authenticated user’s Twitter ID
list_id	string	Yes	ID of the list to unpin

twitter_list_update

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

Name	Type	Required	Description
description	string	No	New description
id	string	Yes	Twitter List ID to update
name	string	No	New name for the list
private	boolean	No	Set to true to make private, false for public

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	Base64-encoded image data
media_category	string	No	Media category for use context
media_type	string	Yes	MIME type, e.g. image/jpeg or image/png

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_data	string	Yes	Base64-encoded chunk data
media_id	string	Yes	Media ID from the INIT step
segment_index	integer	Yes	Zero-based index of the chunk segment

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_category	string	No	Media category for use context
media_data	string	Yes	Base64-encoded media data
media_type	string	Yes	MIME type, e.g. image/jpeg

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
additional_owners	string	No	Comma-separated user IDs to also own the media
media_category	string	No	Media category for use context
media_type	string	Yes	MIME type, e.g. video/mp4 or image/gif
total_bytes	integer	Yes	Total size of the media file in bytes

twitter_media_upload_large

Uploads media files to X/Twitter. Automatically uses chunked upload for GIFs, videos, and images larger than 5 MB. Use for videos, GIFs, or any file larger than 5 MB.

Name	Type	Required	Description
additional_owners	string	No	Comma-separated user IDs to also own the media
media_category	string	No	Media category for use context
media_data	string	Yes	Base64-encoded media file data
media_type	string	Yes	MIME type, e.g. video/mp4 or image/gif
total_bytes	integer	Yes	Total size of the file in bytes

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	Media ID from the upload INIT step

twitter_muted_users_get

Returns user objects muted by the X user identified by the id path parameter.

Name	Type	Required	Description
expansions	string	No	Comma-separated expansions
id	string	Yes	Twitter user ID
max_results	integer	No	Max results per page (1-1000)
pagination_token	string	No	Pagination token for next page
user_fields	string	No	Comma-separated user fields

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.

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
end_time	string	Yes	ISO 8601 end time
start_time	string	Yes	ISO 8601 start time
tweet_ids	string	Yes	Comma-separated list of Tweet IDs

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
geo_place_id	string	No	Place ID for geo tag
media_media_ids	array<string>	No	Media IDs to attach
poll_duration_minutes	integer	No	Duration of poll in minutes
poll_options	array<string>	No	Up to 4 poll options
quote_tweet_id	string	No	ID of the tweet to quote
reply_in_reply_to_tweet_id	string	No	ID of the tweet to reply to
text	string	No	Text content of the tweet

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	ID of the Tweet to delete

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
id	string	Yes	Authenticated user’s Twitter ID
tweet_id	string	Yes	ID of the Tweet to like

twitter_post_likers_get

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

Name	Type	Required	Description
expansions	string	No	Comma-separated expansions
id	string	Yes	Tweet ID
max_results	integer	No	Max results per page (1-100)
pagination_token	string	No	Pagination token for next page
user_fields	string	No	Comma-separated user fields

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
expansions	string	No	Comma-separated expansions
id	string	Yes	Tweet ID
media_fields	string	No	Comma-separated media fields
tweet_fields	string	No	Comma-separated tweet fields
user_fields	string	No	Comma-separated user fields

twitter_post_quotes_get

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

Name	Type	Required	Description
expansions	string	No	Comma-separated expansions
id	string	Yes	Tweet ID
max_results	integer	No	Max results per page (1-100)
pagination_token	string	No	Pagination token for next page
tweet_fields	string	No	Comma-separated tweet fields

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
id	string	Yes	Authenticated user’s Twitter ID
tweet_id	string	Yes	ID of the Tweet to retweet

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
expansions	string	No	Comma-separated expansions
id	string	Yes	Tweet ID
max_results	integer	No	Max results per page (1-100)
pagination_token	string	No	Pagination token for next page
user_fields	string	No	Comma-separated user fields

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
expansions	string	No	Comma-separated expansions
id	string	Yes	Tweet ID
max_results	integer	No	Max results per page (1-100)
pagination_token	string	No	Pagination token for next page
tweet_fields	string	No	Comma-separated tweet fields

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
id	string	Yes	Authenticated user’s Twitter ID
tweet_id	string	Yes	ID of the Tweet to unlike

twitter_post_unretweet

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

Name	Type	Required	Description
id	string	Yes	Authenticated user’s Twitter ID
source_tweet_id	string	Yes	ID of the Tweet to unretweet

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
expansions	string	No	Comma-separated expansions
ids	string	Yes	Comma-separated list of Tweet IDs (up to 100)
media_fields	string	No	Comma-separated media fields
tweet_fields	string	No	Comma-separated tweet fields
user_fields	string	No	Comma-separated user fields

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). Note: impression_count returns 0 for other users’ tweets — use retweet_count, like_count, or quote_count for engagement filtering instead.

Name	Type	Required	Description
end_time	string	No	ISO 8601 end time
expansions	string	No	Comma-separated expansions
max_results	integer	No	Max results per page (10-100)
media_fields	string	No	Comma-separated media fields
next_token	string	No	Next page token
query	string	Yes	Search query using X search syntax, e.g. from:username -is:retweet
since_id	string	No	Minimum tweet ID
start_time	string	No	ISO 8601 start time
tweet_fields	string	No	Comma-separated tweet fields
until_id	string	No	Maximum tweet ID
user_fields	string	No	Comma-separated user fields

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
end_time	string	No	ISO 8601 end time
granularity	string	No	Aggregation granularity
query	string	Yes	Search query
since_id	string	No	Minimum tweet ID
start_time	string	No	ISO 8601 start time
until_id	string	No	Maximum tweet ID

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
hidden	boolean	Yes	true to hide, false to unhide
tweet_id	string	Yes	ID of the reply tweet to hide or unhide

twitter_space_get

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

Name	Type	Required	Description
expansions	string	No	Comma-separated expansions
id	string	Yes	Twitter Space ID
space_fields	string	No	Comma-separated space fields
user_fields	string	No	Comma-separated user fields

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
expansions	string	No	Comma-separated expansions
id	string	Yes	Twitter Space ID
max_results	integer	No	Max results per page (1-100)
tweet_fields	string	No	Comma-separated tweet fields

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
expansions	string	No	Comma-separated expansions
id	string	Yes	Twitter Space ID
user_fields	string	No	Comma-separated user fields

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
expansions	string	No	Comma-separated expansions
space_fields	string	No	Comma-separated space fields
user_fields	string	No	Comma-separated user fields
user_ids	string	Yes	Comma-separated list of user IDs to get spaces for

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
expansions	string	No	Comma-separated expansions
ids	string	Yes	Comma-separated list of Space IDs
space_fields	string	No	Comma-separated space fields
user_fields	string	No	Comma-separated user fields

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
expansions	string	No	Comma-separated expansions
max_results	integer	No	Max results per page (1-100)
query	string	Yes	Text to search for in Space titles
space_fields	string	No	Comma-separated space fields
state	string	No	Filter by space state

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. 403 errors indicate missing Enterprise access or wrong auth type.

Name	Type	Required	Description
backfill_minutes	integer	No	Minutes of backfill to stream on reconnect (0-5)
expansions	string	No	Comma-separated expansions
tweet_fields	string	No	Comma-separated tweet fields

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 to retrieve usage data for, default 7
usage_fields	string	No	Comma-separated usage fields to include

twitter_user_follow

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

Name	Type	Required	Description
id	string	Yes	Authenticated user’s Twitter ID
target_user_id	string	Yes	ID of the user to follow

twitter_user_followed_lists_get

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

Name	Type	Required	Description
expansions	string	No	Comma-separated expansions
id	string	Yes	Twitter user ID
list_fields	string	No	Comma-separated list fields
max_results	integer	No	Max results per page (1-100)
pagination_token	string	No	Pagination token for next page
user_fields	string	No	Comma-separated user fields

twitter_user_liked_tweets_get

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

Name	Type	Required	Description
expansions	string	No	Comma-separated expansions
id	string	Yes	Twitter user ID
max_results	integer	No	Max results per page (5-100)
pagination_token	string	No	Pagination token for next page
tweet_fields	string	No	Comma-separated tweet fields
user_fields	string	No	Comma-separated user fields

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.

Name	Type	Required	Description
expansions	string	No	Comma-separated expansions
id	string	Yes	Twitter user ID
list_fields	string	No	Comma-separated list fields
max_results	integer	No	Max results per page (1-100)
pagination_token	string	No	Pagination token for next page
user_fields	string	No	Comma-separated user fields

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
expansions	string	No	Comma-separated expansions
id	string	Yes	Twitter user ID
tweet_fields	string	No	Comma-separated tweet fields
user_fields	string	No	Comma-separated user fields

twitter_user_lookup_by_username

Fetches public profile information for a valid and existing Twitter user by their username. Optionally expands related data like pinned Tweets. Results may be limited for protected profiles not followed by the authenticated user.

Name	Type	Required	Description
expansions	string	No	Comma-separated expansions
tweet_fields	string	No	Comma-separated tweet fields
user_fields	string	No	Comma-separated user fields
username	string	Yes	Twitter username without the @ symbol, e.g. elonmusk

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
expansions	string	No	Comma-separated expansions
tweet_fields	string	No	Comma-separated tweet fields
user_fields	string	No	Comma-separated user fields to return, e.g. created_at,description,public_metrics

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.

Name	Type	Required	Description
id	string	Yes	Authenticated user’s Twitter ID
target_user_id	string	Yes	ID of the user to mute

twitter_user_owned_lists_get

Retrieves Lists created (owned) by a specific Twitter user, not Lists they follow or are subscribed to.

Name	Type	Required	Description
expansions	string	No	Comma-separated expansions
id	string	Yes	Twitter user ID
list_fields	string	No	Comma-separated list fields
max_results	integer	No	Max results per page (1-100)
pagination_token	string	No	Pagination token for next page
user_fields	string	No	Comma-separated user fields

twitter_user_pinned_lists_get

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

Name	Type	Required	Description
expansions	string	No	Comma-separated expansions
id	string	Yes	Twitter user ID
list_fields	string	No	Comma-separated list fields
user_fields	string	No	Comma-separated user fields

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. CRITICAL: The id parameter MUST be the authenticated user’s own numeric Twitter user ID. Use twitter_user_me to get your ID first. Cannot fetch another user’s home timeline.

Name	Type	Required	Description
exclude	string	No	Comma-separated types to exclude: retweets,replies
expansions	string	No	Comma-separated expansions
id	string	Yes	Authenticated user’s own numeric Twitter ID — must be your own ID
max_results	integer	No	Max results per page (1-100)
pagination_token	string	No	Pagination token for next page
tweet_fields	string	No	Comma-separated tweet fields
user_fields	string	No	Comma-separated user fields

twitter_user_unfollow

Allows the authenticated user to unfollow an existing Twitter user, which removes the follow relationship. The source user ID is automatically determined from the authenticated session.

Name	Type	Required	Description
id	string	Yes	Authenticated user’s Twitter ID
target_user_id	string	Yes	ID of the user to unfollow

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.

Name	Type	Required	Description
id	string	Yes	Authenticated user’s Twitter ID
target_user_id	string	Yes	ID of the user to unmute

twitter_users_lookup

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

Name	Type	Required	Description
expansions	string	No	Comma-separated expansions
ids	string	Yes	Comma-separated list of Twitter user IDs (up to 100)
tweet_fields	string	No	Comma-separated tweet fields
user_fields	string	No	Comma-separated user fields

twitter_users_lookup_by_username

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

Name	Type	Required	Description
expansions	string	No	Comma-separated expansions
tweet_fields	string	No	Comma-separated tweet fields
user_fields	string	No	Comma-separated user fields
usernames	string	Yes	Comma-separated list of Twitter usernames without @ symbols (up to 100)