Twitter / X connector

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Set up the connector

   Register your Twitter / X credentials with Scalekit so it can authenticate requests on your behalf. You do this once per environment.

   Dashboard setup steps

   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 AgentKit > Connections > 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 AgentKit > 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.

4. Make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'twitter'
   const identifier = 'user_123'
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'twitter_dm_events_get',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "twitter"
   identifier = "user_123"
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="twitter_dm_events_get",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Get media upload status, post likers, user followed lists — Gets the status of a media upload for X/Twitter
• Lookup users, posts, user — Retrieves detailed information for specified X (formerly Twitter) user IDs
• Unmute user — Unmutes a target user for the authenticated user, allowing them to see Tweets and notifications from the target user again
• List delete, member remove, follow — Permanently deletes a specified Twitter List using its ID
• Search full archive, recent — Searches the full archive of public Tweets from March 2006 onwards
• Upload media — Uploads media (images only) to X/Twitter using the v2 API

Common workflows

Proxy API call

Node.js

const me = await actions.request({
  connectionName: 'twitter',
  identifier: 'user_123',
  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: 'twitter',
  identifier: 'user_123',
  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: 'twitter',
  identifier: 'user_123',
  path: '/2/tweets/search/recent',
  method: 'GET',
  params: { query: 'from:twitterdev', max_results: '10' },
});
console.log('Search results:', search);

Python

me = actions.request(
    connection_name='twitter',
    identifier='user_123',
    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='twitter',
    identifier='user_123',
    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='twitter',
    identifier='user_123',
    path="/2/tweets/search/recent",
    method="GET",
    params={"query": "from:twitterdev", "max_results": "10"}
)
print("Search results:", search)

Execute a tool

Node.js

const result = await actions.executeTool({
  connector: 'twitter',
  identifier: 'user_123',
  toolName: 'twitter_blocked_users_get',
  toolInput: {
    id: '<YOUR_USER_ID>', // use the id from /2/users/me
  },
});
console.log(result);

Python

result = actions.execute_tool(
    tool_name='twitter_blocked_users_get',
    tool_input={
        "id": "<YOUR_USER_ID>",  # use the id from /2/users/me
    },
    connection_name='twitter',
    identifier='user_123',
)
print(result)

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

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.2 params▾

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

NameTypeRequiredDescription

event_typesarrayrequiredList of event types to subscribe to, e.g. profile.updated, follows, spaces

user_idstringrequiredTwitter 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.5 params▾

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.

NameTypeRequiredDescription

idstringrequiredAuthenticated user's Twitter ID — must match the authenticated user

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (1-1000)

pagination_tokenstringoptionalPagination token for next page

user_fieldsstringoptionalComma-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.2 params▾

Adds a specified, existing, and accessible Tweet to a user's bookmarks. Success is indicated by the 'bookmarked' field in the response.

NameTypeRequiredDescription

idstringrequiredAuthenticated user's Twitter ID

tweet_idstringrequiredID 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.2 params▾

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.

NameTypeRequiredDescription

idstringrequiredAuthenticated user's Twitter ID

tweet_idstringrequiredID 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.5 params▾

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

NameTypeRequiredDescription

idstringrequiredAuthenticated user's Twitter ID

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (1-100)

pagination_tokenstringoptionalPagination token for next page

tweet_fieldsstringoptionalComma-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.2 params▾

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.

NameTypeRequiredDescription

typestringrequiredType of compliance job

resumablebooleanoptionalWhether the job should be resumable

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

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

NameTypeRequiredDescription

idstringrequiredCompliance job ID

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

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

NameTypeRequiredDescription

typestringrequiredType of compliance jobs to list

statusstringoptionalFilter by job status

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.6 params▾

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.

NameTypeRequiredDescription

participant_idstringrequiredUser ID of the DM conversation participant

dm_event_fieldsstringoptionalComma-separated DM event fields

event_typesstringoptionalFilter by event types

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (1-100)

pagination_tokenstringoptionalPagination token for next page

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

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

NameTypeRequiredDescription

dm_conversation_idstringrequiredDM conversation ID

dm_event_fieldsstringoptionalComma-separated DM event fields

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (1-100)

pagination_tokenstringoptionalPagination 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.3 params▾

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

NameTypeRequiredDescription

