# Twitter

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.

- **Category:** social media accounts
- **Auth:** OAUTH2
- **Composio Managed App Available?** No
- **Tools:** 80
- **Triggers:** 0
- **Slug:** `TWITTER`
- **Version:** 20260316_00

## Frequently Asked Questions

### Why are Composio managed credentials no longer available for Twitter?

As of February 2026, Composio managed credentials for the Twitter toolkit have been removed. You must now bring your own Twitter API credentials. To migrate:

1. Create a Twitter Developer account and obtain API credentials from the [Twitter Developer Portal](https://developer.x.com/en/portal/dashboard).
2. Set up a custom auth configuration with your credentials in Composio.

If you were relying on managed credentials, your Twitter integrations will stop working until you configure your own. See the [changelog entry](/docs/changelog/2026/02/12) for full details.

### Why am I getting rate limit or "UsageCapExceeded" errors on Twitter?

Twitter enforces strict rate limits per app. Use your own OAuth app with appropriate rate limit allocations for production workloads.

### Why can't I access certain Twitter API endpoints?

Twitter enforces plan-based access tiers. Check your project's product and plan for the required permissions at the [Twitter Developer Portal](https://developer.x.com/en/portal/products).

### Why am I getting 403 errors on Twitter API calls?

Your developer account or project may not have the required access level for the endpoint. Check your enrollment and access tier in the Twitter Developer Portal.

---

## Tools

### Add a list member

**Slug:** `TWITTER_ADD_LIST_MEMBER`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier of the Twitter List to which the user will be added. |
| `user_id` | string | Yes | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Add post to bookmarks

**Slug:** `TWITTER_ADD_POST_TO_BOOKMARKS`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | 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. |
| `tweet_id` | string | Yes | Unique identifier (string) of the Tweet to be bookmarked, provided in the request body. String type used to support large integer values. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Append Media Upload

**Slug:** `TWITTER_APPEND_MEDIA_UPLOAD`

Append 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The media identifier for the media to perform the append operation. |
| `media` | string | Yes | Base64-encoded media data chunk to append. This should be a segment of the media file being uploaded in the chunked upload process. |
| `segment_index` | integer | Yes | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get bookmarks by user

**Slug:** `TWITTER_BOOKMARKS_BY_USER`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | No | 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. |
| `expansions` | array | No | 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. |
| `max_results` | integer | No | The maximum number of bookmarked Tweets to return per page, between 1 and 100 inclusive. |
| `poll_fields` | array | No | 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. |
| `user_fields` | array | No | 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. |
| `media_fields` | array | No | 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. |
| `place_fields` | array | No | 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. |
| `tweet_fields` | array | No | 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` | string | No | 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. |
| `composio_execution_message` | string | No | Internal field for execution messages. Do not set manually. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create activity subscription

**Slug:** `TWITTER_CREATE_ACTIVITY_SUBSCRIPTION`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tag` | string | No | Optional tag to label this subscription (1-200 characters). |
| `filter` | object | Yes | Filter criteria specifying which events to receive. Must include at least one of 'user_id' or 'keyword'. |
| `event_type` | string ("profile.update.bio" | "profile.update.profile_picture" | "profile.update.banner_picture" | "profile.update.screenname" | "profile.update.geo" | "profile.update.url" | "profile.update.verified_badge" | "profile.update.affiliate_badge" | "profile.update.handle" | "news.new" | "follow.follow" | "follow.unfollow" | "spaces.start" | "spaces.end" | "chat.received" | "chat.sent" | "ProfileBioUpdate" | "ProfilePictureUpdate" | "ProfileBannerPictureUpdate" | "ProfileScreennameUpdate" | "ProfileGeoUpdate" | "ProfileUrlUpdate" | "ProfileVerifiedBadgeUpdate" | "NewsNew" | "FollowFollow" | "FollowUnfollow") | Yes | The type of activity event to subscribe to. Examples: 'profile.update.bio', 'follow.follow', 'spaces.start'. |
| `webhook_id` | string | No | The unique identifier of this webhook config. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create compliance job

**Slug:** `TWITTER_CREATE_COMPLIANCE_JOB`

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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Optional. A user-defined name for the compliance job. Must be unique and up to 64 characters. |
| `type` | string ("tweets" | "users") | Yes | Type of compliance job: 'tweets' for Tweet IDs or 'users' for user IDs. |
| `resumable` | boolean | No | If true, returns a pre-signed URL for resumable uploads, useful for large ID lists. Defaults to false if not specified. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create group DM conversation

**Slug:** `TWITTER_CREATE_DM_CONVERSATION`

Creates 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `message` | object | Yes | 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. |
| `participant_ids` | array | Yes | 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. |
| `conversation_type` | string ("Group") | Yes | REQUIRED. Specifies the type of conversation to be created. Must be 'Group' for this action. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create a list

**Slug:** `TWITTER_CREATE_LIST`

Creates 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Name for the List (1-25 characters, must start with a letter, and can only contain letters, numbers, hyphens, or underscores). |
| `private` | boolean | No | Sets List visibility: True for private, False for public. |
| `description` | string | No | Brief description for the List (up to 100 characters). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create a post

**Slug:** `TWITTER_CREATION_OF_A_POST`

Creates 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `text` | string | No | Text content of the Tweet (max 280 weighted characters using Twitter's counting rules: most characters count as 1, emojis/CJK count as 2, URLs count as 23 regardless of length). 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. |
| `card_uri` | string | No | URI of a card to attach. Mutually exclusive with `quote_tweet_id`, `poll` parameters, `media` parameters, and `direct_message_deep_link`. |
| `nullcast` | boolean | No | Marks the Tweet as a promoted-only post, not appearing in public timelines or served to followers. |
| `geo_place_id` | string | No | Twitter Place ID to associate with the Tweet. |
| `poll_options` | array | No | List of 2 to 4 poll options (max 25 characters each). Required if creating a poll. Mutually exclusive with `card_uri`. |
| `quote_tweet_id` | string | No | 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`. |
| `reply_settings` | string ("following" | "mentionedUsers" | "subscribers") | No | 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). |
| `media_media_ids` | array | No | 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`. |
| `poll_reply_settings` | string | No | Specifies who can reply to the poll Tweet: 'following' or 'mentionedUsers'. Mutually exclusive with `card_uri`. |
| `media_tagged_user_ids` | array | No | User IDs to tag in media; tagged users must have enabled photo tagging. Mutually exclusive with `card_uri`. |
| `poll_duration_minutes` | integer | No | Poll duration in minutes (5-10080). Required if `poll_options` are provided. Mutually exclusive with `card_uri`. |
| `direct_message_deep_link` | string | No | Deep link to a private Direct Message conversation. Mutually exclusive with `card_uri`. |
| `for_super_followers_only` | boolean | No | Restricts Tweet visibility to the author's Super Followers. |
| `reply_in_reply_to_tweet_id` | string | No | 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. |
| `reply_exclude_reply_user_ids` | array | No | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete direct message

**Slug:** `TWITTER_DELETE_DM`

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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `event_id` | string | Yes | The unique identifier of the Direct Message event to be deleted. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete list

**Slug:** `TWITTER_DELETE_LIST`

Permanently 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier of the Twitter List to be deleted. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get followers by user id

**Slug:** `TWITTER_FOLLOWERS_BY_USER_ID`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The ID of the User to lookup. |
| `expansions` | array | No | Array of fields to expand. |
| `max_results` | integer | No | The maximum number of results. |
| `user_fields` | array | No | Array of User fields to display. |
| `tweet_fields` | array | No | Array of Tweet fields to display. |
| `pagination_token` | string | No | Token for paginating results. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get following by user ID

**Slug:** `TWITTER_FOLLOWING_BY_USER_ID`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier of the Twitter User whose following list is to be retrieved. |
| `expansions` | array | No | Objects to expand (e.g., `pinned_tweet_id`) to include related data alongside user information. |
| `max_results` | integer | No | The maximum number of users to return per page, typically between 1 and 1000. Defaults to 100 if not specified. |
| `user_fields` | array | No | User fields to include for each followed user, providing additional details. |
| `tweet_fields` | array | No | Tweet fields to include for expanded tweet-related objects (e.g., `pinned_tweet_id`). |
| `pagination_token` | string | No | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Follow a list

**Slug:** `TWITTER_FOLLOW_LIST`

Allows 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | 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. |
| `list_id` | string | Yes | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Follow a user

**Slug:** `TWITTER_FOLLOW_USER`

Allows 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | No | The User ID of the authenticated user initiating the follow request. If not provided, it will be automatically fetched from the authenticated session. |
| `target_user_id` | string | Yes | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Search full archive of tweets

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | 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. |
| `end_time` | string | No | 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'. |
| `since_id` | string | No | Returns results with a Tweet ID numerically greater (more recent) than the specified ID. |
| `until_id` | string | No | Returns results with a Tweet ID numerically less (older) than the specified ID. |
| `expansions` | array | No | Specifies which objects to expand in the response for more details. |
| `next_token` | string | No | A token obtained from a previous response's 'meta.next_token' field to retrieve the next page of results. Do not modify this value. |
| `sort_order` | string ("recency" | "relevancy") | No | Specifies the order in which to return results. 'recency' returns the most recent Tweets first, 'relevancy' returns Tweets based on relevance. |
| `start_time` | string | No | 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'. |
| `max_results` | integer | No | The maximum number of search results to return per request. Must be between 10 and 500. |
| `poll_fields` | array | No | Specifies which poll fields to include if 'attachments.poll_ids' is expanded. |
| `user_fields` | array | No | 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. |
| `media_fields` | array | No | Specifies which media fields to include if 'attachments.media_keys' is expanded. |
| `place_fields` | array | No | Specifies which place fields to include if 'geo.place_id' is expanded. |
| `tweet_fields` | array | No | Specifies which Tweet fields to include in the response. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get users blocked by user ID

**Slug:** `TWITTER_GET_BLOCKED_USERS`

Retrieves 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | 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. |
| `expansions` | array | No | Related objects to expand and include, like `pinned_tweet_id` for full Tweet objects. Sent as a comma-separated string to the API. |
| `max_results` | integer | No | Maximum number of blocked users per page (1-100). API defaults to 100 if unspecified. |
| `user_fields` | array | No | User fields to include for each blocked user. Sent as a comma-separated string to the API (e.g., 'created_at,description'). |
| `tweet_fields` | array | No | Fields to include for expanded Tweet objects (e.g., via `expansions=pinned_tweet_id`). Sent as a comma-separated string to the API. |
| `pagination_token` | string | No | Token for fetching the next page of results, obtained from `meta.next_token` of a previous response. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Retrieve compliance job by id

**Slug:** `TWITTER_GET_COMPLIANCE_JOB`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier of the Compliance Job to retrieve. |
| `compliance_job_fields` | array | No | Specifies fields for the ComplianceJob object in the response; if omitted, a default set is returned. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Retrieve compliance jobs

**Slug:** `TWITTER_GET_COMPLIANCE_JOBS`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string ("tweets" | "users") | Yes | Specifies the type of compliance job to retrieve (tweets or users). |
| `status` | string ("complete" | "created" | "failed" | "in_progress") | No | Filters compliance jobs by status; if omitted, jobs of all statuses for the specified type are returned. |
| `compliance_job_fields` | array | No | Specific `ComplianceJob` fields to include in the response; if omitted, a default set of fields is returned. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get DM events for a DM conversation

**Slug:** `TWITTER_GET_DM_CONVERSATION_EVENTS`

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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `expansions` | array | No | Objects to expand and include. E.g., `sender_id` includes the full User object for each DM sender. |
| `event_types` | array | No | DM event types to include. If unspecified, all types are returned. |
| `max_results` | integer | No | Maximum DM events per page (1-100). |
| `user_fields` | array | No | Fields for User objects if `expansions` includes `sender_id` or `participant_ids`. Default: basic user fields. |
| `media_fields` | array | No | Fields for Media objects if `expansions` includes `attachments.media_keys`. Default: basic media fields. |
| `tweet_fields` | array | No | Fields for Tweet objects if `expansions` includes `referenced_tweets.id`. Default: basic tweet fields. |
| `participant_id` | string | Yes | User ID of the other participant in the one-to-one DM conversation. |
| `dm_event_fields` | array | No | Fields for each DM event object. Default: 'id', 'event_type'. |
| `pagination_token` | string | No | Token from `meta.next_token` or `meta.previous_token` of a prior response to fetch a specific results page. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get DM events by ID

**Slug:** `TWITTER_GET_DM_EVENT`

Fetches 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `event_id` | string | Yes | The unique identifier of the Direct Message event to retrieve. |
| `expansions` | array | No | Related objects to expand and include in the response. |
| `user_fields` | array | No | User fields to include for user objects in the response. |
| `media_fields` | array | No | Media fields to include for media objects in the response. |
| `tweet_fields` | array | No | Tweet fields to include for tweet objects in the response. |
| `dm_event_fields` | array | No | DmEvent fields to include in the response. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Lookup list by ID

**Slug:** `TWITTER_GET_LIST`

Returns 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier of the Twitter List to retrieve. This is a numeric string representing the List ID. |
| `expansions` | array | No | 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. |
| `list_fields` | array | No | 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. |
| `user_fields` | array | No | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get list followers

**Slug:** `TWITTER_GET_LIST_FOLLOWERS`

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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Unique identifier of the Twitter List for which to retrieve followers. |
| `expansions` | array | No | Fields to expand for more detailed information on related entities (e.g., pinned tweets, affiliated users). |
| `max_results` | integer | No | Maximum number of user results per page. |
| `user_fields` | array | No | User fields to include in the response for additional details on each follower. |
| `tweet_fields` | array | No | Tweet fields to include if tweet objects (e.g., pinned_tweet_id) are expanded. |
| `pagination_token` | string | No | Pagination token from a previous response's `next_token` to retrieve the next page. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Fetch list members by id

**Slug:** `TWITTER_GET_LIST_MEMBERS`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier of the Twitter List. |
| `expansions` | array | No | 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. |
| `max_results` | integer | No | The maximum number of list members to return per page. Values can range from 1 to 100. |
| `user_fields` | array | No | Specifies which additional user details to return for each list member. |
| `tweet_fields` | array | No | 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. |
| `pagination_token` | string | No | Token for fetching a specific page of results. Obtained from the `next_token` or `previous_token` field in the response's `meta` object. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Media Upload Status

**Slug:** `TWITTER_GET_MEDIA_UPLOAD_STATUS`

Get 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `media_id` | string | Yes | Numeric media ID (1-19 digits) returned from a previous media upload. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get muted users

**Slug:** `TWITTER_GET_MUTED_USERS`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The User ID of the authenticated user whose muted users are to be retrieved. This ID must correspond to an existing X user. |
| `expansions` | array | No | 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. |
| `max_results` | integer | No | The maximum number of user objects to return per page. Default is 100, minimum is 1, maximum is 1000. |
| `user_fields` | array | No | 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`). |
| `tweet_fields` | array | No | 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. |
| `pagination_token` | string | No | A token obtained from a previous response, used to fetch the next page of results. If not provided, the first page is returned. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Fetch OpenAPI specification

**Slug:** `TWITTER_GET_OPENAPI_SPEC`

Fetches the OpenAPI specification (JSON) for Twitter's API v2, used to programmatically understand the API's structure for developing client libraries or tools.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Post analytics

**Slug:** `TWITTER_GET_POST_ANALYTICS`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ids` | array | Yes | A comma-separated list of Post IDs (up to 100 allowed). Each ID should be a numeric string matching pattern ^[0-9]{1,19}$. |
| `end_time` | string | Yes | The UTC timestamp representing the end of the time range in format YYYY-MM-DDTHH:mm:ssZ. Must be a valid RFC3339 datetime string. |
| `start_time` | string | Yes | The UTC timestamp representing the start of the time range in format YYYY-MM-DDTHH:mm:ssZ. Must be a valid RFC3339 datetime string. |
| `granularity` | string ("hourly" | "daily" | "weekly" | "total") | No | The granularity for the analytics results. Determines how the metrics are aggregated over the time range. |
| `analytics.fields` | array | No | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get post retweeters

**Slug:** `TWITTER_GET_POST_RETWEETERS_ACTION`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier of the Post (Tweet) for which to retrieve retweeting users. This ID must be for an existing public Post. |
| `expansions` | array | No | Objects to expand and include, such as pinned Tweets of retweeters. |
| `max_results` | integer | No | Maximum number of user objects per page (1-100, default 100). |
| `user_fields` | array | No | User fields to include for each user who retweeted the Post. |
| `tweet_fields` | array | No | Tweet fields for expanded Tweet objects (e.g., when `expansions` includes 'pinned_tweet_id'). |
| `pagination_token` | string | No | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Retrieve retweets of a post

**Slug:** `TWITTER_GET_POST_RETWEETS`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier of the Tweet for which to retrieve Retweets. |
| `expansions` | array | No | Specifies objects to expand for related data on Retweeting Tweets or their authors (e.g., `author_id`, `referenced_tweets.id`). |
| `max_results` | integer | No | Specifies the maximum number of Retweets to return, between 10 and 100. |
| `poll_fields` | array | No | Poll fields to include if `expansions` contains `attachments.poll_ids`. |
| `user_fields` | array | No | User fields for authors of Retweeting Tweets, applicable if `expansions` includes `author_id`. |
| `media_fields` | array | No | Media fields to include if `expansions` contains `attachments.media_keys`. |
| `place_fields` | array | No | Place fields to include if `expansions` contains `geo.place_id`. |
| `tweet_fields` | array | No | Specifies Tweet fields to include for additional information about the Retweeting Tweets. |
| `pagination_token` | string | No | Pagination token from a previous response's `meta.next_token` to request the next page of results. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Fetch tweet usage data

**Slug:** `TWITTER_GET_POST_USAGE`

Fetches 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `days` | integer | No | Specifies the number of days (1 to 90) to retrieve usage data for. Defaults to 7 days. |
| `usage_fields` | array | No | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get recent direct message events

**Slug:** `TWITTER_GET_RECENT_DM_EVENTS`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `expansions` | array | No | A comma separated list of fields to expand. |
| `event_types` | array | No | The set of event_types to include in the results. |
| `max_results` | integer | No | 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. |
| `user_fields` | array | No | A comma separated list of User fields to display. |
| `media_fields` | array | No | A comma separated list of Media fields to display. |
| `tweet_fields` | array | No | A comma separated list of Tweet fields to display. |
| `dm_event_fields` | array | No | A comma separated list of DmEvent fields to display. |
| `pagination_token` | string | No | This parameter is used to get a specified "page" of results. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Look up space by ID

**Slug:** `TWITTER_GET_SPACE_BY_ID`

Retrieves 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Unique identifier of the Twitter Space to retrieve. |
| `expansions` | array | No | Objects to expand in the response (e.g., `creator_id`). Customize with corresponding `*_fields`. See ExpansionsEnm0 for options. |
| `user_fields` | array | No | Fields for User objects expanded via `expansions` (e.g., if `creator_id` is expanded). See UserFieldsEnm0 for options. |
| `space_fields` | array | No | Fields to include for the Space object; defaults to a standard set if omitted. See SpaceFieldsEnm0 for options. |
| `topic_fields` | array | No | Fields for Topic objects expanded via `expansions` (e.g., if `topic_ids` is expanded). See TopicFieldsEnm0 for options. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Retrieve posts from a space

**Slug:** `TWITTER_GET_SPACE_POSTS`

Retrieves 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | 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. |
| `expansions` | array | No | 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. |
| `max_results` | integer | No | The maximum number of Tweets to fetch from the Space per request. Defaults to 100, which is also the maximum allowed. |
| `poll_fields` | array | No | A list of Poll fields to be included for polls, if 'attachments.poll_ids' is part of 'expansions'. |
| `user_fields` | array | No | A list of User fields to be included for user objects, if 'author_id' or other user-related fields are part of 'expansions'. |
| `media_fields` | array | No | A list of Media fields to be included for media content, if 'attachments.media_keys' is part of 'expansions'. |
| `place_fields` | array | No | A list of Place fields to be included for geo-tagged Tweets, if 'geo.place_id' is part of 'expansions'. |
| `tweet_fields` | array | No | A list of Tweet fields to be included in the response. By default, only 'id' and 'text' are returned for each Tweet. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get spaces by creator IDs

**Slug:** `TWITTER_GET_SPACES_BY_CREATORS`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_ids` | array | Yes | A list of User IDs whose Spaces will be retrieved. At least one User ID must be provided. |
| `expansions` | array | No | Specifies which related objects to expand for more detailed information in the response. |
| `user_fields` | array | No | Specifies which fields to return for User objects, applicable when User-related IDs (e.g., 'creator_id') are included in 'expansions'. |
| `space_fields` | array | No | Specifies which fields to return for each Space object. |
| `topic_fields` | array | No | Specifies which fields to return for Topic objects, applicable when 'topic_ids' is included in 'expansions'. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get space information by IDs

**Slug:** `TWITTER_GET_SPACES_BY_IDS`

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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ids` | array | Yes | Unique identifiers for the Twitter Spaces to retrieve. |
| `expansions` | array | No | Objects to expand and include their full details (e.g., 'creator_id', 'host_ids'). See `ExpansionsEnm0` for options. |
| `user_fields` | array | No | Specific fields for User objects included via expansions (e.g., if 'creator_id' is in 'expansions'). See `UserFieldsEnm0` for options. |
| `space_fields` | array | No | Specific fields to return for each Space object; omits to return default fields. See `SpaceFieldsEnm0` for options. |
| `topic_fields` | array | No | Specific fields for Topic objects included via expansions (e.g., if 'topic_ids' is in 'expansions'). See `TopicFieldsEnm0` for options. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Fetch space ticket buyers list

**Slug:** `TWITTER_GET_SPACE_TICKET_BUYERS`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier of the Space for which to retrieve the list of ticket buyers. |
| `expansions` | array | No | Objects to expand in the response for more detailed information (e.g., `pinned_tweet_id` to include the full Tweet object). |
| `max_results` | integer | No | Maximum number of buyer records to return per page. |
| `user_fields` | array | No | User fields to include for each buyer, providing additional details. Refer to the User object schema for available fields. |
| `tweet_fields` | array | No | Tweet fields to include when Tweet objects are expanded. Refer to the Tweet object schema for available fields. |
| `pagination_token` | string | No | Token from a previous response to fetch the subsequent page of results. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Look up user by ID

**Slug:** `TWITTER_GET_USER_BY_ID`

Retrieves 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | 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. |
| `expansions` | array | No | Linked entities to expand (e.g., `pinned_tweet_id` for the full pinned Tweet). See `ExpansionsEnm0` for options. |
| `user_fields` | array | No | Specifies which user attributes to return. See `UserFieldsEnm0` for options. |
| `tweet_fields` | array | No | Specifies which tweet attributes to return for expanded tweets. See `TweetFieldsEnm0` for options. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get user's followed lists

**Slug:** `TWITTER_GET_USER_FOLLOWED_LISTS`

Returns metadata (not Tweets) for lists a specific Twitter user follows, optionally including expanded owner details.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier of the User whose followed lists are to be retrieved. |
| `expansions` | array | No | 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. |
| `list_fields` | array | No | A list of fields to include for each List object in the response. Refer to `ListFieldsEnm0` for all available fields. |
| `max_results` | integer | No | The maximum number of List results to be returned per page. Default is 100. |
| `user_fields` | array | No | A list of fields to include for each User object, applicable if `expansions` includes `owner_id`. Refer to `UserFieldsEnm0` for available fields. |
| `pagination_token` | string | No | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get a user's list memberships

**Slug:** `TWITTER_GET_USER_LIST_MEMBERSHIPS`

Retrieves 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier of the target User whose List memberships are to be retrieved. |
| `expansions` | array | No | 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`. |
| `list_fields` | array | No | 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. |
| `max_results` | integer | No | Specifies the maximum number of List memberships to return in a single page. Valid range: 1-100. Default: 100. |
| `user_fields` | array | No | 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. |
| `pagination_token` | string | No | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get a user's owned lists

**Slug:** `TWITTER_GET_USER_OWNED_LISTS`

Call this action to retrieve Lists created (owned) by a specific Twitter user, not Lists they follow or are subscribed to.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | User ID of the Twitter User whose owned Lists are to be retrieved. |
| `expansions` | array | No | Set to `['owner_id']` to include the User object of the List's owner. |
| `list_fields` | array | No | Specific fields to return for each List object (e.g., `created_at`, `description`). |
| `max_results` | integer | No | Maximum number of List results per page. Allowed values: 1-100. Default: 100. |
| `user_fields` | array | No | Specific fields for User objects if `expansions` includes `owner_id` (e.g., `public_metrics`, `created_at`). |
| `pagination_token` | string | No | Token from `meta.next_token` of a previous response to fetch the next page. Omit for the first page. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get a user's pinned lists

**Slug:** `TWITTER_GET_USER_PINNED_LISTS`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier of the User whose pinned Lists are to be retrieved. |
| `expansions` | array | No | 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. |
| `list_fields` | array | No | A comma-separated list of List fields to return for each List object. Select desired fields from `ListFieldsEnm0`. |
| `user_fields` | array | No | A comma-separated list of User fields to return. This is applicable when `expansions` includes `owner_id`. Select desired fields from `UserFieldsEnm0`. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Look up users by IDs

**Slug:** `TWITTER_GET_USERS_BY_IDS`

Retrieves detailed information for specified X (formerly Twitter) user IDs, optionally customizing returned fields and expanding related entities.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ids` | array | Yes | 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'). |
| `expansions` | array | No | Objects to expand in the response (e.g., 'pinned_tweet_id'). See ExpansionsEnm0 for options. |
| `user_fields` | array | No | Specific user fields to return. See UserFieldsEnm0 for options. |
| `tweet_fields` | array | No | Tweet fields to return for expanded tweet objects. See TweetFieldsEnm0 for options. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Set reply visibility

**Slug:** `TWITTER_HIDE_REPLIES`

Hides 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `hidden` | boolean | Yes | Set to `true` to hide the reply, `false` to unhide. |
| `tweet_id` | string | Yes | Unique identifier of the reply Tweet to hide or unhide. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Initialize Media Upload

**Slug:** `TWITTER_INITIALIZE_MEDIA_UPLOAD`

Initialize 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `shared` | boolean | No | Whether this media is shared or not. Optional parameter. |
| `media_type` | string ("video/mp4" | "video/webm" | "video/mp2t" | "video/quicktime" | "text/srt" | "text/vtt" | "image/jpeg" | "image/gif" | "image/bmp" | "image/png" | "image/webp" | "image/pjpeg" | "image/tiff" | "model/gltf-binary" | "model/vnd.usdz+zip") | Yes | The MIME type of the media file to be uploaded (e.g., 'video/mp4', 'image/png'). This determines how Twitter processes the file. |
| `total_bytes` | integer | Yes | The total size of the media file in bytes. Must be between 0 and 17179869184 (16 GB). |
| `media_category` | string ("amplify_video" | "tweet_gif" | "tweet_image" | "tweet_video" | "dm_gif" | "dm_image" | "dm_video" | "subtitles") | No | Media category for upload |
| `additional_owners` | array | No | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List post likers

**Slug:** `TWITTER_LIST_POST_LIKERS`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier of the Post (Tweet) for which to retrieve liking users. |
| `expansions` | array | No | Fields to expand for related objects, like a user's pinned Tweet. Example: ['pinned_tweet_id']. |
| `max_results` | integer | No | 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` | array | No | User fields to retrieve for each liking user. Example: ['created_at', 'description']. |
| `tweet_fields` | array | No | Tweet fields to retrieve for expanded Tweet objects (e.g., if `expansions` includes `pinned_tweet_id`). Example: ['created_at', 'public_metrics']. |
| `pagination_token` | string | No | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List posts timeline by list ID

**Slug:** `TWITTER_LIST_POSTS_TIMELINE_BY_LIST_ID`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier of the Twitter List from which to retrieve Tweets. |
| `expansions` | array | No | Specifies which related objects to expand and include in the response (e.g., author data, media details). |
| `max_results` | integer | No | The maximum number of Tweets to return per request. Must be between 1 and 100. |
| `poll_fields` | array | No | Specifies which Poll object fields to include if 'attachments.poll_ids' is in 'expansions'. |
| `user_fields` | array | No | Specifies which User object fields to include if 'author_id' or other user references are in 'expansions'. |
| `media_fields` | array | No | Specifies which Media object fields to include if 'attachments.media_keys' is in 'expansions'. |
| `place_fields` | array | No | Specifies which Place object fields to include if 'geo.place_id' is in 'expansions'. |
| `tweet_fields` | array | No | Specifies which Tweet object fields to include in the response. |
| `pagination_token` | string | No | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Mute user by ID

**Slug:** `TWITTER_MUTE_USER`

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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | No | 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. |
| `target_user_id` | string | Yes | The User ID of the user to be muted. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Pin a list

**Slug:** `TWITTER_PIN_LIST`

Pins 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The ID of the authenticated User pinning the List. |
| `list_id` | string | Yes | The unique identifier of the List to be pinned. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete tweet

**Slug:** `TWITTER_POST_DELETE_BY_POST_ID`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier of the Tweet to be deleted. This ID must correspond to a Tweet authored by the authenticated user. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Look up post by id

**Slug:** `TWITTER_POST_LOOKUP_BY_POST_ID`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | 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. |
| `expansions` | array | No | 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_fields` | array | No | 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_fields` | array | No | 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_fields` | array | No | 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_fields` | array | No | 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_fields` | array | No | Tweet attributes to include for additional details about the Tweet. Accepts a list of field names or a comma-separated string. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get tweets by IDs

**Slug:** `TWITTER_POST_LOOKUP_BY_POST_IDS`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ids` | array | Yes | 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'. |
| `expansions` | array | No | 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. |
| `poll_fields` | array | No | A comma-separated list of Poll fields to include for poll attachments. Can be provided as a string (comma-separated) or a list. |
| `user_fields` | array | No | A comma-separated list of User fields to include for user objects. Can be provided as a string (comma-separated) or a list. |
| `media_fields` | array | No | A comma-separated list of Media fields to include for media attachments. Can be provided as a string (comma-separated) or a list. |
| `place_fields` | array | No | A comma-separated list of Place fields to include for geo-tagged Tweets. Can be provided as a string (comma-separated) or a list. |
| `tweet_fields` | array | No | A comma-separated list of Tweet fields to include in the response. Can be provided as a string (comma-separated) or a list. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Search recent tweets

**Slug:** `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`) 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | 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. |
| `end_time` | string | No | 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. |
| `since_id` | string | No | Returns Tweets more recent than this ID. IMPORTANT: Cannot be used with `start_time` or `end_time` - these are mutually exclusive time range filters. |
| `until_id` | string | No | Returns Tweets older than this ID. IMPORTANT: Cannot be used with `start_time` or `end_time` - these are mutually exclusive time range filters. |
| `expansions` | array | No | Expansions to include additional objects like users, media, polls, etc. |
| `next_token` | string | No | Token from `meta.next_token` of a previous response for pagination; do not modify. |
| `sort_order` | string ("recency" | "relevancy") | No | Order of results: 'recency' (most recent first) or 'relevancy'. |
| `start_time` | string | No | 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. |
| `max_results` | integer | No | 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` | array | No | Poll fields to include when poll IDs are expanded. |
| `user_fields` | array | No | 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` | array | No | Media fields to include when media keys are expanded. |
| `place_fields` | array | No | Place fields to include when place IDs are expanded. |
| `tweet_fields` | array | No | Additional tweet object fields to include in the response. |
| `pagination_token` | string | No | Alternative pagination token from a previous `meta.next_token`; `next_token` is preferred if both are provided. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Remove a list member

**Slug:** `TWITTER_REMOVE_LIST_MEMBER`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier of the Twitter List from which a member will be removed. |
| `user_id` | string | Yes | The unique identifier (ID) of the Twitter user to be removed from the specified List. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Remove a bookmarked post

**Slug:** `TWITTER_REMOVE_POST_FROM_BOOKMARKS`

Removes 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | No | 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. |
| `tweet_id` | string | Yes | The ID of the Tweet to be removed from the user's bookmarks. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Retrieve DM conversation events

**Slug:** `TWITTER_RETRIEVE_DM_CONVERSATION_EVENTS`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | 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'). |
| `expansions` | array | No | A comma separated list of fields to expand. |
| `event_types` | array | No | The set of event_types to include in the results. |
| `max_results` | integer | No | The maximum number of results. |
| `user_fields` | array | No | A comma separated list of User fields to display. |
| `media_fields` | array | No | A comma separated list of Media fields to display. |
| `tweet_fields` | array | No | A comma separated list of Tweet fields to display. |
| `dm_event_fields` | array | No | A comma separated list of DmEvent fields to display. |
| `pagination_token` | string | No | This parameter is used to get a specified "page" of results. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Retrieve posts that quote a post

**Slug:** `TWITTER_RETRIEVE_POSTS_THAT_QUOTE_A_POST`

Retrieves Tweets that quote a specified Tweet, requiring a valid Tweet ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Unique identifier of the Tweet whose quoting Tweets you would like to retrieve. |
| `exclude` | array | No | Specifies whether to exclude replies or retweets from the results. |
| `expansions` | array | No | Fields to expand in the response, such as 'author_id' to include the author's user object. |
| `max_results` | integer | No | Maximum number of results to return per page (range: 10-100). |
| `poll_fields` | array | No | Specific Poll fields to include in the response if poll objects are present. |
| `user_fields` | array | No | Specific User fields to include if user objects are present (e.g., through expansions). |
| `media_fields` | array | No | Specific Media fields to include in the response if media objects are present. |
| `place_fields` | array | No | Specific Place fields to include in the response if place objects are present. |
| `tweet_fields` | array | No | Specific Tweet fields to include in the response. |
| `pagination_token` | string | No | Token for retrieving a specific page of results, typically the `next_token` from a previous response. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Retrieve liked tweets by user ID

**Slug:** `TWITTER_RETURNS_POST_OBJECTS_LIKED_BY_THE_PROVIDED_USER_ID`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Twitter user ID whose liked Tweets are to be retrieved. |
| `expansions` | array | No | Objects to expand, e.g., `author_id`, `attachments.media_keys`, for richer data. |
| `max_results` | integer | No | Maximum liked Tweets per page. |
| `poll_fields` | array | No | Poll fields to include when `attachments.poll_ids` is in `expansions`. |
| `user_fields` | array | No | User fields for Tweet authors or other user objects when `expansions` includes them. |
| `media_fields` | array | No | Media fields to include when `attachments.media_keys` is in `expansions`. |
| `place_fields` | array | No | Place fields to include when `geo.place_id` is in `expansions`. |
| `tweet_fields` | array | No | Specific Tweet fields to include. API provides a default set if omitted. |
| `pagination_token` | string | No | Token from a previous response to fetch the next page. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Retweet post

**Slug:** `TWITTER_RETWEET_POST`

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 to retweet.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tweet_id` | string | Yes | The ID of the Tweet to be retweeted. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get full archive search counts

**Slug:** `TWITTER_SEARCH_FULL_ARCHIVE_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, and `since_id`/`until_id` cannot be used with `start_time`/`end_time`.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search query for matching Tweets using Twitter's V2 filtering syntax (see official Twitter API documentation for syntax and length). |
| `end_time` | string | No | 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. |
| `since_id` | string | No | Count Tweets more recent than this ID. Cannot be used with `start_time` or `end_time`. |
| `until_id` | string | No | Count Tweets older than this ID. Cannot be used with `start_time` or `end_time`. |
| `next_token` | string | No | Token from a previous response to fetch the next page of results. Use as-is. |
| `start_time` | string | No | 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. |
| `granularity` | string ("day" | "hour" | "minute") | No | Time period granularity for aggregating search count results. |
| `pagination_token` | string | No | Pagination token, typically `next_token` in Twitter API v2. Use as-is. |
| `search_count_fields` | array | No | Specifies which fields to return for each search count object; default fields are returned if unspecified. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Fetch recent tweet counts

**Slug:** `TWITTER_SEARCH_RECENT_COUNTS`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | 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 |
| `end_time` | string | No | 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. |
| `since_id` | string | No | Returns counts for Tweets created more recently than the specified Tweet ID. This helps to paginate results chronologically. |
| `until_id` | string | No | Returns counts for Tweets created older than the specified Tweet ID. This helps to paginate results chronologically. |
| `next_token` | string | No | A token obtained from a previous response to fetch the next page of results. Do not modify this value. |
| `start_time` | string | No | 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. |
| `granularity` | string ("day" | "hour" | "minute") | No | The time period granularity for aggregating search counts. |
| `pagination_token` | string | No | 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. |
| `search_count_fields` | array | No | A list of fields to include in each search count object. Available fields: 'end', 'start', 'tweet_count'. If unspecified, default fields are returned. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Search for spaces

**Slug:** `TWITTER_SEARCH_SPACES`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | The text query to search for in Space titles and descriptions. |
| `state` | string ("all" | "live" | "scheduled") | No | Filters Spaces by their state (e.g., 'live', 'scheduled'). |
| `expansions` | array | No | 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'). |
| `max_results` | integer | No | The maximum number of Space results to return in a single response. Values must be between 1 and 100, inclusive. |
| `user_fields` | array | No | Specifies fields for expanded User objects (e.g., 'username', 'public_metrics'). Omitting this returns a default set of User fields. |
| `space_fields` | array | No | Specifies fields to include for each Space object (e.g., 'id', 'title'). Omitting this returns a default set of fields. |
| `topic_fields` | array | No | Specifies fields for expanded Topic objects (e.g., 'id', 'name'). Omitting this returns a default set of Topic fields. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Send a new message to a user

**Slug:** `TWITTER_SEND_A_NEW_MESSAGE_TO_A_USER`

Sends 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `text` | string | No | Text content of the Direct Message. |
| `attachments` | array | No | Media attachments for the Direct Message. |
| `participant_id` | string | Yes | User ID of the recipient. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Send a new message to a DM conversation

**Slug:** `TWITTER_SEND_DM_TO_CONVERSATION`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `text` | string | No | Text content of the Direct Message. At least one of `text` or `attachments` is required. |
| `attachments` | array | No | A list of media attachments for the Direct Message, each specifying a `media_id`. At least one of `text` or `attachments` is required. |
| `dm_conversation_id` | string | Yes | Identifier of the DM conversation; can be a numeric string (group DM) or two user IDs hyphen-separated (one-on-one DM). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get tweets label stream

**Slug:** `TWITTER_STREAM_POST_LABELS`

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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `end_time` | string | No | Latest UTC timestamp (YYYY-MM-DDTHH:mm:ssZ) at which the stream will automatically close, ceasing event transmission. |
| `start_time` | string | No | Earliest UTC timestamp (YYYY-MM-DDTHH:mm:ssZ) from which to start streaming label events; disregards `backfill_minutes` if provided. |
| `backfill_minutes` | integer | No | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Unfollow a list

**Slug:** `TWITTER_UNFOLLOW_LIST`

Enables 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The ID of the user who is unfollowing the list. |
| `list_id` | string | Yes | The ID of the Twitter List to be unfollowed. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Unfollow user

**Slug:** `TWITTER_UNFOLLOW_USER`

Allows 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source_user_id` | string | No | 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. |
| `target_user_id` | string | No | The user ID of the user to unfollow. Alternatively, you can pass 'user_id' which will be treated as the target user ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Unlike post

**Slug:** `TWITTER_UNLIKE_POST`

Allows 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The ID of the authenticated user who is unliking the post. This user ID must match the user context of the authentication token. |
| `tweet_id` | string | Yes | The ID of the post (Tweet) that the user is requesting to unlike. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Unmute a user by user ID

**Slug:** `TWITTER_UNMUTE_USER`

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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `target_user_id` | string | Yes | User ID of the user to be unmuted. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Unpin a list

**Slug:** `TWITTER_UNPIN_LIST`

Unpins a List (specified by list_id) from the authenticated user's profile. The user ID is automatically retrieved if not provided.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | No | 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). |
| `list_id` | string | Yes | ID of the List to unpin from the authenticated user's profile. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Unretweet post

**Slug:** `TWITTER_UNRETWEET_POST`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | 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. |
| `source_tweet_id` | string | Yes | The unique identifier of the Post (Tweet) that the user is requesting to unretweet. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update list attributes

**Slug:** `TWITTER_UPDATE_LIST`

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

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier of the Twitter List to be updated. |
| `name` | string | No | New name for the List; must be a non-empty string if provided. |
| `private` | boolean | No | Controls the visibility of the List: `True` for private, `False` for public. |
| `description` | string | No | New description for the List; an empty string clears the existing description. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Upload Large Media

**Slug:** `TWITTER_UPLOAD_LARGE_MEDIA`

DEPRECATED: 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `media` | object | Yes | 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` | string ("tweet_image" | "tweet_gif" | "tweet_video" | "amplify_video") | No | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Upload Media

**Slug:** `TWITTER_UPLOAD_MEDIA`

Upload 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `media` | object | Yes | 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. |
| `media_type` | string | No | 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` | string ("tweet_image" | "dm_image" | "subtitles") | No | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get user reverse chronological timeline

**Slug:** `TWITTER_USER_HOME_TIMELINE_BY_USER_ID`

Retrieves 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | No | 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}$. |
| `exclude` | array | No | Tweet types to exclude from results. Accepts either a list ['replies', 'retweets'] or a comma-separated string 'replies,retweets'. |
| `end_time` | string | No | 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`. |
| `since_id` | string | No | Returns results with a Tweet ID more recent than the specified ID. Takes precedence over `start_time`. |
| `until_id` | string | No | Returns results with a Tweet ID older than the specified ID. Takes precedence over `end_time`. |
| `expansions` | array | No | 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'. |
| `start_time` | string | No | 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`. |
| `max_results` | integer | No | 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. |
| `poll_fields` | array | No | 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'. |
| `user_fields` | array | No | 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'. |
| `media_fields` | array | No | 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'. |
| `place_fields` | array | No | 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'. |
| `tweet_fields` | array | No | 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'. |
| `pagination_token` | string | No | Token from a previous response to fetch the next page of results. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Like a tweet

**Slug:** `TWITTER_USER_LIKE_POST`

Allows 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | 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). |
| `tweet_id` | string | Yes | The unique identifier of the Tweet to be liked. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Look up user by username

**Slug:** `TWITTER_USER_LOOKUP_BY_USERNAME`

Fetches 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `username` | string | Yes | 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. |
| `expansions` | array | No | Fields to expand for more detailed information on objects like `pinned_tweet_id` (includes full Tweet object). |
| `user_fields` | array | No | 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. |
| `tweet_fields` | array | No | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Look up users by username

**Slug:** `TWITTER_USER_LOOKUP_BY_USERNAMES`

Retrieves 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `usernames` | array | Yes | 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. |
| `expansions` | array | No | 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. |
| `user_fields` | array | No | 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. |
| `tweet_fields` | array | No | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get authenticated user

**Slug:** `TWITTER_USER_LOOKUP_ME`

Returns profile information for the currently authenticated X user, customizable via request fields.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `expansions` | array | No | 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_fields` | array | No | 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_fields` | array | No | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |