Twitter, Inc. was an American social media company based in San Francisco, California, which operated and was named for named for its flagship social media network prior to its rebrand as X.
Twitter, Inc. was an American social media company based in San Francisco, California, which operated and was named for named for its flagship social media network prior to its rebrand as X. On Nagent, Twitter is exposed as a fully-configurable social media accounts integration that any agent can call — 79 actions, and OAuth authentication. No code is required to wire Twitter into your workflow — connect it once via the External Integrations panel and reuse it across every agent you build.
Agent builders use Twitter to automate the kinds of tasks social media accounts teams previously handled manually. Concrete examples — each one is a single agent step in Nagent — include:
Every action and trigger is paired with a structured input/output schema (visible in the sections below), so when you wire Twitter into Helix — our agentic agent builder — the editor knows exactly what each step expects and produces. Configure once, deploy anywhere across your Nagent agents.
Every operation an agent can call against Twitter, with input parameters and output schema. Drop these into any step of an agent built in Helix.
TWITTER_ADD_LIST_MEMBERAdds a user to a specified Twitter List; the list must be owned by the authenticated user.
Input parameters
The unique identifier of the Twitter List to which the user will be added.
Unique identifier of the User to add to the list. If you have a username, convert it to a `user_id` first (e.g., via GET /2/users/by/username/{username}).
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_ADD_POST_TO_BOOKMARKSAdds a specified, existing, and accessible Tweet to a user's bookmarks, with success indicated by the 'bookmarked' field in the response.
Input parameters
The user ID of the authenticated user making the request. This ID is used as a path parameter to specify whose bookmark collection the Tweet will be added to.
Unique identifier (string) of the Tweet to be bookmarked, provided in the request body. String type used to support large integer values.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_APPEND_MEDIA_UPLOADAppend data chunk to an ongoing media upload session on X/Twitter. Use this action during chunked media uploads to append each segment of media data in sequence.
Input parameters
The media identifier for the media to perform the append operation.
Base64-encoded media data chunk to append. This should be a segment of the media file being uploaded in the chunked upload process.
Zero-based index of the media segment being appended. Start with 0 for the first chunk and increment by 1 for each subsequent chunk.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_BOOKMARKS_BY_USERRetrieves Tweets bookmarked by the authenticated user, where the provided User ID must match the authenticated user's ID.
Input parameters
Defaults to 'me' (recommended). Retrieves bookmarks for the currently authenticated user. You can ONLY retrieve YOUR OWN bookmarks. Passing any other user's ID will fail with a 400 error.
A list of objects to expand and include in the response, providing more detailed information about entities like authors, media, or referenced Tweets. Refer to the `ExpansionsEnm0` enum for available expansion options.
The maximum number of bookmarked Tweets to return per page, between 1 and 100 inclusive.
A list of specific Poll object fields to include when `attachments.poll_ids` is part of `expansions`. Refer to the `PollFieldsEnm0` enum for available field options.
A list of specific User object fields to include for user objects (e.g., authors) when requested via `expansions`. Refer to the `UserFieldsEnm0` enum for available field options.
A list of specific Media object fields to include when `attachments.media_keys` is part of `expansions`. Refer to the `MediaFieldsEnm0` enum for available field options.
A list of specific Place object fields to include when `geo.place_id` is part of `expansions`. Refer to the `PlaceFieldsEnm0` enum for available field options.
A list of specific Tweet fields to include in the response for each bookmarked Tweet. Omitting this parameter will result in a default set of fields being returned. Refer to the `TweetFieldsEnm0` enum for available field options.
Pagination token MUST be obtained from `meta.next_token` or `meta.previous_token` of a prior BookmarksByUser response. CRITICAL: Do NOT construct, modify, or guess token values - Twitter tokens are cryptographically signed and ANY user-generated or modified value will fail with HTTP 400. Valid tokens are opaque alphanumeric strings (typically 40+ characters). Omit this parameter entirely to fetch the first page of results.
Internal field for execution messages. Do not set manually.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_CREATE_ACTIVITY_SUBSCRIPTIONTool to create a subscription for an X activity event. Use when you need to monitor specific user activities like profile updates, follows, or spaces events.
Input parameters
Optional tag to label this subscription (1-200 characters).
Filter criteria specifying which events to receive. Must include at least one of 'user_id' or 'keyword'.
The type of activity event to subscribe to. Examples: 'profile.update.bio', 'follow.follow', 'spaces.start'.
The unique identifier of this webhook config.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_CREATE_COMPLIANCE_JOBCreates 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.
Input parameters
Optional. A user-defined name for the compliance job. Must be unique and up to 64 characters.
Type of compliance job: 'tweets' for Tweet IDs or 'users' for user IDs.
If true, returns a pre-signed URL for resumable uploads, useful for large ID lists. Defaults to false if not specified.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_CREATE_DM_CONVERSATIONCreates a new group Direct Message (DM) conversation on Twitter. REQUIRED PARAMETERS: - conversation_type: Must be 'Group' - participant_ids: List of Twitter user IDs to include in the conversation - message: JSON object with the initial message. Must contain 'text' field. To include media attachments, use message.attachments array with media_id (NOT media_url): {"text": "...", "attachments": \[{"media_id": "1234567890"}\]} Note: Media must be uploaded first using the upload_media action to obtain a media_id.
Input parameters
REQUIRED. A JSON object representing the initial message for the DM conversation. It must contain a 'text' field for the message content. To include media, use an 'attachments' array with media_id (NOT media_url): attachments: \[{"media_id": "media_id_string"}\]. Media must be uploaded first using upload_media action to obtain a media_id.
REQUIRED. A list of Twitter User IDs for the participants to be included in the group DM conversation. Minimum 2 user IDs required. The authenticated user is implicitly included and should not be added to this list.
REQUIRED. Specifies the type of conversation to be created. Must be 'Group' for this action.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_CREATE_LISTCreates a new, empty List on X (formerly Twitter), for which the provided name must be unique for the authenticated user; accounts are added separately.
Input parameters
Name for the List (1-25 characters, must start with a letter, and can only contain letters, numbers, hyphens, or underscores).
Sets List visibility: True for private, False for public.
Brief description for the List (up to 100 characters).
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_CREATION_OF_A_POSTCreates a Tweet on Twitter; `text` is required unless `card_uri`, `media_media_ids`, `poll_options`, or `quote_tweet_id` is provided. Example - Creating a tweet with media and location: { "text": "Check out our latest product update! 🚀", "media_media_ids": \["1455952740635586573"\], "geo_place_id": "df51dec6f4ee2b2c" } Example - Quote tweet with commentary: { "text": "This is a game-changer for the industry! Here's why... 🧵", "quote_tweet_id": "1453828617121234945" } Example - Reply to a tweet: { "text": "Great point! Here's my take on this...", "reply_in_reply_to_tweet_id": "1453828617121234945" }
Input parameters
Text content of the Tweet. Length limits are enforced by the X (Twitter) API and depend on the authenticated user's account tier — basic accounts are typically capped at 280 weighted characters (emojis/CJK count as 2, URLs count as 23 regardless of length), while X Premium accounts may post longer content. Validation is delegated to the API; over-length submissions return a 4xx error. At least one of `text`, `media_media_ids`, `card_uri`, `poll_options`, or `quote_tweet_id` must be provided with a non-empty value. Empty strings or whitespace-only strings are not valid. IMPORTANT: Do not include t.co URLs (Twitter's URL shortener) - use original URLs and Twitter will shorten them automatically. Also avoid URL placeholders like <URL>, \[URL\], or {URL} which will be rejected.
URI of a card to attach. Mutually exclusive with `quote_tweet_id`, `poll` parameters, `media` parameters, and `direct_message_deep_link`.
Marks the Tweet as a promoted-only post, not appearing in public timelines or served to followers.
Twitter Place ID to associate with the Tweet.
List of 2 to 4 poll options (max 25 characters each). Required if creating a poll. Mutually exclusive with `card_uri`.
ID of the Tweet to quote. MUST be a numeric string containing only digits (1-19 digits). Accepts string or numeric types, automatically converted to string. Example: '1346889436626259968' is valid. Placeholder values like 'unknown', 'null', 'none' are NOT valid. Mutually exclusive with `card_uri`, `poll` parameters, and `direct_message_deep_link`.
Specifies who can reply to this Tweet. Valid values are: 'following' (users following the author), 'mentionedUsers' (users mentioned in the Tweet - note: use 'mentionedUsers', NOT 'mentioning'), or 'subscribers' (X Premium subscribers only).
Up to 4 Media IDs obtained from prior uploads. Each Media ID MUST be a numeric string containing only digits (1-19 digits), matching the pattern ^\[0-9\]{1,19}$. Example: '1455952740635586573' is valid, 'PLACEHOLDER_MEDIA_ID' is invalid. At least one of `text` or `media_media_ids` must be provided. Mutually exclusive with `card_uri`.
Specifies who can reply to the poll Tweet: 'following' or 'mentionedUsers'. Mutually exclusive with `card_uri`.
User IDs to tag in media; tagged users must have enabled photo tagging. Mutually exclusive with `card_uri`.
Poll duration in minutes (5-10080). Required if `poll_options` are provided. Mutually exclusive with `card_uri`.
Deep link to a private Direct Message conversation. Mutually exclusive with `card_uri`.
Restricts Tweet visibility to the author's Super Followers.
ID of the Tweet to which this is a reply. MUST be a numeric string containing only digits (1-19 digits). Accepts string or numeric types, automatically converted to string. Example: '1346889436626259960' is valid, 'Hello' is invalid. Required if creating a reply. Note: Twitter does not allow replies to tweets that have been edited - use quote_tweet_id instead for edited tweets.
User IDs to exclude from @mentioning in the reply; these users will not be notified. Used when `reply_in_reply_to_tweet_id` is set.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_DELETE_DMPermanently 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.
Input parameters
The unique identifier of the Direct Message event to be deleted.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_DELETE_LISTPermanently deletes a specified Twitter List using its ID, which must be owned by the authenticated user; this action is irreversible and the list must already exist.
Input parameters
The unique identifier of the Twitter List to be deleted.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_FOLLOWERS_BY_USER_IDRetrieves a list of users who follow a specified public Twitter user ID.
Input parameters
The ID of the User to lookup.
Array of fields to expand.
The maximum number of results.
Array of User fields to display.
Array of Tweet fields to display.
Token for paginating results.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_FOLLOWING_BY_USER_IDRetrieves users followed by a specific Twitter user, allowing pagination and customization of returned user and tweet data fields via expansions.
Input parameters
The unique identifier of the Twitter User whose following list is to be retrieved.
Objects to expand (e.g., `pinned_tweet_id`) to include related data alongside user information.
The maximum number of users to return per page, typically between 1 and 1000. Defaults to 100 if not specified.
User fields to include for each followed user, providing additional details.
Tweet fields to include for expanded tweet-related objects (e.g., `pinned_tweet_id`).
A token obtained from the `next_token` field in a previous response, used to fetch the next page of results. Omit for the first page.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_FOLLOW_LISTAllows the authenticated user (`id`) to follow a specific Twitter List (`list_id`) they are permitted to access, subscribing them to the list's timeline; this does not automatically follow individual list members.
Input parameters
The unique numeric identifier of the authenticated user who will follow the list. Must match the currently authenticated user's ID (obtainable via user_lookup_me action). This is a required path parameter.
The unique numeric identifier (1-19 digits) of the Twitter/X List to follow. The list must be public, or the authenticated user must have access to a private list. List IDs can be found in list URLs or via list lookup actions.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_FOLLOW_USERAllows an authenticated user (path `id`) to follow another user (`target_user_id`), which results in a pending request if the target user's tweets are protected.
Input parameters
The User ID of the authenticated user initiating the follow request. If not provided, it will be automatically fetched from the authenticated session.
The unique identifier of the User to be followed. This ID is a numeric string with 1 to 19 digits. Required parameter. Alternatively, you can pass 'user_id' which will be treated as the target user ID.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_FULL_ARCHIVE_SEARCHSearches the full archive of public Tweets from March 2006 onwards; use 'start_time' and 'end_time' together for a defined time window.
Input parameters
The search query or rule to match Tweets. IMPORTANT: (1) Must contain at least one positive search term (word, hashtag, username, phrase). Queries with only negations (e.g., '-is:retweet') or only operators (e.g., 'lang:en') are invalid. (2) Spaces between terms act as implicit AND (e.g., 'cat dog' finds tweets with both). Do NOT use explicit 'AND' keyword - it will cause 'Ambiguous use of and' errors. (3) Use uppercase OR for OR logic (e.g., 'cat OR dog'). (4) Use '-' prefix for NOT (e.g., '-retweet'). (5) Use parentheses for grouping (e.g., '(cat OR dog) photo'). (6) Wildcard characters (*) are NOT supported in search terms. (7) Standalone '#' characters are invalid - hashtags must have text after '#'. (8) The '&' character is auto-converted to space (implicit AND) since Twitter doesn't support it as an operator. (9) Context annotations: Use 'context:domain_id.entity_id' to filter by topics/entities Twitter automatically detects (e.g., 'context:12.706083845846597632' for LA Lakers). Only valid domain-entity pairs from Twitter's annotation system work; invalid IDs cause 'Invalid Domain-Entity pair specified' errors. See Twitter's context annotations documentation and GitHub CSV for valid IDs.
The newest UTC timestamp (YYYY-MM-DDTHH:mm:ssZ) to which Tweets will be provided. Exclusive. Must be at least 10 seconds prior to the current request time. If provided time is too recent, it will be automatically adjusted to 10 seconds before the request time. Example: '2021-01-31T23:59:59Z'.
Returns results with a Tweet ID numerically greater (more recent) than the specified ID.
Returns results with a Tweet ID numerically less (older) than the specified ID.
Specifies which objects to expand in the response for more details.
A token obtained from a previous response's 'meta.next_token' field to retrieve the next page of results. Do not modify this value.
Specifies the order in which to return results. 'recency' returns the most recent Tweets first, 'relevancy' returns Tweets based on relevance.
The oldest UTC timestamp (YYYY-MM-DDTHH:mm:ssZ) from which Tweets will be provided. Inclusive. Must be on or after 2006-03-21T00:00:00Z (the date of the first tweet). If provided time is before this minimum date, it will be automatically adjusted to 2006-03-21T00:00:00Z. Example: '2021-01-01T00:00:00Z'.
The maximum number of search results to return per request. Must be between 10 and 500.
Specifies which poll fields to include if 'attachments.poll_ids' is expanded.
Additional user object fields to include if 'author_id' or other user-related expansions are used. Note: 'id', 'name', and 'username' are always returned by default for user objects. While these default fields can be included in this parameter, they are redundant since the API returns them automatically.
Specifies which media fields to include if 'attachments.media_keys' is expanded.
Specifies which place fields to include if 'geo.place_id' is expanded.
Specifies which Tweet fields to include in the response.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_BLOCKED_USERSRetrieves the authenticated user's own block list. IMPORTANT: You can only retrieve YOUR OWN block list - the `id` parameter must be the authenticated user's ID. Use the 'Get authenticated user' action first to obtain your user ID.
Input parameters
The authenticated user's own Twitter user ID. IMPORTANT: This endpoint only allows you to retrieve YOUR OWN block list - you cannot query another user's blocked accounts. The ID provided MUST match the currently authenticated user's ID. Use the 'Get authenticated user' (user_lookup_me) action to retrieve your user ID if needed.
Related objects to expand and include, like `pinned_tweet_id` for full Tweet objects. Sent as a comma-separated string to the API.
Maximum number of blocked users per page (1-100). API defaults to 100 if unspecified.
User fields to include for each blocked user. Sent as a comma-separated string to the API (e.g., 'created_at,description').
Fields to include for expanded Tweet objects (e.g., via `expansions=pinned_tweet_id`). Sent as a comma-separated string to the API.
Token for fetching the next page of results, obtained from `meta.next_token` of a previous response.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_COMPLIANCE_JOBRetrieves status, download/upload URLs, and other details for an existing Twitter compliance job specified by its unique ID.
Input parameters
The unique identifier of the Compliance Job to retrieve.
Specifies fields for the ComplianceJob object in the response; if omitted, a default set is returned.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_COMPLIANCE_JOBSReturns a list of recent compliance jobs, filtered by type (tweets or users) and optionally by status.
Input parameters
Specifies the type of compliance job to retrieve (tweets or users).
Filters compliance jobs by status; if omitted, jobs of all statuses for the specified type are returned.
Specific `ComplianceJob` fields to include in the response; if omitted, a default set of fields is returned.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_DM_CONVERSATION_EVENTSFetches 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.
Input parameters
Objects to expand and include. E.g., `sender_id` includes the full User object for each DM sender.
DM event types to include. If unspecified, all types are returned.
Maximum DM events per page (1-100).
Fields for User objects if `expansions` includes `sender_id` or `participant_ids`. Default: basic user fields.
Fields for Media objects if `expansions` includes `attachments.media_keys`. Default: basic media fields.
Fields for Tweet objects if `expansions` includes `referenced_tweets.id`. Default: basic tweet fields.
User ID of the other participant in the one-to-one DM conversation.
Fields for each DM event object. Default: 'id', 'event_type'.
Token from `meta.next_token` or `meta.previous_token` of a prior response to fetch a specific results page.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_DM_EVENTFetches a specific Direct Message (DM) event by its unique ID, allowing optional expansion of related data like users or tweets; ensure the `event_id` refers to an existing DM event accessible to the authenticated user.
Input parameters
The unique identifier of the Direct Message event to retrieve.
Related objects to expand and include in the response.
User fields to include for user objects in the response.
Media fields to include for media objects in the response.
Tweet fields to include for tweet objects in the response.
DmEvent fields to include in the response.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_LISTReturns metadata for a specific Twitter List, identified by its ID; does not return list members but can expand the owner's User object via the `expansions` parameter.
Input parameters
The unique identifier of the Twitter List to retrieve. This is a numeric string representing the List ID.
A list of objects to expand in the response. Currently, the only supported expansion is `owner_id`, which, if included, returns the full User object for the list's owner within an `includes` object in the response.
A list of fields to be returned for the List object. Valid fields include `created_at`, `description`, `follower_count`, `id`, `member_count`, `name`, `owner_id`, and `private`. If unspecified, default fields are returned.
A list of fields to be returned for User objects if `owner_id` is specified in `expansions`. Valid fields include attributes like `id`, `name`, `username`, `created_at`, `description`, `public_metrics`, etc. If unspecified, default fields are returned for User objects.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_LIST_FOLLOWERSFetches 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.
Input parameters
Unique identifier of the Twitter List for which to retrieve followers.
Fields to expand for more detailed information on related entities (e.g., pinned tweets, affiliated users).
Maximum number of user results per page.
User fields to include in the response for additional details on each follower.
Tweet fields to include if tweet objects (e.g., pinned_tweet_id) are expanded.
Pagination token from a previous response's `next_token` to retrieve the next page.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_LIST_MEMBERSFetches members of a specific Twitter List, identified by its unique ID.
Input parameters
The unique identifier of the Twitter List.
A list of fields to expand for each user, such as `pinned_tweet_id` to include the user's pinned Tweet. If an expansion is included, `tweet.fields` can be used to specify which Tweet fields are returned.
The maximum number of list members to return per page. Values can range from 1 to 100.
Specifies which additional user details to return for each list member.
A list of Tweet fields to be included if an expansion like `pinned_tweet_id` or `most_recent_tweet_id` is requested. This specifies what details of the expanded Tweet should be returned.
Token for fetching a specific page of results. Obtained from the `next_token` or `previous_token` field in the response's `meta` object.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_MEDIA_UPLOAD_STATUSGet the processing status of uploaded media (videos/GIFs) on X/Twitter. Only call this when the FINALIZE command returned a processing_info field. Poll every 3–5 seconds with a 60–120 second maximum timeout to avoid HTTP 429 errors. Response state cycles through 'pending', 'in_progress', 'succeeded', and 'failed'. Only attach media_id to a tweet when state is 'succeeded'. State 'failed' is terminal — requires a completely new upload via TWITTER_UPLOAD_MEDIA or TWITTER_UPLOAD_LARGE_MEDIA. Video/GIF processing takes 30–120 seconds; posting before 'succeeded' results in non-playable media.
Input parameters
Numeric media ID (1-19 digits) returned from a previous media upload.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_MUTED_USERSReturns user objects muted by the X user identified by the `id` path parameter.
Input parameters
The User ID of the authenticated user whose muted users are to be retrieved. This ID must correspond to an existing X user.
A comma-separated list of fields to expand for related objects in the response, providing more detailed information. For example, `pinned_tweet_id` can be expanded to include the full Tweet object.
The maximum number of user objects to return per page. Default is 100, minimum is 1, maximum is 1000.
A comma-separated list of user fields to include in the response. These fields provide additional information about the muted user objects (e.g., `created_at`, `description`).
A comma-separated list of Tweet fields to include for any expanded Tweet objects (e.g., if `pinned_tweet_id` is in `expansions`). This is only relevant if Tweet objects are being expanded.
A token obtained from a previous response, used to fetch the next page of results. If not provided, the first page is returned.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_OPENAPI_SPECFetches the OpenAPI specification (JSON) for Twitter's API v2, used to programmatically understand the API's structure for developing client libraries or tools.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_POST_ANALYTICSTool to retrieve analytics data for specified Posts within a defined time range. Use when you need engagement metrics, impressions, or other analytics for one or more Posts. Requires OAuth 2.0 with tweet.read and users.read scopes.
Input parameters
A comma-separated list of Post IDs (up to 100 allowed). Each ID should be a numeric string matching pattern ^\[0-9\]{1,19}$.
The UTC timestamp representing the end of the time range in format YYYY-MM-DDTHH:mm:ssZ. Must be a valid RFC3339 datetime string.
The UTC timestamp representing the start of the time range in format YYYY-MM-DDTHH:mm:ssZ. Must be a valid RFC3339 datetime string.
The granularity for the analytics results. Determines how the metrics are aggregated over the time range.
A comma-separated list of analytics fields to display. If not specified, all available fields will be returned. Accepts either a list or a comma-separated string.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_POST_RETWEETERS_ACTIONRetrieves users who publicly retweeted a specified public Post ID, excluding Quote Tweets and retweets from private accounts.
Input parameters
The unique identifier of the Post (Tweet) for which to retrieve retweeting users. This ID must be for an existing public Post.
Objects to expand and include, such as pinned Tweets of retweeters.
Maximum number of user objects per page (1-100, default 100).
User fields to include for each user who retweeted the Post.
Tweet fields for expanded Tweet objects (e.g., when `expansions` includes 'pinned_tweet_id').
A token obtained from a previous response's `meta.next_token` field, used to fetch the next page of results. If not provided, the first page is returned.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_POST_RETWEETSRetrieves Tweets that Retweeted a specified public or authenticated-user-accessible Tweet ID, optionally customizing the response with fields and expansions.
Input parameters
The unique identifier of the Tweet for which to retrieve Retweets.
Specifies objects to expand for related data on Retweeting Tweets or their authors (e.g., `author_id`, `referenced_tweets.id`).
Specifies the maximum number of Retweets to return, between 10 and 100.
Poll fields to include if `expansions` contains `attachments.poll_ids`.
User fields for authors of Retweeting Tweets, applicable if `expansions` includes `author_id`.
Media fields to include if `expansions` contains `attachments.media_keys`.
Place fields to include if `expansions` contains `geo.place_id`.
Specifies Tweet fields to include for additional information about the Retweeting Tweets.
Pagination token from a previous response's `meta.next_token` to request the next page of results.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_POST_USAGEFetches Tweet usage statistics for a Project (e.g., consumption, caps, daily breakdowns for Project & Client Apps) to monitor API limits; data can be retrieved for 1 to 90 days.
Input parameters
Specifies the number of days (1 to 90) to retrieve usage data for. Defaults to 7 days.
A list of specific usage metrics to retrieve. Available fields include: 'cap_reset_day', 'daily_client_app_usage', 'daily_project_usage', 'project_cap', 'project_id', 'project_usage'. If omitted, all available usage fields are returned.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_RECENT_DM_EVENTSReturns recent Direct Message events for the authenticated user, such as new messages or changes in conversation participants.
Input parameters
A comma separated list of fields to expand.
The set of event_types to include in the results.
Number of DM events to return (up to 2000 per call). Automatically paginates internally. If more results exist beyond 2000, check `meta.has_more` from the tool response and pass `meta.next_token` to `pagination_token` in a new call to continue from that point.
A comma separated list of User fields to display.
A comma separated list of Media fields to display.
A comma separated list of Tweet fields to display.
A comma separated list of DmEvent fields to display.
This parameter is used to get a specified "page" of results.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_SPACE_BY_IDRetrieves details for a Twitter Space by its ID, allowing for customization and expansion of related data, provided the Space ID is valid and accessible.
Input parameters
Unique identifier of the Twitter Space to retrieve.
Objects to expand in the response (e.g., `creator_id`). Customize with corresponding `*_fields`. See ExpansionsEnm0 for options.
Fields for User objects expanded via `expansions` (e.g., if `creator_id` is expanded). See UserFieldsEnm0 for options.
Fields to include for the Space object; defaults to a standard set if omitted. See SpaceFieldsEnm0 for options.
Fields for Topic objects expanded via `expansions` (e.g., if `topic_ids` is expanded). See TopicFieldsEnm0 for options.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_SPACE_POSTSRetrieves Tweets that were shared/posted during a Twitter Space broadcast. IMPORTANT: This endpoint returns Tweets that participants explicitly shared during the Space session, NOT audio transcripts, comments, or reactions. Most Spaces have zero associated Tweets, so empty results (result_count=0) are normal and expected. Twitter Spaces are primarily audio conversations - this endpoint only returns text Tweets that were shared alongside the audio.
Input parameters
The unique identifier of the Twitter Space. Can be extracted from Space URLs (e.g., '1nAKEEAgYvkKL' from https://x.com/i/spaces/1nAKEEAgYvkKL). Note: Most Spaces have zero associated Tweets since Spaces are primarily audio conversations.
A list of fields to expand and include additional related objects in the response, such as author details or media attachments. Expanded objects are returned in the 'includes' section of the response.
The maximum number of Tweets to fetch from the Space per request. Defaults to 100, which is also the maximum allowed.
A list of Poll fields to be included for polls, if 'attachments.poll_ids' is part of 'expansions'.
A list of User fields to be included for user objects, if 'author_id' or other user-related fields are part of 'expansions'.
A list of Media fields to be included for media content, if 'attachments.media_keys' is part of 'expansions'.
A list of Place fields to be included for geo-tagged Tweets, if 'geo.place_id' is part of 'expansions'.
A list of Tweet fields to be included in the response. By default, only 'id' and 'text' are returned for each Tweet.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_SPACES_BY_CREATORSRetrieves Twitter Spaces created by a list of specified User IDs, with options to customize returned data fields.
Input parameters
A list of User IDs whose Spaces will be retrieved. At least one User ID must be provided.
Specifies which related objects to expand for more detailed information in the response.
Specifies which fields to return for User objects, applicable when User-related IDs (e.g., 'creator_id') are included in 'expansions'.
Specifies which fields to return for each Space object.
Specifies which fields to return for Topic objects, applicable when 'topic_ids' is included in 'expansions'.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_SPACES_BY_IDSFetches detailed information for one or more Twitter Spaces (live, scheduled, or ended) by their unique IDs; at least one Space ID must be provided.
Input parameters
Unique identifiers for the Twitter Spaces to retrieve.
Objects to expand and include their full details (e.g., 'creator_id', 'host_ids'). See `ExpansionsEnm0` for options.
Specific fields for User objects included via expansions (e.g., if 'creator_id' is in 'expansions'). See `UserFieldsEnm0` for options.
Specific fields to return for each Space object; omits to return default fields. See `SpaceFieldsEnm0` for options.
Specific fields for Topic objects included via expansions (e.g., if 'topic_ids' is in 'expansions'). See `TopicFieldsEnm0` for options.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_SPACE_TICKET_BUYERSRetrieves a list of users who purchased tickets for a specific, valid, and ticketed Twitter Space.
Input parameters
The unique identifier of the Space for which to retrieve the list of ticket buyers.
Objects to expand in the response for more detailed information (e.g., `pinned_tweet_id` to include the full Tweet object).
Maximum number of buyer records to return per page.
User fields to include for each buyer, providing additional details. Refer to the User object schema for available fields.
Tweet fields to include when Tweet objects are expanded. Refer to the Tweet object schema for available fields.
Token from a previous response to fetch the subsequent page of results.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_USER_BY_IDRetrieves detailed public information for a Twitter user by their ID, optionally expanding related data (e.g., pinned tweets) and specifying particular user or tweet fields to return.
Input parameters
The unique numeric identifier (ID) of an existing Twitter/X user. Must be a string of 1-19 digits (e.g., '44196397' for @elonmusk, '12' for @jack). Note: This must be the numeric user ID, NOT the @username handle.
Linked entities to expand (e.g., `pinned_tweet_id` for the full pinned Tweet). See `ExpansionsEnm0` for options.
Specifies which user attributes to return. See `UserFieldsEnm0` for options.
Specifies which tweet attributes to return for expanded tweets. See `TweetFieldsEnm0` for options.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_USER_FOLLOWED_LISTSReturns metadata (not Tweets) for lists a specific Twitter user follows, optionally including expanded owner details.
Input parameters
The unique identifier of the User whose followed lists are to be retrieved.
A list of objects to expand and include in the response. Use `owner_id` to include the User object of the list's owner. Refer to `ExpansionsEnm0` for available options.
A list of fields to include for each List object in the response. Refer to `ListFieldsEnm0` for all available fields.
The maximum number of List results to be returned per page. Default is 100.
A list of fields to include for each User object, applicable if `expansions` includes `owner_id`. Refer to `UserFieldsEnm0` for available fields.
A token used to retrieve a specific page of results. This value is obtained from the `next_token` field in the `meta` object of a previous response. Use it to navigate through paginated results.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_USER_LIST_MEMBERSHIPSRetrieves all Twitter Lists a specified user is a member of, including public Lists and private Lists the authenticated user is authorized to view.
Input parameters
The unique identifier of the target User whose List memberships are to be retrieved.
A list of objects to be expanded in the response, providing additional related data. For example, expanding `owner_id` includes the full User object for the list owner. Each item must be a value from `ExpansionsEnm0`.
A list specifying the desired fields to be returned for each List object. Each item in the list must be a value from `ListFieldsEnm0`. If omitted, default fields are returned.
Specifies the maximum number of List memberships to return in a single page. Valid range: 1-100. Default: 100.
A list specifying the desired fields for User objects, applicable if `owner_id` is included in `expansions`. Each item in the list must be a value from `UserFieldsEnm0`. If omitted, default fields are returned for expanded User objects.
Token for pagination, used to fetch a specific page of results. Obtain this from the `next_token` field in a previous response to get the next page.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_USER_OWNED_LISTSCall this action to retrieve Lists created (owned) by a specific Twitter user, not Lists they follow or are subscribed to.
Input parameters
User ID of the Twitter User whose owned Lists are to be retrieved.
Set to `\['owner_id'\]` to include the User object of the List's owner.
Specific fields to return for each List object (e.g., `created_at`, `description`).
Maximum number of List results per page. Allowed values: 1-100. Default: 100.
Specific fields for User objects if `expansions` includes `owner_id` (e.g., `public_metrics`, `created_at`).
Token from `meta.next_token` of a previous response to fetch the next page. Omit for the first page.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_USER_PINNED_LISTSRetrieves the Lists a specific, existing Twitter user has pinned to their profile to highlight them.
Input parameters
The unique identifier of the User whose pinned Lists are to be retrieved.
A comma-separated list of object IDs to expand in the response, providing full details instead of just an ID. Select from `ExpansionsEnm0` to include related objects like the list owner.
A comma-separated list of List fields to return for each List object. Select desired fields from `ListFieldsEnm0`.
A comma-separated list of User fields to return. This is applicable when `expansions` includes `owner_id`. Select desired fields from `UserFieldsEnm0`.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_GET_USERS_BY_IDSRetrieves detailed information for specified X (formerly Twitter) user IDs, optionally customizing returned fields and expanding related entities.
Input parameters
User IDs to retrieve (up to 100 per request). Accepts a list of ID strings (e.g., \['2244994945', '783214'\]) or a comma-separated string (e.g., '2244994945,783214').
Objects to expand in the response (e.g., 'pinned_tweet_id'). See ExpansionsEnm0 for options.
Specific user fields to return. See UserFieldsEnm0 for options.
Tweet fields to return for expanded tweet objects. See TweetFieldsEnm0 for options.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_HIDE_REPLIESHides or unhides an existing reply Tweet. This action allows the authenticated user to hide or unhide a reply to a conversation they own (started). You can only hide replies to posts you authored. Note: Requires the tweet.moderate.write OAuth scope.
Input parameters
Set to `true` to hide the reply, `false` to unhide.
Unique identifier of the reply Tweet to hide or unhide.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_INITIALIZE_MEDIA_UPLOADInitialize a media upload session for X/Twitter. Use this to start a chunked media upload process, which returns a media_id for subsequent APPEND and FINALIZE commands. Required for uploading large files or when using the chunked upload workflow.
Input parameters
Whether this media is shared or not. Optional parameter.
The MIME type of the media file to be uploaded (e.g., 'video/mp4', 'image/png'). This determines how Twitter processes the file.
The total size of the media file in bytes. Must be between 0 and 17179869184 (16 GB).
Media category for upload
A list of user IDs to set as additional owners allowed to use the returned media_id in Tweets or Cards. Each user ID must be a string of 1-19 digits.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_LIST_POST_LIKERSRetrieves users who have liked the Post (Tweet) identified by the provided ID.
Input parameters
The unique identifier of the Post (Tweet) for which to retrieve liking users.
Fields to expand for related objects, like a user's pinned Tweet. Example: \['pinned_tweet_id'\].
The maximum number of user objects to return per page. The value must be between 1 and 100, inclusive. Defaults to 100 if not specified.
User fields to retrieve for each liking user. Example: \['created_at', 'description'\].
Tweet fields to retrieve for expanded Tweet objects (e.g., if `expansions` includes `pinned_tweet_id`). Example: \['created_at', 'public_metrics'\].
A token used to request the next page of results if more results are available. This token is returned in the `meta.next_token` field of a previous response.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_LIST_POSTS_TIMELINE_BY_LIST_IDFetches the most recent Tweets posted by members of a specified Twitter List.
Input parameters
The unique identifier of the Twitter List from which to retrieve Tweets.
Specifies which related objects to expand and include in the response (e.g., author data, media details).
The maximum number of Tweets to return per request. Must be between 1 and 100.
Specifies which Poll object fields to include if 'attachments.poll_ids' is in 'expansions'.
Specifies which User object fields to include if 'author_id' or other user references are in 'expansions'.
Specifies which Media object fields to include if 'attachments.media_keys' is in 'expansions'.
Specifies which Place object fields to include if 'geo.place_id' is in 'expansions'.
Specifies which Tweet object fields to include in the response.
A token used to request the next page of results if more Tweets are available. Obtained from the 'next_token' field in a previous response.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_MUTE_USERMutes 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.
Input parameters
The User ID of the authenticated user performing the mute action. If not provided, it will be automatically fetched from the authenticated session. Must match the authenticated user's ID.
The User ID of the user to be muted.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_PIN_LISTPins a specified List to the authenticated user's profile, provided the List exists, the user has access rights, and the pin limit (typically 5 Lists) is not exceeded.
Input parameters
The ID of the authenticated User pinning the List.
The unique identifier of the List to be pinned.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_POST_DELETE_BY_POST_IDIrreversibly deletes a specific Tweet by its ID; the Tweet may persist in third-party caches after deletion.
Input parameters
The unique identifier of the Tweet to be deleted. This ID must correspond to a Tweet authored by the authenticated user.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_POST_LOOKUP_BY_POST_IDFetches comprehensive details for a single Tweet by its unique ID, provided the Tweet exists and is accessible.
Input parameters
The unique numeric identifier of the Tweet to retrieve. Must be a numeric string (1-19 digits). Common prefixes like 'tweet_' will be automatically stripped.
Additional data related to the Tweet to include, such as author details, mentioned users, or media information. Accepts a list of expansion names or a comma-separated string.
Poll attributes to include if poll objects are part of the Tweet or expansions. Accepts a list of field names or a comma-separated string.
User attributes to include for user objects (e.g., author, mentions) requested via expansions. Accepts a list of field names or a comma-separated string. NOTE: 'username' is a default field always returned by the API and is not a valid value for this parameter (it will be automatically filtered out if provided).
Media attributes to include if media objects are part of the Tweet or expansions. Accepts a list of field names or a comma-separated string.
Place attributes to include if place objects are part of the Tweet or expansions. Accepts a list of field names or a comma-separated string.
Tweet attributes to include for additional details about the Tweet. Accepts a list of field names or a comma-separated string.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_POST_LOOKUP_BY_POST_IDSRetrieves detailed information for one or more Posts (Tweets) identified by their unique IDs, allowing selection of specific fields and expansions.
Input parameters
A list of Post IDs to retrieve. Up to 100 IDs can be specified in a single request. Parameter can be provided as 'ids', 'tweet_ids', or 'post_ids'.
A comma-separated list of fields to expand in the response for related entities like authors or media. Can be provided as a string (comma-separated) or a list.
A comma-separated list of Poll fields to include for poll attachments. Can be provided as a string (comma-separated) or a list.
A comma-separated list of User fields to include for user objects. Can be provided as a string (comma-separated) or a list.
A comma-separated list of Media fields to include for media attachments. Can be provided as a string (comma-separated) or a list.
A comma-separated list of Place fields to include for geo-tagged Tweets. Can be provided as a string (comma-separated) or a list.
A comma-separated list of Tweet fields to include in the response. Can be provided as a string (comma-separated) or a list.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_RECENT_SEARCHSearches 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`) DEFAULT FIELDS: Tweet objects always return 'id' and 'text' by default. User objects always return 'id', 'name', and 'username' by default when expanded. Do not request these default fields in field parameters. IMPORTANT LIMITATION - Impression Counts: The public_metrics.impression_count field returns 0 for search results from other users. Impression data is a non-public metric only available for tweets owned by the authenticated user. To filter by engagement, use retweet_count, like_count, or quote_count instead. Example - Get original tweets from Elon Musk since Sept 20, 2025: { "query": "from:elonmusk -is:retweet -is:reply", "start_time": "2025-09-20T00:00:00Z", "max_results": 50, "tweet_fields": \["created_at","public_metrics","text"\], "expansions": \["author_id","attachments.media_keys","referenced_tweets.id"\] }
Input parameters
REQUIRED. Search query for matching Tweets. Recent Search limited to last 7 days; for older tweets use Full Archive Search. IMPORTANT QUERY REQUIREMENTS: • Each OR-separated clause must independently contain at least one positive term (keyword, hashtag, from:user, etc.) • Each OR-separated clause must have at least one standalone operator (cannot use only is:/has:/lang: operators) • Queries with only negation operators are invalid (e.g., '-is:retweet -is:reply') Examples of VALID queries: • 'from:user -is:retweet' (single clause with standalone operator) • 'keyword is:reply OR from:user' (both OR clauses have standalone operators) • 'AI OR ML' (both OR clauses are standalone keywords) Examples of INVALID queries: • 'from:user OR is:reply' (second clause only has conjunction-required operator) • 'from:user OR -is:retweet' (second clause only has negation) • 'is:reply OR is:retweet' (both clauses lack standalone operators) Common operators: • Keywords: 'artificial intelligence' (implicit AND) • OR: 'AI OR ML' (uppercase required - splits query into independent clauses) • From user: 'from:username' (do NOT include @ symbol - use 'from:elonmusk' not 'from:@elonmusk') • To user: 'to:username' (do NOT include @ symbol) • Cashtags: '$TSLA' or '$BTC' (for financial symbols - must include ticker after $) • Language: 'lang:en' (valid: am, ar, bg, bn, ca, cs, da, de, el, en, es, et, fi, fr, gu, he, hi, hr, hu, id, it, ja, kn, ko, lt, lv, ml, mr, ms, nl, no, pa, pl, pt, ro, ru, sk, sl, sr, sv, ta, te, th, tr, uk, ur, vi, zh; 'auto' is NOT supported and will be auto-removed) Conjunction-required operators (CANNOT stand alone in an OR clause - must be combined with keyword, from:, to:, or hashtag): • '-is:retweet' - Exclude retweets • '-is:reply' - Exclude replies • '-is:quote' - Exclude quote tweets • 'is:retweet' - Only retweets • 'is:reply' - Only replies • 'is:quote' - Only quote tweets • 'has:video', 'has:images', 'has:links', 'has:media' - Media filters • 'lang:en' - Language filter Elevated-access operators (may require elevated access on certain tiers): • 'has:video' - Tweets with video attachments • 'has:images' - Tweets with image attachments • 'has:links' - Tweets containing links • 'has:media' - Tweets with any media (videos, images, GIFs) • 'referenced_tweet:' - Filter by referenced tweet ID (e.g., 'referenced_tweet:123456') Note: These operators may fail with 'Reference to invalid operator' error on Free/Basic tier. If you receive this error, remove these operators from your query. Note: Unsupported operators (min_retweets, min_faves, site:, lang:auto, since:, until:) are auto-removed. For time filtering, use start_time/end_time parameters instead of since:/until: operators. Note: Lowercase 'and' is a reserved keyword. It will be auto-quoted to search for the literal word 'and'. Note: The @ symbol in from:/to: operators is automatically stripped (from:@elonmusk becomes from:elonmusk). The API is case-insensitive for usernames.
Newest UTC timestamp (YYYY-MM-DDTHH:mm:ssZ) for results; exclusive. IMPORTANT: Cannot be used with `since_id` or `until_id` - these are mutually exclusive time range filters.
Returns Tweets more recent than this ID. IMPORTANT: Cannot be used with `start_time` or `end_time` - these are mutually exclusive time range filters.
Returns Tweets older than this ID. IMPORTANT: Cannot be used with `start_time` or `end_time` - these are mutually exclusive time range filters.
Expansions to include additional objects like users, media, polls, etc.
Token from `meta.next_token` of a previous response for pagination; do not modify.
Order of results: 'recency' (most recent first) or 'relevancy'.
Oldest UTC timestamp (YYYY-MM-DDTHH:mm:ssZ) for results. Must be within last 7 days. For last N hours, calculate from current time (e.g., now-12h = 2025-10-06T03:00:00Z if now is 15:00). IMPORTANT: Cannot be used with `since_id` or `until_id` - these are mutually exclusive time range filters.
Number of results to return. Twitter API enforces minimum of 10 (values below 10 are auto-adjusted to 10). Maximum 100 per call (automatically paginates internally for higher values up to 2000). If more results exist beyond 2000, check `meta.has_more` from the response and pass `meta.next_token` to `pagination_token` in a new call to continue from that point.
Poll fields to include when poll IDs are expanded.
Additional user object fields to include when user IDs are expanded via expansions. Note: 'id', 'name', and 'username' are always returned by default and should not be requested.
Media fields to include when media keys are expanded.
Place fields to include when place IDs are expanded.
Additional tweet object fields to include in the response.
Alternative pagination token from a previous `meta.next_token`; `next_token` is preferred if both are provided.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_REMOVE_LIST_MEMBERRemoves 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, and the updated list of members is not returned.
Input parameters
The unique identifier of the Twitter List from which a member will be removed.
The unique identifier (ID) of the Twitter user to be removed from the specified List.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_REMOVE_POST_FROM_BOOKMARKSRemoves a Tweet, specified by `tweet_id`, from the authenticated user's bookmarks; the Tweet must have been previously bookmarked by the user for the action to have an effect.
Input parameters
The Twitter user ID of the currently authenticated user. This parameter is optional - if not provided, it will be automatically retrieved from the authenticated user's profile. If provided, it MUST match the authenticated user's own Twitter user ID (not a tweet ID or another user's ID). You can find your user ID by using the User Lookup Me endpoint.
The ID of the Tweet to be removed from the user's bookmarks.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_RETRIEVE_DM_CONVERSATION_EVENTSRetrieves Direct Message (DM) events for a specific conversation ID on Twitter, useful for analyzing messages and participant activities.
Input parameters
The DM Conversation ID. For one-on-one conversations, use the format 'USER_ID_1-USER_ID_2' (e.g., '123456789-987654321') where both are numeric user IDs. For group conversations, use a single 15-19 digit numeric ID (e.g., '123456789012345').
A comma separated list of fields to expand.
The set of event_types to include in the results.
The maximum number of results.
A comma separated list of User fields to display.
A comma separated list of Media fields to display.
A comma separated list of Tweet fields to display.
A comma separated list of DmEvent fields to display.
This parameter is used to get a specified "page" of results.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_RETRIEVE_POSTS_THAT_QUOTE_A_POSTRetrieves Tweets that quote a specified Tweet, requiring a valid Tweet ID.
Input parameters
Unique identifier of the Tweet whose quoting Tweets you would like to retrieve.
Specifies whether to exclude replies or retweets from the results.
Fields to expand in the response, such as 'author_id' to include the author's user object.
Maximum number of results to return per page (range: 10-100).
Specific Poll fields to include in the response if poll objects are present.
Specific User fields to include if user objects are present (e.g., through expansions).
Specific Media fields to include in the response if media objects are present.
Specific Place fields to include in the response if place objects are present.
Specific Tweet fields to include in the response.
Token for retrieving a specific page of results, typically the `next_token` from a previous response.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_RETURNS_POST_OBJECTS_LIKED_BY_THE_PROVIDED_USER_IDRetrieves Tweets liked by a specified Twitter user, provided their liked tweets are public or accessible.
Input parameters
Twitter user ID whose liked Tweets are to be retrieved.
Objects to expand, e.g., `author_id`, `attachments.media_keys`, for richer data.
Maximum liked Tweets per page.
Poll fields to include when `attachments.poll_ids` is in `expansions`.
User fields for Tweet authors or other user objects when `expansions` includes them.
Media fields to include when `attachments.media_keys` is in `expansions`.
Place fields to include when `geo.place_id` is in `expansions`.
Specific Tweet fields to include. API provides a default set if omitted.
Token from a previous response to fetch the next page.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_RETWEET_POSTRetweets a Tweet for the authenticated user. The user ID is automatically fetched from the authenticated session - you only need to provide the tweet_id to retweet.
Input parameters
The ID of the Tweet to be retweeted.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_SEARCH_FULL_ARCHIVE_COUNTSReturns 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, and `since_id`/`until_id` cannot be used with `start_time`/`end_time`.
Input parameters
Search query for matching Tweets using Twitter's V2 filtering syntax (see official Twitter API documentation for syntax and length).
Newest UTC timestamp (exclusive, YYYY-MM-DDTHH:mm:ssZ) to count Tweets up to. Must be at least 10 seconds prior to the request time. If specified, `start_time` is also required and `end_time` must be later.
Count Tweets more recent than this ID. Cannot be used with `start_time` or `end_time`.
Count Tweets older than this ID. Cannot be used with `start_time` or `end_time`.
Token from a previous response to fetch the next page of results. Use as-is.
Oldest UTC timestamp (inclusive, YYYY-MM-DDTHH:mm:ssZ) to count Tweets from. If specified, `end_time` is also required and `start_time` must be earlier.
Time period granularity for aggregating search count results.
Pagination token, typically `next_token` in Twitter API v2. Use as-is.
Specifies which fields to return for each search count object; default fields are returned if unspecified.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_SEARCH_RECENT_COUNTSRetrieves the count of Tweets matching a specified search query within the last 7 days, aggregated by 'minute', 'hour', or 'day'.
Input parameters
A search query rule to match against Tweets. For example, '#twitterdev OR @twitterapi'. Refer to Twitter's documentation for query syntax and maximum length: https://developer.twitter.com/en/docs/twitter-api/tweets/search/integrate/build-a-query
OPTIONAL: The newest UTC timestamp (exclusive) to which to count Tweets. Must be in ISO 8601 format: YYYY-MM-DDTHH:mm:ssZ. Must be within the last 7 days. If omitted, defaults to now (minus 30 seconds). Do NOT pass placeholder values like '<DATE_TIME>' - either provide a valid timestamp or omit entirely.
Returns counts for Tweets created more recently than the specified Tweet ID. This helps to paginate results chronologically.
Returns counts for Tweets created older than the specified Tweet ID. This helps to paginate results chronologically.
A token obtained from a previous response to fetch the next page of results. Do not modify this value.
OPTIONAL: The oldest UTC timestamp (inclusive) from which to count Tweets. Must be in ISO 8601 format: YYYY-MM-DDTHH:mm:ssZ. Must be within the last 7 days. If omitted, defaults to 7 days ago. Do NOT pass placeholder values like '<DATE_TIME>' - either provide a valid timestamp or omit entirely.
The time period granularity for aggregating search counts.
A token used for pagination to retrieve the next set of results. This value is obtained from the 'next_token' field in a previous response.
A list of fields to include in each search count object. Available fields: 'end', 'start', 'tweet_count'. If unspecified, default fields are returned.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_SEARCH_SPACESSearches for Twitter Spaces by a textual query, optionally filtering by state (live, scheduled, all) to discover audio conversations.
Input parameters
The text query to search for in Space titles and descriptions.
Filters Spaces by their state (e.g., 'live', 'scheduled').
Specifies fields to expand and include additional related objects (e.g., 'creator_id' for User object, 'host_ids', 'invited_user_ids', 'speaker_ids', 'topic_ids').
The maximum number of Space results to return in a single response. Values must be between 1 and 100, inclusive.
Specifies fields for expanded User objects (e.g., 'username', 'public_metrics'). Omitting this returns a default set of User fields.
Specifies fields to include for each Space object (e.g., 'id', 'title'). Omitting this returns a default set of fields.
Specifies fields for expanded Topic objects (e.g., 'id', 'name'). Omitting this returns a default set of Topic fields.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_SEND_A_NEW_MESSAGE_TO_A_USERSends a new Direct Message with text and/or media (media_id for attachments must be pre-uploaded) to a specified Twitter user; this creates a new DM and does not modify existing messages.
Input parameters
Text content of the Direct Message.
Media attachments for the Direct Message.
User ID of the recipient.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_SEND_DM_TO_CONVERSATIONSends a message, with optional text and/or media attachments (using pre-uploaded `media_id`s), to a specified Twitter Direct Message conversation.
Input parameters
Text content of the Direct Message. At least one of `text` or `attachments` is required.
A list of media attachments for the Direct Message, each specifying a `media_id`. At least one of `text` or `attachments` is required.
Identifier of the DM conversation; can be a numeric string (group DM) or two user IDs hyphen-separated (one-on-one DM).
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_STREAM_POST_LABELSStream 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.
Input parameters
Latest UTC timestamp (YYYY-MM-DDTHH:mm:ssZ) at which the stream will automatically close, ceasing event transmission.
Earliest UTC timestamp (YYYY-MM-DDTHH:mm:ssZ) from which to start streaming label events; disregards `backfill_minutes` if provided.
Number of minutes of historical data (labels applied or removed) to stream upon connection for recent activity; ignored if `start_time` is provided. Valid values: 0-5.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_UNFOLLOW_LISTEnables a user (via `id`) to unfollow a specific Twitter List (via `list_id`), which removes its tweets from their timeline and stops related notifications; the action reports `following: false` on success, even if the user was not initially following the list.
Input parameters
The ID of the user who is unfollowing the list.
The ID of the Twitter List to be unfollowed.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_UNFOLLOW_USERAllows the authenticated user to unfollow an existing Twitter user (`target_user_id`), which removes the follow relationship. The source user ID is automatically determined from the authenticated session.
Input parameters
The user ID of the authenticated user initiating the unfollow action. If not provided, it will be automatically fetched from the authenticated session. Note: This parameter is automatically populated and should not be set manually.
The user ID of the user to unfollow. Alternatively, you can pass 'user_id' which will be treated as the target user ID.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_UNLIKE_POSTAllows an authenticated user (`id`) to remove their like from a specific post (`tweet_id`); the action is idempotent and completes successfully even if the post was not liked.
Input parameters
The ID of the authenticated user who is unliking the post. This user ID must match the user context of the authentication token.
The ID of the post (Tweet) that the user is requesting to unlike.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_UNMUTE_USERUnmutes 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.
Input parameters
User ID of the user to be unmuted.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_UNPIN_LISTUnpins a List (specified by list_id) from the authenticated user's profile. The user ID is automatically retrieved if not provided.
Input parameters
The authenticated user's ID. This parameter is optional - if not provided, it will be automatically retrieved from the authenticated user's context. If provided, it MUST match the authenticated user's ID (you cannot unpin lists from other users' profiles).
ID of the List to unpin from the authenticated user's profile.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_UNRETWEET_POSTRemoves a user's retweet of a specified Post, if the user had previously retweeted it.
Input parameters
The ID of the authenticated user making this request. This MUST be your own user ID (the currently authenticated account). You can only remove your own retweets, not someone else's. Use the user_lookup_me endpoint to get your authenticated user ID if needed.
The unique identifier of the Post (Tweet) that the user is requesting to unretweet.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_UPDATE_LISTUpdates an existing Twitter List's name, description, or privacy status, requiring the List ID and at least one mutable property.
Input parameters
The unique identifier of the Twitter List to be updated.
New name for the List; must be a non-empty string if provided.
Controls the visibility of the List: `True` for private, `False` for public.
New description for the List; an empty string clears the existing description.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_UPLOAD_LARGE_MEDIADEPRECATED: Use TWITTER_UPLOAD_MEDIA instead. Use this to upload a single media file to X/Twitter. Automatically uses chunked upload for GIFs, videos, and images larger than 5 MB. Max file size: 512 MB; max video duration: 140 seconds. After upload, poll TWITTER_GET_MEDIA_UPLOAD_STATUS until processing_info.state=='succeeded' before attaching the media_id to a tweet — GIFs and videos take 30–120 seconds to process. A terminal 'failed' state means the media_id is unusable and the file must be re-uploaded.
Input parameters
The media file to upload. Supported mimetypes: video/mp4, video/webm, image/gif, image/jpeg, image/png, image/webp. If mimetype is generic (e.g., application/octet-stream), it will be inferred from the media_category or file extension.
Media category for the upload. Valid values: tweet_image, tweet_gif, tweet_video, amplify_video. Optional; auto-detected from mimetype or file extension when omitted. Required for videos > 140 seconds or ads campaigns (use amplify_video). For standard uploads: tweet_video for videos, tweet_gif for animated GIFs, tweet_image for images.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_UPLOAD_MEDIAUpload media (images only) to X/Twitter using the v2 API. Supports tweet_image, dm_image, and subtitles media categories only. One file per call; the returned media_id expires (see expires_after_secs in response), so upload immediately before creating the tweet. For GIFs, videos, or any file larger than ~5 MB, use TWITTER_UPLOAD_LARGE_MEDIA instead.
Input parameters
The media file to upload. This action only supports images. For GIFs, videos, or any file larger than ~5 MB, use 'TWITTER_UPLOAD_LARGE_MEDIA' instead. Must include a valid mimetype (e.g., image/jpeg, image/png); incorrect or missing mimetype causes validation errors or misclassification.
The MIME type of the media being uploaded. Required for subtitle uploads. Examples: 'text/srt' for SRT subtitles, 'text/vtt' for VTT subtitles, 'image/jpeg' for JPEG images, 'image/png' for PNG images.
Media category for upload (v2 API) Note: The v2 media upload endpoint only supports these three categories. For videos and GIFs, use TWITTER_UPLOAD_LARGE_MEDIA instead.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_USER_HOME_TIMELINE_BY_USER_IDRetrieves the home timeline (reverse chronological feed) for the authenticated Twitter user. Returns tweets from accounts the user follows as well as the user's own tweets, in reverse chronological order. Useful for displaying the personalized feed without algorithmic sorting. CRITICAL: The 'id' parameter MUST be the authenticated user's own numeric Twitter user ID - use TWITTER_USER_LOOKUP_ME to get your ID first. This endpoint cannot fetch another user's home timeline, and passing any ID that doesn't match the authenticating user (including phone numbers or other user IDs) will result in an error. DEFAULT FIELDS: Tweet objects always return 'id' and 'text' by default. User objects always return 'id', 'name', and 'username' by default when expanded. Do not request these default fields in field parameters.
Input parameters
The numeric Twitter user ID of the authenticated user. OPTIONAL: If not provided, it will be automatically fetched. This endpoint only works for the authenticated user's own timeline, so providing another user's ID will result in an error. Must be a numeric string (1-19 digits) matching pattern ^\[0-9\]{1,19}$.
Tweet types to exclude from results. Accepts either a list \['replies', 'retweets'\] or a comma-separated string 'replies,retweets'.
Latest UTC timestamp for Tweets in RFC3339 format (YYYY-MM-DDTHH:mm:ssZ). Must use second granularity with Z timezone notation. Overridden by `until_id`.
Returns results with a Tweet ID more recent than the specified ID. Takes precedence over `start_time`.
Returns results with a Tweet ID older than the specified ID. Takes precedence over `end_time`.
Objects to expand and include in the response for detailed information. Accepts either a list \['author_id', 'attachments.media_keys'\] or a comma-separated string 'author_id,attachments.media_keys'.
Earliest UTC timestamp for Tweets in RFC3339 format (YYYY-MM-DDTHH:mm:ssZ). Must use second granularity with Z timezone notation. Overridden by `since_id`.
Number of tweets to return (up to 2000 per call). Automatically paginates internally. If more results exist beyond 2000, check `meta.has_more` from the tool response and pass `meta.next_token` to `pagination_token` in a new call to continue from that point.
Specific Poll fields for poll objects, if `expansions` includes `attachments.poll_ids`. Accepts either a list \['duration_minutes', 'options'\] or a comma-separated string 'duration_minutes,options'.
Additional user object fields to include in the response, if `expansions` includes user-related items like `author_id`. Accepts either a list \['public_metrics', 'created_at'\] or a comma-separated string 'public_metrics,created_at'.
Specific Media fields for media objects, if `expansions` includes `attachments.media_keys`. Accepts either a list \['url', 'preview_image_url'\] or a comma-separated string 'url,preview_image_url'.
Specific Place fields for place objects, if `expansions` includes `geo.place_id`. Accepts either a list \['full_name', 'country_code'\] or a comma-separated string 'full_name,country_code'.
Specific Tweet fields to include in the response. Accepts either a list \['created_at', 'public_metrics'\] or a comma-separated string 'created_at,public_metrics'.
Token from a previous response to fetch the next page of results.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_USER_LIKE_POSTAllows the authenticated user to like a specific, accessible Tweet, provided neither user has blocked the other and the authenticated user is not restricted from liking. The authenticated user's ID is automatically determined from the OAuth token - you only need to provide the tweet_id.
Input parameters
The numeric user ID of the authenticated user performing the like. MUST match the currently authenticated user's ID (use TWITTER_USER_LOOKUP_ME to retrieve it). Must be a numeric string (1-19 digits).
The unique identifier of the Tweet to be liked.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_USER_LOOKUP_BY_USERNAMEFetches public profile information for a valid and existing Twitter user by their username, optionally expanding related data like pinned Tweets; results may be limited for protected profiles not followed by the authenticated user.
Input parameters
Twitter username (handle), without '@'. Must match ^\[A-Za-z0-9_\]{1,15}$ (letters, numbers, underscore only; 1–15 chars). Leading '@' is ignored. Note: This endpoint accepts only a single username. For batch lookup of multiple usernames, use USER_LOOKUP_BY_USERNAMES action.
Fields to expand for more detailed information on objects like `pinned_tweet_id` (includes full Tweet object).
Additional user object fields to include in the response. Note: 'id', 'name', and 'username' are always returned by default for user objects and should not be specified here.
Additional tweet object fields to include for Tweets returned via expansions (e.g., `pinned_tweet_id`). Note: 'id' and 'text' are always returned by default for tweet objects and should not be specified here.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_USER_LOOKUP_BY_USERNAMESRetrieves detailed information for 1 to 100 Twitter users by their usernames (each 1-15 alphanumeric characters/underscores), allowing customizable user/tweet fields and expansion of related data like pinned tweets.
Input parameters
A list of Twitter/X usernames (handles) to look up (1-100 usernames). Valid Twitter usernames contain only letters (A-Z), numbers (0-9), and underscores (_), with a maximum length of 15 characters (pattern: ^\[A-Za-z0-9_\]{1,15}$). Leading '@' symbols are automatically stripped. Space-separated strings within a single element will be split into multiple usernames. Invalid usernames will result in errors from the API.
A list of objects to expand in the response, providing more detailed information. For example, 'pinned_tweet_id' will include the full Tweet object for a user's pinned Tweet.
A list of user fields to include in the response. By default, the API returns 'id', 'name', and 'username' fields. Specify additional fields here to include them in the response.
A list of tweet fields to include in the response if 'expansions' includes 'pinned_tweet_id'. These fields provide additional information about the pinned tweet.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
TWITTER_USER_LOOKUP_MEReturns profile information for the currently authenticated X user, customizable via request fields.
Input parameters
Fields to expand for related entities. ONLY 'pinned_tweet_id' is valid for user lookup endpoints. This returns the user's pinned Tweet in the includes.tweets array. Do NOT use tweet expansions like 'author_id' or 'referenced_tweets.id' - those are not valid for this endpoint. Note: 'affiliation' and 'most_recent_tweet_id' are user fields, not expansions.
User attributes to include in the response. Valid values: affiliation, connection_status, created_at, description, entities, id, location, most_recent_tweet_id, name, pinned_tweet_id, profile_banner_url, profile_image_url, protected, public_metrics, receives_your_dm, subscription_type, url, username, verified, verified_type, withheld. Note: id, name, and username are returned by default.
Tweet attributes to include when using expansions=pinned_tweet_id. Only used to get additional fields for the expanded pinned tweet. Valid values include: id, text, created_at, public_metrics, author_id, entities, etc.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
No publicly available marketplace agent is found using this tool yet. There are 83 agents privately built on Nagent that already use Twitter.
Build on Nagent
Connect Twitter to any Nagent agent in minutes — no API key management, no boilerplate. Just configure and deploy.
The five questions agent builders ask before adopting a new integration.
Open the External Integrations panel inside Nagent (app.nagent.ai/externalIntegration), find Twitter, and click "Connect Now." You'll authenticate with OAuth — Nagent handles credential storage and refresh automatically. Once connected, Twitter is available to any agent in your workspace.
No. Nagent provides no-code integration for every tool. Once Twitter is connected, you configure its 79 actions directly in the agent builder UI — no API calls, no boilerplate, no schema management.
Helix — Nagent's agentic agent builder — lets you drop Twitter steps into any workflow visually. Pick an action (e.g., one of those listed above), fill in the inputs (Helix knows the required vs. optional schema for each parameter), and connect it to upstream/downstream steps. Triggers run as the entry point of an agent, so when a Twitter event fires, the agent kicks off automatically.
Every Twitter action and trigger ships with a fully-typed schema — input parameters with name, type, required flag, and description, plus the output payload shape. The schemas are documented in the sections above. Helix uses these schemas to validate your configuration at build time and to type-check the data flowing between steps.
Yes. While Twitter ships with 79 pre-built social media accounts actions, you can layer custom logic around them inside Helix — pre/post-processing steps, conditional branches, retries, or stitching Twitter together with other connected tools. For deeper customization, talk to our team about Nagent's Agentic AI Lab — forward-deployed engineers who build Twitter-based workflows tailored to your business.