# X (Twitter) Your Toolhouse AI Worker can connect to X (Twitter) using 79 specialized tools. ## Auth Connection This service requires an auth connection to use its tools. You can set this up in your Toolhouse dashboard under [Auth Connections](https://toolhouse.app/auth-connections?authkit_slugs=twitter). ## Tools (79) ### `Twitter Add List Member` Integration name: **TWITTER\_ADD\_LIST\_MEMBER** Adds a user to a specified Twitter List; the list must be owned by the authenticated user. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"1455540726635843584"` | The unique identifier of the Twitter List to which the user will be added. | | `user_id` | string | ✅ | `"2244994945"` | 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}). | *** ### `Twitter Add Post To Bookmarks` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------- | ------ | :------: | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"2244994945"` | 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 | ✅ | `"1460323737035677698"` | Unique identifier (string) of the Tweet to be bookmarked, provided in the request body. String type used to support large integer values. | *** ### `Twitter Append Media Upload` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------------- | ------- | :------: | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `id` | string | ✅ | `"1146654567674912769"` | The media identifier for the media to perform the append operation. | | `media` | string | ✅ | — | 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 | ✅ | — | Zero-based index of the media segment being appended. Start with 0 for the first chunk and increment by 1 for each subsequent chunk. | *** ### `Twitter Bookmarks By User` Integration name: **TWITTER\_BOOKMARKS\_BY\_USER** Retrieves Tweets bookmarked by the authenticated user, where the provided User ID must match the authenticated user's ID. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------------------------- | ------- | :------: | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | string | | — | 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 | | `"author_id"` | 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 | | — | The maximum number of bookmarked Tweets to return per page, between 1 and 100 inclusive. | | `poll_fields` | array | | `"duration_minutes"` | 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 | | `"public_metrics"` | 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 | | `"url"` | 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 | | `"full_name"` | 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 | | `"created_at"` | 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 | | — | 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 | | — | Internal field for execution messages. Do not set manually. | *** ### `Twitter Create Activity Subscription` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------ | ------ | :------: | ----------------------- | ------------------------------------------------------------------------------------------------------------- | | `tag` | string | | `"production"` | Optional tag to label this subscription (1-200 characters). | | `filter` | object | ✅ | — | Filter criteria specifying which events to receive. Must include at least one of 'user\_id' or 'keyword'. | | `event_type` | string | ✅ | `"profile.update.bio"` | The type of activity event to subscribe to. Examples: 'profile.update.bio', 'follow\.follow', 'spaces.start'. | | `webhook_id` | string | | `"1146654567674912769"` | The unique identifier of this webhook config. | *** ### `Twitter Create Compliance Job` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ----------- | ------- | :------: | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | | `name` | string | | `"my-tweet-compliance-run-may-2024"` | Optional. A user-defined name for the compliance job. Must be unique and up to 64 characters. | | `type` | string | ✅ | `"tweets"` | Type of compliance job: 'tweets' for Tweet IDs or 'users' for user IDs. | | `resumable` | boolean | | `true` | If true, returns a pre-signed URL for resumable uploads, useful for large ID lists. Defaults to false if not specified. | *** ### `Twitter Create Dm Conversation` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------- | ------ | :------: | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `message` | object | ✅ | `"{\"text\": \"Hello everyone, welcome to the group!\"}"` | 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 | ✅ | `["1234567890","0987654321"]` | 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"` | REQUIRED. Specifies the type of conversation to be created. Must be 'Group' for this action. | *** ### `Twitter Create List` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------- | ------- | :------: | --------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `name` | string | ✅ | `"TechExperts"` | Name for the List (1-25 characters, must start with a letter, and can only contain letters, numbers, hyphens, or underscores). | | `private` | boolean | | — | Sets List visibility: True for private, False for public. | | `description` | string | | `"Tech News"` | Brief description for the List (up to 100 characters). | *** ### `Twitter Creation Of A Post` Integration name: **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" } #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------------------ | ------- | :------: | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | string | | `"Hello world!"` | Text content of the Tweet. Length limits are enforced by the X (Twitter) API and depend on the authenticated user's account tier — basic accounts are typically capped at 280 weighted characters (emojis/CJK count as 2, URLs count as 23 regardless of length), while X Premium accounts may post longer content. Validation is delegated to the API; over-length submissions return a 4xx error. At least one of `text`, `media_media_ids`, `card_uri`, `poll_options`, or `quote_tweet_id` must be provided with a non-empty value. Empty strings or whitespace-only strings are not valid. IMPORTANT: Do not include t.co URLs (Twitter's URL shortener) - use original URLs and Twitter will shorten them automatically. Also avoid URL placeholders like , \[URL], or {URL} which will be rejected. | | `card_uri` | string | | `"https://example.com/my-card"` | URI of a card to attach. Mutually exclusive with `quote_tweet_id`, `poll` parameters, `media` parameters, and `direct_message_deep_link`. | | `nullcast` | boolean | | `true` | Marks the Tweet as a promoted-only post, not appearing in public timelines or served to followers. | | `geo_place_id` | string | | `"df51dec6f4ee2b2c"` | Twitter Place ID to associate with the Tweet. | | `poll_options` | array | | `["Yes","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 | | `"1346889436626259968"` | 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"` | 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 | | `["1146032800000000000","1146032800000000001"]` | 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 | | `"following"` | Specifies who can reply to the poll Tweet: 'following' or 'mentionedUsers'. Mutually exclusive with `card_uri`. | | `media_tagged_user_ids` | array | | `["2244994945","783214"]` | User IDs to tag in media; tagged users must have enabled photo tagging. Mutually exclusive with `card_uri`. | | `poll_duration_minutes` | integer | | `60` | Poll duration in minutes (5-10080). Required if `poll_options` are provided. Mutually exclusive with `card_uri`. | | `direct_message_deep_link` | string | | `"https://twitter.com/messages/compose?recipient_id=12345&text=Hi"` | Deep link to a private Direct Message conversation. Mutually exclusive with `card_uri`. | | `for_super_followers_only` | boolean | | `true` | Restricts Tweet visibility to the author's Super Followers. | | `reply_in_reply_to_tweet_id` | string | | `"1346889436626259960"` | 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 | | `["123456789","987654321"]` | 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. | *** ### `Twitter Delete Dm` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------- | ------ | :------: | ----------------------- | ---------------------------------------------------------------- | | `event_id` | string | ✅ | `"1472690840046841856"` | The unique identifier of the Direct Message event to be deleted. | *** ### `Twitter Delete List` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | ----------------------- | -------------------------------------------------------- | | `id` | string | ✅ | `"1458007500858716160"` | The unique identifier of the Twitter List to be deleted. | *** ### `Twitter Followers By User Id` Integration name: **TWITTER\_FOLLOWERS\_BY\_USER\_ID** Retrieves a list of users who follow a specified public Twitter user ID. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | ------- | --------------------------------- | | `id` | string | ✅ | — | The ID of the User to lookup. | | `expansions` | array | | — | Array of fields to expand. | | `max_results` | integer | | — | The maximum number of results. | | `user_fields` | array | | — | Array of User fields to display. | | `tweet_fields` | array | | — | Array of Tweet fields to display. | | `pagination_token` | string | | — | Token for paginating results. | *** ### `Twitter Following By User Id` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"2244994945"` | The unique identifier of the Twitter User whose following list is to be retrieved. | | `expansions` | array | | `["pinned_tweet_id"]` | Objects to expand (e.g., `pinned_tweet_id`) to include related data alongside user information. | | `max_results` | integer | | `"100"` | The maximum number of users to return per page, typically between 1 and 1000. Defaults to 100 if not specified. | | `user_fields` | array | | `["created_at","description","profile_image_url"]` | User fields to include for each followed user, providing additional details. | | `tweet_fields` | array | | `["created_at","public_metrics","text"]` | Tweet fields to include for expanded tweet-related objects (e.g., `pinned_tweet_id`). | | `pagination_token` | string | | `"NGS0092ND09NSDFN"` | 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. | *** ### `Twitter Follow List` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"2244994945"` | 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 | ✅ | `"1455154772435103747"` | 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. | *** ### `Twitter Follow User` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------------- | ------ | :------: | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | | `"123456789"` | 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 | ✅ | `"2244994945"` | 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. | *** ### `Twitter Full Archive Search` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | -------------- | ------- | :------: | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | ✅ | `"#twitterdev OR @twitterdev"` | 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 | | `"2022-11-30T23:59:59Z"` | 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 | | `"1346889436626259968"` | Returns results with a Tweet ID numerically greater (more recent) than the specified ID. | | `until_id` | string | | `"1460323737035677698"` | Returns results with a Tweet ID numerically less (older) than the specified ID. | | `expansions` | array | | `["author_id","referenced_tweets.id"]` | Specifies which objects to expand in the response for more details. | | `next_token` | string | | `"7140dibdnow9c7btw423vh951v5cnqf09hyssx3h"` | 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"` | Specifies the order in which to return results. 'recency' returns the most recent Tweets first, 'relevancy' returns Tweets based on relevance. | | `start_time` | string | | `"2022-11-01T00:00:00Z"` | 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 | | `100` | The maximum number of search results to return per request. Must be between 10 and 500. | | `poll_fields` | array | | `["duration_minutes","options","end_datetime"]` | Specifies which poll fields to include if 'attachments.poll\_ids' is expanded. | | `user_fields` | array | | `["public_metrics","profile_image_url","created_at"]` | 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 | | `["url","preview_image_url","public_metrics"]` | Specifies which media fields to include if 'attachments.media\_keys' is expanded. | | `place_fields` | array | | `["full_name","country","geo"]` | Specifies which place fields to include if 'geo.place\_id' is expanded. | | `tweet_fields` | array | | `["created_at","text","public_metrics"]` | Specifies which Tweet fields to include in the response. | *** ### `Twitter Get Blocked Users` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"2244994945"` | 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 | | `"pinned_tweet_id"` | 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 | | `"25"` | Maximum number of blocked users per page (1-100). API defaults to 100 if unspecified. | | `user_fields` | array | | `"created_at,description,entities,id,location,name,pinned_tweet_id,profile_image_url,protected,public_metrics,url,username,verified,withheld"` | 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 | | `"attachments,author_id,context_annotations,created_at,entities,geo,id,in_reply_to_user_id,lang,public_metrics,possibly_sensitive,referenced_tweets,reply_settings,source,text,withheld"` | 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 | | `"NGHITGLI0X9F9G3ylA5401k7B0xT3XyhsF6u1wyo0dF42"` | Token for fetching the next page of results, obtained from `meta.next_token` of a previous response. | *** ### `Twitter Get Compliance Job` Integration name: **TWITTER\_GET\_COMPLIANCE\_JOB** Retrieves status, download/upload URLs, and other details for an existing Twitter compliance job specified by its unique ID. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ----------------------- | ------ | :------: | ------------------------- | ----------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"1372966999991541762"` | The unique identifier of the Compliance Job to retrieve. | | `compliance_job_fields` | array | | `["created_at","status"]` | Specifies fields for the ComplianceJob object in the response; if omitted, a default set is returned. | *** ### `Twitter Get Compliance Jobs` Integration name: **TWITTER\_GET\_COMPLIANCE\_JOBS** Returns a list of recent compliance jobs, filtered by type (tweets or users) and optionally by status. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ----------------------- | ------ | :------: | ----------- | ------------------------------------------------------------------------------------------------------------ | | `type` | string | ✅ | `"tweets"` | Specifies the type of compliance job to retrieve (tweets or users). | | `status` | string | | `"created"` | Filters compliance jobs by status; if omitted, jobs of all statuses for the specified type are returned. | | `compliance_job_fields` | array | | `"id"` | Specific `ComplianceJob` fields to include in the response; if omitted, a default set of fields is returned. | *** ### `Twitter Get Dm Conversation Events` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | | `expansions` | array | | `["sender_id","attachments.media_keys"]` | Objects to expand and include. E.g., `sender_id` includes the full User object for each DM sender. | | `event_types` | array | | `["MessageCreate","ParticipantsJoin"]` | DM event types to include. If unspecified, all types are returned. | | `max_results` | integer | | `"50"` | Maximum DM events per page (1-100). | | `user_fields` | array | | `["id","created_at","profile_image_url"]` | Fields for User objects if `expansions` includes `sender_id` or `participant_ids`. Default: basic user fields. | | `media_fields` | array | | `["media_key","type","url","preview_image_url"]` | Fields for Media objects if `expansions` includes `attachments.media_keys`. Default: basic media fields. | | `tweet_fields` | array | | `["id","text","created_at","author_id"]` | Fields for Tweet objects if `expansions` includes `referenced_tweets.id`. Default: basic tweet fields. | | `participant_id` | string | ✅ | `"2244994945"` | User ID of the other participant in the one-to-one DM conversation. | | `dm_event_fields` | array | | `["sender_id","text","created_at"]` | Fields for each DM event object. Default: 'id', 'event\_type'. | | `pagination_token` | string | | `"nextToken123"` | Token from `meta.next_token` or `meta.previous_token` of a prior response to fetch a specific results page. | *** ### `Twitter Get Dm Event` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ----------------- | ------ | :------: | ----------------------- | -------------------------------------------------------------- | | `event_id` | string | ✅ | `"1234567890123456789"` | The unique identifier of the Direct Message event to retrieve. | | `expansions` | array | | `"participant_ids"` | Related objects to expand and include in the response. | | `user_fields` | array | | `"id"` | User fields to include for user objects in the response. | | `media_fields` | array | | `"url"` | Media fields to include for media objects in the response. | | `tweet_fields` | array | | `"id"` | Tweet fields to include for tweet objects in the response. | | `dm_event_fields` | array | | `"created_at"` | DmEvent fields to include in the response. | *** ### `Twitter Get List` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------- | ------ | :------: | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"1146654567674912769"` | The unique identifier of the Twitter List to retrieve. This is a numeric string representing the List ID. | | `expansions` | array | | `"owner_id"` | A list of objects to expand in the response. Currently, the only supported expansion is `owner_id`, which, if included, returns the full User object for the list's owner within an `includes` object in the response. | | `list_fields` | array | | `"created_at"` | 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 | | `"created_at"` | 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. | *** ### `Twitter Get List Followers` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"1459122346354774019"` | Unique identifier of the Twitter List for which to retrieve followers. | | `expansions` | array | | `["pinned_tweet_id","affiliation.user_id"]` | Fields to expand for more detailed information on related entities (e.g., pinned tweets, affiliated users). | | `max_results` | integer | | `"50"` | Maximum number of user results per page. | | `user_fields` | array | | `["created_at","description","entities","id","location","name","pinned_tweet_id","profile_image_url","protected","public_metrics","url","verified","withheld"]` | User fields to include in the response for additional details on each follower. | | `tweet_fields` | array | | `["attachments","author_id","created_at","entities","id","text","public_metrics"]` | Tweet fields to include if tweet objects (e.g., pinned\_tweet\_id) are expanded. | | `pagination_token` | string | | `"NEXT_TOKEN"` | Pagination token from a previous response's `next_token` to retrieve the next page. | *** ### `Twitter Get List Members` Integration name: **TWITTER\_GET\_LIST\_MEMBERS** Fetches members of a specific Twitter List, identified by its unique ID. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"1450500649578020864"` | The unique identifier of the Twitter List. | | `expansions` | array | | `["pinned_tweet_id"]` | 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 | | `"100"` | The maximum number of list members to return per page. Values can range from 1 to 100. | | `user_fields` | array | | `["created_at","description","public_metrics"]` | Specifies which additional user details to return for each list member. | | `tweet_fields` | array | | `["created_at","text","public_metrics"]` | 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 | | `"NEXT_TOKEN_HERE"` | Token for fetching a specific page of results. Obtained from the `next_token` or `previous_token` field in the response's `meta` object. | *** ### `Twitter Get Media Upload Status` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------- | ------ | :------: | ------- | --------------------------------------------------------------------- | | `media_id` | string | ✅ | — | Numeric media ID (1-19 digits) returned from a previous media upload. | *** ### `Twitter Get Muted Users` Integration name: **TWITTER\_GET\_MUTED\_USERS** Returns user objects muted by the X user identified by the `id` path parameter. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"2244994945"` | 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 | | — | 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 | | `"100"` | The maximum number of user objects to return per page. Default is 100, minimum is 1, maximum is 1000. | | `user_fields` | array | | — | 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 | | — | 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 | | `"NEXT_TOKEN_FROM_PREVIOUS_RESPONSE"` | A token obtained from a previous response, used to fetch the next page of results. If not provided, the first page is returned. | *** ### `Twitter Get Openapi Spec` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. *No parameters required.* *** ### `Twitter Get Post Analytics` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------ | :------: | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ids` | array | ✅ | `["1234567890","9876543210"]` | 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 | ✅ | `"2021-02-01T18:40:40.000Z"` | 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 | ✅ | `"2021-02-01T18:40:40.000Z"` | 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"` | The granularity for the analytics results. Determines how the metrics are aggregated over the time range. | | `analytics.fields` | array | | `["impressions","engagements","likes"]` | 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. | *** ### `Twitter Get Post Retweeters Action` Integration name: **TWITTER\_GET\_POST\_RETWEETERS\_ACTION** Retrieves users who publicly retweeted a specified public Post ID, excluding Quote Tweets and retweets from private accounts. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"1346889436626259968"` | The unique identifier of the Post (Tweet) for which to retrieve retweeting users. This ID must be for an existing public Post. | | `expansions` | array | | `["pinned_tweet_id"]` | Objects to expand and include, such as pinned Tweets of retweeters. | | `max_results` | integer | | `"50"` | Maximum number of user objects per page (1-100, default 100). | | `user_fields` | array | | `["created_at","description","public_metrics","profile_image_url"]` | User fields to include for each user who retweeted the Post. | | `tweet_fields` | array | | `["created_at","public_metrics","text"]` | Tweet fields for expanded Tweet objects (e.g., when `expansions` includes 'pinned\_tweet\_id'). | | `pagination_token` | string | | `"NEXT_TOKEN_STRING"` | 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. | *** ### `Twitter Get Post Retweets` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"1460323737035677698"` | The unique identifier of the Tweet for which to retrieve Retweets. | | `expansions` | array | | — | Specifies objects to expand for related data on Retweeting Tweets or their authors (e.g., `author_id`, `referenced_tweets.id`). | | `max_results` | integer | | — | Specifies the maximum number of Retweets to return, between 10 and 100. | | `poll_fields` | array | | — | Poll fields to include if `expansions` contains `attachments.poll_ids`. | | `user_fields` | array | | — | User fields for authors of Retweeting Tweets, applicable if `expansions` includes `author_id`. | | `media_fields` | array | | — | Media fields to include if `expansions` contains `attachments.media_keys`. | | `place_fields` | array | | — | Place fields to include if `expansions` contains `geo.place_id`. | | `tweet_fields` | array | | — | Specifies Tweet fields to include for additional information about the Retweeting Tweets. | | `pagination_token` | string | | `"1sqq1j31u9xwl_AsojKIKxUaUXPNkXqfn6a35Kgm85P1A"` | Pagination token from a previous response's `meta.next_token` to request the next page of results. | *** ### `Twitter Get Post Usage` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | -------------- | ------- | :------: | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `days` | integer | | `"7"` | Specifies the number of days (1 to 90) to retrieve usage data for. Defaults to 7 days. | | `usage_fields` | array | | `["cap_reset_day","project_usage"]` | 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. | *** ### `Twitter Get Recent Dm Events` Integration name: **TWITTER\_GET\_RECENT\_DM\_EVENTS** Returns recent Direct Message events for the authenticated user, such as new messages or changes in conversation participants. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `expansions` | array | | — | A comma separated list of fields to expand. | | `event_types` | array | | — | The set of event\_types to include in the results. | | `max_results` | integer | | — | 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 | | — | A comma separated list of User fields to display. | | `media_fields` | array | | — | A comma separated list of Media fields to display. | | `tweet_fields` | array | | — | A comma separated list of Tweet fields to display. | | `dm_event_fields` | array | | — | A comma separated list of DmEvent fields to display. | | `pagination_token` | string | | — | This parameter is used to get a specified "page" of results. | *** ### `Twitter Get Space By Id` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | -------------- | ------ | :------: | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"1SLjjRYNejbKM"` | Unique identifier of the Twitter Space to retrieve. | | `expansions` | array | | `["creator_id","host_ids"]` | Objects to expand in the response (e.g., `creator_id`). Customize with corresponding `*_fields`. See ExpansionsEnm0 for options. | | `user_fields` | array | | `["public_metrics","profile_image_url"]` | Fields for User objects expanded via `expansions` (e.g., if `creator_id` is expanded). See UserFieldsEnm0 for options. | | `space_fields` | array | | `["created_at","participant_count","title"]` | Fields to include for the Space object; defaults to a standard set if omitted. See SpaceFieldsEnm0 for options. | | `topic_fields` | array | | `["id","name","description"]` | Fields for Topic objects expanded via `expansions` (e.g., if `topic_ids` is expanded). See TopicFieldsEnm0 for options. | *** ### `Twitter Get Space Posts` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | -------------- | ------- | :------: | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | — | The unique identifier of the Twitter Space. Can be extracted from Space URLs (e.g., '1nAKEEAgYvkKL' from ). Note: Most Spaces have zero associated Tweets since Spaces are primarily audio conversations. | | `expansions` | array | | `"author_id"` | 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 | | `"50"` | The maximum number of Tweets to fetch from the Space per request. Defaults to 100, which is also the maximum allowed. | | `poll_fields` | array | | `"id"` | A list of Poll fields to be included for polls, if 'attachments.poll\_ids' is part of 'expansions'. | | `user_fields` | array | | `"public_metrics"` | 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 | | `"url"` | A list of Media fields to be included for media content, if 'attachments.media\_keys' is part of 'expansions'. | | `place_fields` | array | | `"full_name"` | A list of Place fields to be included for geo-tagged Tweets, if 'geo.place\_id' is part of 'expansions'. | | `tweet_fields` | array | | `"author_id"` | A list of Tweet fields to be included in the response. By default, only 'id' and 'text' are returned for each Tweet. | *** ### `Twitter Get Spaces By Creators` Integration name: **TWITTER\_GET\_SPACES\_BY\_CREATORS** Retrieves Twitter Spaces created by a list of specified User IDs, with options to customize returned data fields. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | -------------- | ----- | :------: | -------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `user_ids` | array | ✅ | `"2244994945"` | A list of User IDs whose Spaces will be retrieved. At least one User ID must be provided. | | `expansions` | array | | `"creator_id"` | Specifies which related objects to expand for more detailed information in the response. | | `user_fields` | array | | `"created_at"` | Specifies which fields to return for User objects, applicable when User-related IDs (e.g., 'creator\_id') are included in 'expansions'. | | `space_fields` | array | | `"created_at"` | Specifies which fields to return for each Space object. | | `topic_fields` | array | | `"id"` | Specifies which fields to return for Topic objects, applicable when 'topic\_ids' is included in 'expansions'. | *** ### `Twitter Get Spaces By Ids` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | -------------- | ----- | :------: | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `ids` | array | ✅ | `["1SLjjRYNejbKM","1DXxyRYugenJ"]` | Unique identifiers for the Twitter Spaces to retrieve. | | `expansions` | array | | `["creator_id","host_ids"]` | Objects to expand and include their full details (e.g., 'creator\_id', 'host\_ids'). See `ExpansionsEnm0` for options. | | `user_fields` | array | | `["created_at","public_metrics"]` | Specific fields for User objects included via expansions (e.g., if 'creator\_id' is in 'expansions'). See `UserFieldsEnm0` for options. | | `space_fields` | array | | `["created_at","participant_count","title"]` | Specific fields to return for each Space object; omits to return default fields. See `SpaceFieldsEnm0` for options. | | `topic_fields` | array | | `["id","name","description"]` | Specific fields for Topic objects included via expansions (e.g., if 'topic\_ids' is in 'expansions'). See `TopicFieldsEnm0` for options. | *** ### `Twitter Get Space Ticket Buyers` Integration name: **TWITTER\_GET\_SPACE\_TICKET\_BUYERS** Retrieves a list of users who purchased tickets for a specific, valid, and ticketed Twitter Space. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | ------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | — | The unique identifier of the Space for which to retrieve the list of ticket buyers. | | `expansions` | array | | `"pinned_tweet_id"` | Objects to expand in the response for more detailed information (e.g., `pinned_tweet_id` to include the full Tweet object). | | `max_results` | integer | | — | Maximum number of buyer records to return per page. | | `user_fields` | array | | `"id"` | User fields to include for each buyer, providing additional details. Refer to the User object schema for available fields. | | `tweet_fields` | array | | `"id"` | Tweet fields to include when Tweet objects are expanded. Refer to the Tweet object schema for available fields. | | `pagination_token` | string | | — | Token from a previous response to fetch the subsequent page of results. | *** ### `Twitter Get User By Id` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | -------------- | ------ | :------: | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"2244994945"` | 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 | | `"pinned_tweet_id"` | Linked entities to expand (e.g., `pinned_tweet_id` for the full pinned Tweet). See `ExpansionsEnm0` for options. | | `user_fields` | array | | `"created_at"` | Specifies which user attributes to return. See `UserFieldsEnm0` for options. | | `tweet_fields` | array | | `"created_at"` | Specifies which tweet attributes to return for expanded tweets. See `TweetFieldsEnm0` for options. | *** ### `Twitter Get User Followed Lists` Integration name: **TWITTER\_GET\_USER\_FOLLOWED\_LISTS** Returns metadata (not Tweets) for lists a specific Twitter user follows, optionally including expanded owner details. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"2244994945"` | The unique identifier of the User whose followed lists are to be retrieved. | | `expansions` | array | | `["owner_id"]` | 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 | | `["created_at","description","follower_count"]` | A list of fields to include for each List object in the response. Refer to `ListFieldsEnm0` for all available fields. | | `max_results` | integer | | — | The maximum number of List results to be returned per page. Default is 100. | | `user_fields` | array | | `["profile_image_url","public_metrics"]` | 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 | | — | 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. | *** ### `Twitter Get User List Memberships` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"2244994945"` | The unique identifier of the target User whose List memberships are to be retrieved. | | `expansions` | array | | `["owner_id"]` | 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 | | `["created_at","description"]` | 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 | | `"100"` | Specifies the maximum number of List memberships to return in a single page. Valid range: 1-100. Default: 100. | | `user_fields` | array | | `["created_at","profile_image_url","username"]` | 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 | | `"PgmPqCUd3arS2InPWE7Xjw_5X2E02AEaVUn6vx5RglKIk"` | 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. | *** ### `Twitter Get User Owned Lists` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | ------------------------------ | ------------------------------------------------------------------------------------------------------------ | | `id` | string | ✅ | — | User ID of the Twitter User whose owned Lists are to be retrieved. | | `expansions` | array | | `"owner_id"` | Set to `['owner_id']` to include the User object of the List's owner. | | `list_fields` | array | | `"created_at"` | Specific fields to return for each List object (e.g., `created_at`, `description`). | | `max_results` | integer | | `25` | Maximum number of List results per page. Allowed values: 1-100. Default: 100. | | `user_fields` | array | | `"public_metrics"` | Specific fields for User objects if `expansions` includes `owner_id` (e.g., `public_metrics`, `created_at`). | | `pagination_token` | string | | `"PBTGI670EALHAI67_3_ADDAAZZ"` | Token from `meta.next_token` of a previous response to fetch the next page. Omit for the first page. | *** ### `Twitter Get User Pinned Lists` Integration name: **TWITTER\_GET\_USER\_PINNED\_LISTS** Retrieves the Lists a specific, existing Twitter user has pinned to their profile to highlight them. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------- | ------ | :------: | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | string | ✅ | `"2244994945"` | The unique identifier of the User whose pinned Lists are to be retrieved. | | `expansions` | array | | `"owner_id"` | 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 | | `"created_at"` | A comma-separated list of List fields to return for each List object. Select desired fields from `ListFieldsEnm0`. | | `user_fields` | array | | `"created_at"` | A comma-separated list of User fields to return. This is applicable when `expansions` includes `owner_id`. Select desired fields from `UserFieldsEnm0`. | *** ### `Twitter Get Users By Ids` Integration name: **TWITTER\_GET\_USERS\_BY\_IDS** Retrieves detailed information for specified X (formerly Twitter) user IDs, optionally customizing returned fields and expanding related entities. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | -------------- | ----- | :------: | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ids` | array | ✅ | `["2244994945","783214"]` | 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 | | — | Objects to expand in the response (e.g., 'pinned\_tweet\_id'). See ExpansionsEnm0 for options. | | `user_fields` | array | | — | Specific user fields to return. See UserFieldsEnm0 for options. | | `tweet_fields` | array | | — | Tweet fields to return for expanded tweet objects. See TweetFieldsEnm0 for options. | *** ### `Twitter Hide Replies` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------- | ------- | :------: | -------- | ------------------------------------------------------- | | `hidden` | boolean | ✅ | `"true"` | Set to `true` to hide the reply, `false` to unhide. | | `tweet_id` | string | ✅ | — | Unique identifier of the reply Tweet to hide or unhide. | *** ### `Twitter Initialize Media Upload` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------- | ------- | :------: | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `shared` | boolean | | `true` | Whether this media is shared or not. Optional parameter. | | `media_type` | string | ✅ | `"video/mp4"` | 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 | ✅ | `1024000` | The total size of the media file in bytes. Must be between 0 and 17179869184 (16 GB). | | `media_category` | string | | `"tweet_video"` | Media category for upload | | `additional_owners` | array | | `["2244994945","783214"]` | 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. | *** ### `Twitter List Post Likers` Integration name: **TWITTER\_LIST\_POST\_LIKERS** Retrieves users who have liked the Post (Tweet) identified by the provided ID. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"1460323737035677698"` | The unique identifier of the Post (Tweet) for which to retrieve liking users. | | `expansions` | array | | `["pinned_tweet_id"]` | Fields to expand for related objects, like a user's pinned Tweet. Example: \['pinned\_tweet\_id']. | | `max_results` | integer | | `50` | 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 | | `["created_at","description"]` | User fields to retrieve for each liking user. Example: \['created\_at', 'description']. | | `tweet_fields` | array | | `["created_at","public_metrics"]` | Tweet fields to retrieve for expanded Tweet objects (e.g., if `expansions` includes `pinned_tweet_id`). Example: \['created\_at', 'public\_metrics']. | | `pagination_token` | string | | `"NEXT_TOKEN"` | 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. | *** ### `Twitter List Posts Timeline By List Id` Integration name: **TWITTER\_LIST\_POSTS\_TIMELINE\_BY\_LIST\_ID** Fetches the most recent Tweets posted by members of a specified Twitter List. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"1455949872148680704"` | The unique identifier of the Twitter List from which to retrieve Tweets. | | `expansions` | array | | `"author_id"` | Specifies which related objects to expand and include in the response (e.g., author data, media details). | | `max_results` | integer | | — | The maximum number of Tweets to return per request. Must be between 1 and 100. | | `poll_fields` | array | | `"id"` | Specifies which Poll object fields to include if 'attachments.poll\_ids' is in 'expansions'. | | `user_fields` | array | | `"public_metrics"` | Specifies which User object fields to include if 'author\_id' or other user references are in 'expansions'. | | `media_fields` | array | | `"url"` | Specifies which Media object fields to include if 'attachments.media\_keys' is in 'expansions'. | | `place_fields` | array | | `"full_name"` | Specifies which Place object fields to include if 'geo.place\_id' is in 'expansions'. | | `tweet_fields` | array | | `"created_at"` | Specifies which Tweet object fields to include in the response. | | `pagination_token` | string | | `"7140dibdnow9c7btw423bnr3k0xq1hyrmo13k74vxah3n"` | 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. | *** ### `Twitter Mute User` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------------- | ------ | :------: | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | | `"2244994945"` | 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 | ✅ | `"783214"` | The User ID of the user to be muted. | *** ### `Twitter Pin List` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | ----------------------- | -------------------------------------------------- | | `id` | string | ✅ | `"2244994945"` | The ID of the authenticated User pinning the List. | | `list_id` | string | ✅ | `"1458528232014442499"` | The unique identifier of the List to be pinned. | *** ### `Twitter Post Delete By Post Id` Integration name: **TWITTER\_POST\_DELETE\_BY\_POST\_ID** Irreversibly deletes a specific Tweet by its ID; the Tweet may persist in third-party caches after deletion. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `id` | string | ✅ | `"1340880330944065536"` | The unique identifier of the Tweet to be deleted. This ID must correspond to a Tweet authored by the authenticated user. | *** ### `Twitter Post Lookup By Post Id` Integration name: **TWITTER\_POST\_LOOKUP\_BY\_POST\_ID** Fetches comprehensive details for a single Tweet by its unique ID, provided the Tweet exists and is accessible. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | -------------- | ------ | :------: | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"1346889436626259968"` | 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 | | `"author_id"` | 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 | | `"id"` | 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 | | `"public_metrics"` | 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 | | `"media_key"` | 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 | | `"full_name"` | 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 | | `"created_at"` | Tweet attributes to include for additional details about the Tweet. Accepts a list of field names or a comma-separated string. | *** ### `Twitter Post Lookup By Post Ids` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | -------------- | ----- | :------: | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ids` | array | ✅ | `["1346889436626259968","1293593516030459905"]` | 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 | | `["author_id","attachments.media_keys"]` | 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 | | `["options","duration_minutes","end_datetime"]` | 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 | | `["public_metrics","profile_image_url"]` | 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 | | `["url","type","width","height"]` | 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 | | `["full_name","geo","country_code"]` | 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 | | `["created_at","author_id","public_metrics"]` | A comma-separated list of Tweet fields to include in the response. Can be provided as a string (comma-separated) or a list. | *** ### `Twitter Recent Search` Integration name: **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"] } #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `query` | string | ✅ | `"from:elonmusk -is:retweet -is:reply"` | 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 | | `"2023-01-02T00:00:00Z"` | 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 | | `"1346889436626259968"` | 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 | | `"1346889436626259960"` | 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 | | `["author_id","attachments.media_keys"]` | Expansions to include additional objects like users, media, polls, etc. | | `next_token` | string | | `"7140dibdnow9c7btw424y0glyzp3gflb1vxotgrg2y829"` | Token from `meta.next_token` of a previous response for pagination; do not modify. | | `sort_order` | string | | `"recency"` | Order of results: 'recency' (most recent first) or 'relevancy'. | | `start_time` | string | | `"2025-10-05T12:00:00Z"` | 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 | | `10` | 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 | | `["options","duration_minutes","voting_status"]` | Poll fields to include when poll IDs are expanded. | | `user_fields` | array | | `["created_at","verified","public_metrics"]` | 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 | | `["url","preview_image_url","height","width"]` | Media fields to include when media keys are expanded. | | `place_fields` | array | | `["full_name","country","geo"]` | Place fields to include when place IDs are expanded. | | `tweet_fields` | array | | `["created_at","author_id","public_metrics"]` | Additional tweet object fields to include in the response. | | `pagination_token` | string | | `"7140dibdnow9c7btw424y0glyzp3gflb1vxotgrg2y829"` | Alternative pagination token from a previous `meta.next_token`; `next_token` is preferred if both are provided. | *** ### `Twitter Remove List Member` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | ----------------------- | ------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"1459564519541506049"` | The unique identifier of the Twitter List from which a member will be removed. | | `user_id` | string | ✅ | `"2244994945"` | The unique identifier (ID) of the Twitter user to be removed from the specified List. | *** ### `Twitter Remove Post From Bookmarks` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------- | ------ | :------: | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | | `"2244994945"` | 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 | ✅ | `"1460323737035677698"` | The ID of the Tweet to be removed from the user's bookmarks. | *** ### `Twitter Retrieve Dm Conversation Events` Integration name: **TWITTER\_RETRIEVE\_DM\_CONVERSATION\_EVENTS** Retrieves Direct Message (DM) events for a specific conversation ID on Twitter, useful for analyzing messages and participant activities. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | — | 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 | | — | A comma separated list of fields to expand. | | `event_types` | array | | — | The set of event\_types to include in the results. | | `max_results` | integer | | — | The maximum number of results. | | `user_fields` | array | | — | A comma separated list of User fields to display. | | `media_fields` | array | | — | A comma separated list of Media fields to display. | | `tweet_fields` | array | | — | A comma separated list of Tweet fields to display. | | `dm_event_fields` | array | | — | A comma separated list of DmEvent fields to display. | | `pagination_token` | string | | — | This parameter is used to get a specified "page" of results. | *** ### `Twitter Retrieve Posts That Quote A Post` Integration name: **TWITTER\_RETRIEVE\_POSTS\_THAT\_QUOTE\_A\_POST** Retrieves Tweets that quote a specified Tweet, requiring a valid Tweet ID. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | -------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"1346889436626259968"` | Unique identifier of the Tweet whose quoting Tweets you would like to retrieve. | | `exclude` | array | | `["replies"]` | Specifies whether to exclude replies or retweets from the results. | | `expansions` | array | | `["author_id","referenced_tweets.id"]` | Fields to expand in the response, such as 'author\_id' to include the author's user object. | | `max_results` | integer | | `10` | Maximum number of results to return per page (range: 10-100). | | `poll_fields` | array | | `["options","duration_minutes"]` | Specific Poll fields to include in the response if poll objects are present. | | `user_fields` | array | | `["public_metrics"]` | Specific User fields to include if user objects are present (e.g., through expansions). | | `media_fields` | array | | `["url","preview_image_url"]` | Specific Media fields to include in the response if media objects are present. | | `place_fields` | array | | `["full_name","geo"]` | Specific Place fields to include in the response if place objects are present. | | `tweet_fields` | array | | `["created_at","author_id"]` | Specific Tweet fields to include in the response. | | `pagination_token` | string | | `"SDFSFFSUSUHSNF232"` | Token for retrieving a specific page of results, typically the `next_token` from a previous response. | *** ### `Twitter Returns Post Objects Liked By The Provided User Id` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | -------------------------------------------- | ------------------------------------------------------------------------------------ | | `id` | string | ✅ | `"2244994945"` | Twitter user ID whose liked Tweets are to be retrieved. | | `expansions` | array | | `["author_id","attachments.media_keys"]` | Objects to expand, e.g., `author_id`, `attachments.media_keys`, for richer data. | | `max_results` | integer | | `"50"` | Maximum liked Tweets per page. | | `poll_fields` | array | | `["duration_minutes","options"]` | Poll fields to include when `attachments.poll_ids` is in `expansions`. | | `user_fields` | array | | `["public_metrics","profile_image_url"]` | User fields for Tweet authors or other user objects when `expansions` includes them. | | `media_fields` | array | | `["url","preview_image_url","type"]` | Media fields to include when `attachments.media_keys` is in `expansions`. | | `place_fields` | array | | `["full_name","geo"]` | Place fields to include when `geo.place_id` is in `expansions`. | | `tweet_fields` | array | | `["created_at","public_metrics","entities"]` | Specific Tweet fields to include. API provides a default set if omitted. | | `pagination_token` | string | | `"nextToken123"` | Token from a previous response to fetch the next page. | *** ### `Twitter Retweet Post` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------- | ------ | :------: | ----------------------- | ------------------------------------ | | `tweet_id` | string | ✅ | `"1293593516030459905"` | The ID of the Tweet to be retweeted. | *** ### `Twitter Search Full Archive Counts` Integration name: **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`. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------------------- | ------ | :------: | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | ✅ | `"(from:twitterdev -is:retweet) OR #twitterapi"` | Search query for matching Tweets using Twitter's V2 filtering syntax (see official Twitter API documentation for syntax and length). | | `end_time` | string | | — | 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 | | — | Count Tweets more recent than this ID. Cannot be used with `start_time` or `end_time`. | | `until_id` | string | | — | Count Tweets older than this ID. Cannot be used with `start_time` or `end_time`. | | `next_token` | string | | — | Token from a previous response to fetch the next page of results. Use as-is. | | `start_time` | string | | — | 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"` | Time period granularity for aggregating search count results. | | `pagination_token` | string | | — | Pagination token, typically `next_token` in Twitter API v2. Use as-is. | | `search_count_fields` | array | | `["start","tweet_count"]` | Specifies which fields to return for each search count object; default fields are returned if unspecified. | *** ### `Twitter Search Recent Counts` Integration name: **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'. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------------------- | ------ | :------: | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | ✅ | `"#covid19 lang:en"` | A search query rule to match against Tweets. For example, '#twitterdev OR @twitterapi'. Refer to Twitter's documentation for query syntax and maximum length: | | `end_time` | string | | `"2024-12-21T00:00:00Z"` | 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 '\' - either provide a valid timestamp or omit entirely. | | `since_id` | string | | `"1346889436626259968"` | Returns counts for Tweets created more recently than the specified Tweet ID. This helps to paginate results chronologically. | | `until_id` | string | | `"1346889436626259969"` | Returns counts for Tweets created older than the specified Tweet ID. This helps to paginate results chronologically. | | `next_token` | string | | `"b26v89c19zqg8o3fosk1i54k92ins3fcg1fg5p3phw9qt"` | A token obtained from a previous response to fetch the next page of results. Do not modify this value. | | `start_time` | string | | `"2024-12-15T00:00:00Z"` | 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 '\' - either provide a valid timestamp or omit entirely. | | `granularity` | string | | `"day"` | The time period granularity for aggregating search counts. | | `pagination_token` | string | | `"b26v89c19zqg8o3fosk1i54k92ins3fcg1fg5p3phw9qt"` | 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 | | `["end","start","tweet_count"]` | A list of fields to include in each search count object. Available fields: 'end', 'start', 'tweet\_count'. If unspecified, default fields are returned. | *** ### `Twitter Search Spaces` Integration name: **TWITTER\_SEARCH\_SPACES** Searches for Twitter Spaces by a textual query, optionally filtering by state (live, scheduled, all) to discover audio conversations. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | -------------- | ------- | :------: | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | ✅ | `"crypto"` | The text query to search for in Space titles and descriptions. | | `state` | string | | — | Filters Spaces by their state (e.g., 'live', 'scheduled'). | | `expansions` | array | | — | 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 | | — | The maximum number of Space results to return in a single response. Values must be between 1 and 100, inclusive. | | `user_fields` | array | | — | Specifies fields for expanded User objects (e.g., 'username', 'public\_metrics'). Omitting this returns a default set of User fields. | | `space_fields` | array | | — | Specifies fields to include for each Space object (e.g., 'id', 'title'). Omitting this returns a default set of fields. | | `topic_fields` | array | | — | Specifies fields for expanded Topic objects (e.g., 'id', 'name'). Omitting this returns a default set of Topic fields. | *** ### `Twitter Send A New Message To A User` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------------- | ------ | :------: | -------------- | ----------------------------------------- | | `text` | string | | — | Text content of the Direct Message. | | `attachments` | array | | — | Media attachments for the Direct Message. | | `participant_id` | string | ✅ | `"2244994945"` | User ID of the recipient. | *** ### `Twitter Send Dm To Conversation` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | -------------------- | ------ | :------: | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `text` | string | | — | Text content of the Direct Message. At least one of `text` or `attachments` is required. | | `attachments` | array | | — | 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 | ✅ | `"123456789-987654321"` | Identifier of the DM conversation; can be a numeric string (group DM) or two user IDs hyphen-separated (one-on-one DM). | *** ### `Twitter Stream Post Labels` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `end_time` | string | | `"2023-01-01T12:00:00Z"` | Latest UTC timestamp (YYYY-MM-DDTHH:mm:ssZ) at which the stream will automatically close, ceasing event transmission. | | `start_time` | string | | `"2023-01-01T00:00:00Z"` | Earliest UTC timestamp (YYYY-MM-DDTHH:mm:ssZ) from which to start streaming label events; disregards `backfill_minutes` if provided. | | `backfill_minutes` | integer | | `0` | 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. | *** ### `Twitter Unfollow List` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | ----------------------- | ----------------------------------------------- | | `id` | string | ✅ | `"2244994945"` | The ID of the user who is unfollowing the list. | | `list_id` | string | ✅ | `"1458007526700871680"` | The ID of the Twitter List to be unfollowed. | *** ### `Twitter Unfollow User` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------------- | ------ | :------: | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `source_user_id` | string | | `"2244994945"` | 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 | | `"783214"` | The user ID of the user to unfollow. Alternatively, you can pass 'user\_id' which will be treated as the target user ID. | *** ### `Twitter Unlike Post` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------- | ------ | :------: | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"1234567890"` | 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 | ✅ | `"1460323737035677698"` | The ID of the post (Tweet) that the user is requesting to unlike. | *** ### `Twitter Unmute User` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------------- | ------ | :------: | ----------------------- | ---------------------------------- | | `target_user_id` | string | ✅ | `"9876543210987654321"` | User ID of the user to be unmuted. | *** ### `Twitter Unpin List` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | | `"2244994945"` | 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 | ✅ | `"1460323740012077058"` | ID of the List to unpin from the authenticated user's profile. | *** ### `Twitter Unretweet Post` Integration name: **TWITTER\_UNRETWEET\_POST** Removes a user's retweet of a specified Post, if the user had previously retweeted it. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ----------------- | ------ | :------: | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"2244994945"` | 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 | ✅ | `"1346889436626259968"` | The unique identifier of the Post (Tweet) that the user is requesting to unretweet. | *** ### `Twitter Update List` Integration name: **TWITTER\_UPDATE\_LIST** Updates an existing Twitter List's name, description, or privacy status, requiring the List ID and at least one mutable property. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------- | ------- | :------: | ---------------------------------------- | ------------------------------------------------------------------------------ | | `id` | string | ✅ | `"1455540050104430592"` | The unique identifier of the Twitter List to be updated. | | `name` | string | | `"AI Innovators"` | New name for the List; must be a non-empty string if provided. | | `private` | boolean | | `true` | Controls the visibility of the List: `True` for private, `False` for public. | | `description` | string | | `"Curated list of AI experts and news."` | New description for the List; an empty string clears the existing description. | *** ### `Twitter Upload Large Media` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------------- | ------ | :------: | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `media` | object | ✅ | — | 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 | | — | 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. | *** ### `Twitter Upload Media` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------------- | ------ | :------: | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `media` | object | ✅ | — | 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 | | — | 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 | | — | 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. | *** ### `Twitter User Home Timeline By User Id` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | | `"2244994945"` | 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 | | `["replies","retweets"]` | Tweet types to exclude from results. Accepts either a list \['replies', 'retweets'] or a comma-separated string 'replies,retweets'. | | `end_time` | string | | `"2021-12-31T23:59:59Z"` | 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 | | `"1346889436626259968"` | Returns results with a Tweet ID more recent than the specified ID. Takes precedence over `start_time`. | | `until_id` | string | | `"1346889436626259969"` | Returns results with a Tweet ID older than the specified ID. Takes precedence over `end_time`. | | `expansions` | array | | `["author_id","attachments.media_keys"]` | 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 | | `"2021-01-01T00:00:00Z"` | 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 | | `"50"` | 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 | | `["duration_minutes","options"]` | 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 | | `["public_metrics","created_at"]` | 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 | | `["url","preview_image_url","type"]` | 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 | | `["full_name","country_code"]` | 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 | | `["created_at","public_metrics","text"]` | 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 | | `"7140dibd0v1s6csiqmq1c69n01z3pmr9glpk8g5q5lwg2"` | Token from a previous response to fetch the next page of results. | *** ### `Twitter User Like Post` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------- | ------ | :------: | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"1993025481650978819"` | 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 | ✅ | `"1346889436626259968"` | The unique identifier of the Tweet to be liked. | *** ### `Twitter User Lookup By Username` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | -------------- | ------ | :------: | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `username` | string | ✅ | `"TwitterDev"` | 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 | | `["pinned_tweet_id","most_recent_tweet_id"]` | Fields to expand for more detailed information on objects like `pinned_tweet_id` (includes full Tweet object). | | `user_fields` | array | | `["created_at","description","public_metrics","profile_image_url","verified_type"]` | 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 | | `["created_at","public_metrics","author_id"]` | 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. | *** ### `Twitter User Lookup By Usernames` Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | -------------- | ----- | :------: | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `usernames` | array | ✅ | `["twitterdev","TwitterAPI","jack"]` | 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 | | `["pinned_tweet_id"]` | 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 | | `["created_at","description","profile_image_url","public_metrics","verified"]` | 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 | | `["created_at","id","text","public_metrics"]` | 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. | *** ### `Twitter User Lookup Me` Integration name: **TWITTER\_USER\_LOOKUP\_ME** Returns profile information for the currently authenticated X user, customizable via request fields. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | -------------- | ----- | :------: | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `expansions` | array | | `"pinned_tweet_id"` | 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 | | `"created_at"` | 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 | | `"id"` | 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. | *** --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.toolhouse.ai/toolhouse/integrations/x-twitter.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.