dm_conversation_idstringrequiredDM conversation ID to send the message to

media_idstringoptionalPre-uploaded media ID to attach

textstringoptionalMessage 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.2 params▾

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.

NameTypeRequiredDescription

event_idstringrequiredID of the DM event to delete

participant_idstringrequiredUser 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.3 params▾

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

NameTypeRequiredDescription

event_idstringrequiredDM event ID

dm_event_fieldsstringoptionalComma-separated DM event fields

expansionsstringoptionalComma-separated expansions

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

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

NameTypeRequiredDescription

dm_event_fieldsstringoptionalComma-separated DM event fields

event_typesstringoptionalFilter by event types

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (1-100)

pagination_tokenstringoptionalPagination 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.3 params▾

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.

NameTypeRequiredDescription

message_textstringrequiredInitial message text

participant_idsarrayrequiredList of Twitter user IDs to include

message_media_idsarrayoptionalMedia IDs to attach to initial message

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.3 params▾

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.

NameTypeRequiredDescription

participant_idstringrequiredTwitter user ID of the DM recipient

media_idstringoptionalPre-uploaded media ID to attach

textstringoptionalMessage text

twitter_followers_get#Retrieves a list of users who follow a specified public Twitter user ID.5 params▾

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

NameTypeRequiredDescription

idstringrequiredTwitter user ID to get followers for

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (1-1000)

pagination_tokenstringoptionalPagination token for next page

user_fieldsstringoptionalComma-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.5 params▾

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

NameTypeRequiredDescription

idstringrequiredTwitter user ID

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (1-1000)

pagination_tokenstringoptionalPagination token for next page

user_fieldsstringoptionalComma-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.10 params▾

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.

NameTypeRequiredDescription

querystringrequiredSearch query using X search syntax

end_timestringoptionalISO 8601 end time

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (10-500)

next_tokenstringoptionalNext page token

since_idstringoptionalMinimum tweet ID

start_timestringoptionalISO 8601 start time e.g. 2021-01-01T00:00:00Z

tweet_fieldsstringoptionalComma-separated tweet fields

until_idstringoptionalMaximum tweet ID

user_fieldsstringoptionalComma-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.7 params▾

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.

NameTypeRequiredDescription

querystringrequiredSearch query

end_timestringoptionalISO 8601 end time

granularitystringoptionalAggregation granularity

next_tokenstringoptionalNext page token

since_idstringoptionalMinimum tweet ID

start_timestringoptionalISO 8601 start time

until_idstringoptionalMaximum 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.3 params▾

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

NameTypeRequiredDescription

namestringrequiredUnique name for the new list

descriptionstringoptionalDescription of the list

privatebooleanoptionalWhether 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.1 param▾

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

NameTypeRequiredDescription

list_idstringrequiredID 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.2 params▾

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.

NameTypeRequiredDescription

idstringrequiredAuthenticated user's Twitter ID

list_idstringrequiredID 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.5 params▾

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.

NameTypeRequiredDescription

idstringrequiredTwitter List ID

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (1-100)

pagination_tokenstringoptionalPagination token for next page

user_fieldsstringoptionalComma-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.4 params▾

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.

NameTypeRequiredDescription

idstringrequiredTwitter List ID

expansionsstringoptionalComma-separated expansions

list_fieldsstringoptionalComma-separated list fields

user_fieldsstringoptionalComma-separated user fields

twitter_list_member_add#Adds a user to a specified Twitter List. The list must be owned by the authenticated user.2 params▾

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

NameTypeRequiredDescription

list_idstringrequiredID of the Twitter List

user_idstringrequiredID 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.2 params▾

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.

NameTypeRequiredDescription

idstringrequiredTwitter List ID

user_idstringrequiredID of the user to remove from the list

twitter_list_members_get#Fetches members of a specific Twitter List, identified by its unique ID.5 params▾

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

NameTypeRequiredDescription

idstringrequiredTwitter List ID

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (1-100)

pagination_tokenstringoptionalPagination token for next page

user_fieldsstringoptionalComma-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.2 params▾

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.

NameTypeRequiredDescription

idstringrequiredAuthenticated user's Twitter ID

list_idstringrequiredID of the list to pin

twitter_list_timeline_get#Fetches the most recent Tweets posted by members of a specified Twitter List.6 params▾

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

NameTypeRequiredDescription

idstringrequiredTwitter List ID

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (1-100)

pagination_tokenstringoptionalPagination token for next page

tweet_fieldsstringoptionalComma-separated tweet fields

user_fieldsstringoptionalComma-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.2 params▾

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.

NameTypeRequiredDescription

idstringrequiredAuthenticated user's Twitter ID

list_idstringrequiredID 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.2 params▾

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

NameTypeRequiredDescription

idstringrequiredAuthenticated user's Twitter ID

list_idstringrequiredID 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.4 params▾

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

NameTypeRequiredDescription

idstringrequiredTwitter List ID to update

descriptionstringoptionalNew description

namestringoptionalNew name for the list

privatebooleanoptionalSet 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.3 params▾

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.

NameTypeRequiredDescription

mediastringrequiredBase64-encoded image data

media_typestringrequiredMIME type, e.g. image/jpeg or image/png

media_categorystringoptionalMedia category for use context

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.3 params▾

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.

NameTypeRequiredDescription

media_datastringrequiredBase64-encoded chunk data

media_idstringrequiredMedia ID from the INIT step

segment_indexintegerrequiredZero-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.3 params▾

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.

NameTypeRequiredDescription

media_datastringrequiredBase64-encoded media data

media_typestringrequiredMIME type, e.g. image/jpeg

media_categorystringoptionalMedia category for use context

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.4 params▾

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.

NameTypeRequiredDescription

media_typestringrequiredMIME type, e.g. video/mp4 or image/gif

total_bytesintegerrequiredTotal size of the media file in bytes

additional_ownersstringoptionalComma-separated user IDs to also own the media

media_categorystringoptionalMedia category for use context

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.5 params▾

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.

NameTypeRequiredDescription

media_datastringrequiredBase64-encoded media file data

media_typestringrequiredMIME type, e.g. video/mp4 or image/gif

total_bytesintegerrequiredTotal size of the file in bytes

additional_ownersstringoptionalComma-separated user IDs to also own the media

media_categorystringoptionalMedia category for use context

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.1 param▾

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.

NameTypeRequiredDescription

media_idstringrequiredMedia ID from the upload INIT step

twitter_muted_users_get#Returns user objects muted by the X user identified by the id path parameter.5 params▾

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

NameTypeRequiredDescription

idstringrequiredTwitter user ID

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (1-1000)

pagination_tokenstringoptionalPagination token for next page

user_fieldsstringoptionalComma-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.0 params▾

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.3 params▾

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.

NameTypeRequiredDescription

end_timestringrequiredISO 8601 end time

start_timestringrequiredISO 8601 start time

tweet_idsstringrequiredComma-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.7 params▾

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.

NameTypeRequiredDescription

geo_place_idstringoptionalPlace ID for geo tag

media_media_idsarrayoptionalMedia IDs to attach

poll_duration_minutesintegeroptionalDuration of poll in minutes

poll_optionsarrayoptionalUp to 4 poll options

quote_tweet_idstringoptionalID of the tweet to quote

reply_in_reply_to_tweet_idstringoptionalID of the tweet to reply to

textstringoptionalText 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.1 param▾

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

NameTypeRequiredDescription

idstringrequiredID 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.2 params▾

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.

NameTypeRequiredDescription

idstringrequiredAuthenticated user's Twitter ID

tweet_idstringrequiredID of the Tweet to like

twitter_post_likers_get#Retrieves users who have liked the Post (Tweet) identified by the provided ID.5 params▾

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

NameTypeRequiredDescription

idstringrequiredTweet ID

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (1-100)

pagination_tokenstringoptionalPagination token for next page

user_fieldsstringoptionalComma-separated user fields

twitter_post_lookup#Fetches comprehensive details for a single Tweet by its unique ID, provided the Tweet exists and is accessible.5 params▾

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

NameTypeRequiredDescription

idstringrequiredTweet ID

expansionsstringoptionalComma-separated expansions

media_fieldsstringoptionalComma-separated media fields

tweet_fieldsstringoptionalComma-separated tweet fields

user_fieldsstringoptionalComma-separated user fields

twitter_post_quotes_get#Retrieves Tweets that quote a specified Tweet. Requires a valid Tweet ID.5 params▾

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

NameTypeRequiredDescription

idstringrequiredTweet ID

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (1-100)

pagination_tokenstringoptionalPagination token for next page

tweet_fieldsstringoptionalComma-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.2 params▾

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.

NameTypeRequiredDescription

idstringrequiredAuthenticated user's Twitter ID

tweet_idstringrequiredID 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.5 params▾

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

NameTypeRequiredDescription

idstringrequiredTweet ID

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (1-100)

pagination_tokenstringoptionalPagination token for next page

user_fieldsstringoptionalComma-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.5 params▾

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

NameTypeRequiredDescription

idstringrequiredTweet ID

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (1-100)

pagination_tokenstringoptionalPagination token for next page

tweet_fieldsstringoptionalComma-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.2 params▾

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.

NameTypeRequiredDescription

idstringrequiredAuthenticated user's Twitter ID

tweet_idstringrequiredID of the Tweet to unlike

twitter_post_unretweet#Removes a user's retweet of a specified Post, if the user had previously retweeted it.2 params▾

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

NameTypeRequiredDescription

idstringrequiredAuthenticated user's Twitter ID

source_tweet_idstringrequiredID 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.5 params▾

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

NameTypeRequiredDescription

idsstringrequiredComma-separated list of Tweet IDs (up to 100)

expansionsstringoptionalComma-separated expansions

media_fieldsstringoptionalComma-separated media fields

tweet_fieldsstringoptionalComma-separated tweet fields

user_fieldsstringoptionalComma-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.11 params▾

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.

NameTypeRequiredDescription

querystringrequiredSearch query using X search syntax, e.g. from:username -is:retweet

end_timestringoptionalISO 8601 end time

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (10-100)

media_fieldsstringoptionalComma-separated media fields

next_tokenstringoptionalNext page token

since_idstringoptionalMinimum tweet ID

start_timestringoptionalISO 8601 start time

tweet_fieldsstringoptionalComma-separated tweet fields

until_idstringoptionalMaximum tweet ID

user_fieldsstringoptionalComma-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'.6 params▾

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

NameTypeRequiredDescription

querystringrequiredSearch query

end_timestringoptionalISO 8601 end time

granularitystringoptionalAggregation granularity

since_idstringoptionalMinimum tweet ID

start_timestringoptionalISO 8601 start time

until_idstringoptionalMaximum 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.2 params▾

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.

NameTypeRequiredDescription

hiddenbooleanrequiredtrue to hide, false to unhide

tweet_idstringrequiredID 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.4 params▾

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

NameTypeRequiredDescription

idstringrequiredTwitter Space ID

expansionsstringoptionalComma-separated expansions

space_fieldsstringoptionalComma-separated space fields

user_fieldsstringoptionalComma-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.4 params▾

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.

NameTypeRequiredDescription

idstringrequiredTwitter Space ID

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (1-100)

tweet_fieldsstringoptionalComma-separated tweet fields

twitter_space_ticket_buyers_get#Retrieves a list of users who purchased tickets for a specific, valid, and ticketed Twitter Space.3 params▾

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

NameTypeRequiredDescription

idstringrequiredTwitter Space ID

expansionsstringoptionalComma-separated expansions

user_fieldsstringoptionalComma-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.4 params▾

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

NameTypeRequiredDescription

user_idsstringrequiredComma-separated list of user IDs to get spaces for

expansionsstringoptionalComma-separated expansions

space_fieldsstringoptionalComma-separated space fields

user_fieldsstringoptionalComma-separated user fields

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.4 params▾

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.

NameTypeRequiredDescription

idsstringrequiredComma-separated list of Space IDs

expansionsstringoptionalComma-separated expansions

space_fieldsstringoptionalComma-separated space fields

user_fieldsstringoptionalComma-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.5 params▾

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

NameTypeRequiredDescription

querystringrequiredText to search for in Space titles

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (1-100)

space_fieldsstringoptionalComma-separated space fields

statestringoptionalFilter 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.3 params▾

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.

NameTypeRequiredDescription

backfill_minutesintegeroptionalMinutes of backfill to stream on reconnect (0-5)

expansionsstringoptionalComma-separated expansions

tweet_fieldsstringoptionalComma-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.2 params▾

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.

NameTypeRequiredDescription

daysintegeroptionalNumber of days to retrieve usage data for, default 7

usage_fieldsstringoptionalComma-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.2 params▾

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

NameTypeRequiredDescription

idstringrequiredAuthenticated user's Twitter ID

target_user_idstringrequiredID 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.6 params▾

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

NameTypeRequiredDescription

idstringrequiredTwitter user ID

expansionsstringoptionalComma-separated expansions

list_fieldsstringoptionalComma-separated list fields

max_resultsintegeroptionalMax results per page (1-100)

pagination_tokenstringoptionalPagination token for next page

user_fieldsstringoptionalComma-separated user fields

twitter_user_liked_tweets_get#Retrieves Tweets liked by a specified Twitter user, provided their liked tweets are public or accessible.6 params▾

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

NameTypeRequiredDescription

idstringrequiredTwitter user ID

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (5-100)

pagination_tokenstringoptionalPagination token for next page

tweet_fieldsstringoptionalComma-separated tweet fields

user_fieldsstringoptionalComma-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.6 params▾

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

NameTypeRequiredDescription

idstringrequiredTwitter user ID

expansionsstringoptionalComma-separated expansions

list_fieldsstringoptionalComma-separated list fields

max_resultsintegeroptionalMax results per page (1-100)

pagination_tokenstringoptionalPagination token for next page

user_fieldsstringoptionalComma-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.4 params▾

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.

NameTypeRequiredDescription

idstringrequiredTwitter user ID

expansionsstringoptionalComma-separated expansions

tweet_fieldsstringoptionalComma-separated tweet fields

user_fieldsstringoptionalComma-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.4 params▾

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.

NameTypeRequiredDescription

usernamestringrequiredTwitter username without the @ symbol, e.g. elonmusk

expansionsstringoptionalComma-separated expansions

tweet_fieldsstringoptionalComma-separated tweet fields

user_fieldsstringoptionalComma-separated user fields

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.3 params▾

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

NameTypeRequiredDescription

expansionsstringoptionalComma-separated expansions

tweet_fieldsstringoptionalComma-separated tweet fields

user_fieldsstringoptionalComma-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.2 params▾

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.

NameTypeRequiredDescription

idstringrequiredAuthenticated user's Twitter ID

target_user_idstringrequiredID 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.6 params▾

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

NameTypeRequiredDescription

idstringrequiredTwitter user ID

expansionsstringoptionalComma-separated expansions

list_fieldsstringoptionalComma-separated list fields

max_resultsintegeroptionalMax results per page (1-100)

pagination_tokenstringoptionalPagination token for next page

user_fieldsstringoptionalComma-separated user fields

twitter_user_pinned_lists_get#Retrieves the Lists a specific, existing Twitter user has pinned to their profile to highlight them.4 params▾

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

NameTypeRequiredDescription

idstringrequiredTwitter user ID

expansionsstringoptionalComma-separated expansions

list_fieldsstringoptionalComma-separated list fields

user_fieldsstringoptionalComma-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.7 params▾

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.

NameTypeRequiredDescription

idstringrequiredAuthenticated user's own numeric Twitter ID — must be your own ID

excludestringoptionalComma-separated types to exclude: retweets,replies

expansionsstringoptionalComma-separated expansions

max_resultsintegeroptionalMax results per page (1-100)

pagination_tokenstringoptionalPagination token for next page

tweet_fieldsstringoptionalComma-separated tweet fields

user_fieldsstringoptionalComma-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.2 params▾

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.

NameTypeRequiredDescription

idstringrequiredAuthenticated user's Twitter ID

target_user_idstringrequiredID 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.2 params▾

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.

NameTypeRequiredDescription

idstringrequiredAuthenticated user's Twitter ID

target_user_idstringrequiredID 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.4 params▾

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

NameTypeRequiredDescription

idsstringrequiredComma-separated list of Twitter user IDs (up to 100)

expansionsstringoptionalComma-separated expansions

tweet_fieldsstringoptionalComma-separated tweet fields

user_fieldsstringoptionalComma-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.4 params▾

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.

NameTypeRequiredDescription

usernamesstringrequiredComma-separated list of Twitter usernames without @ symbols (up to 100)

expansionsstringoptionalComma-separated expansions

tweet_fieldsstringoptionalComma-separated tweet fields

user_fieldsstringoptionalComma-separated user fields