action x_search_users { label: "Search Users" description: "Retrieves a list of Users matching a search query." provider: x method: GET path: "/2/users/search" encoding: json scopes: ["tweet.read", "users.read"] input: { type: "object" properties: { expansions: { type: "array" description: "The list of fields you can expand for a [User](#User) object. If the field has an ID, it can be expanded into a full object." items: { type: "string" enum: ["affiliation.user_id", "most_recent_tweet_id", "pinned_tweet_id"] } } max_results: { type: "integer" format: "int32" } next_token: { type: "string" description: "A base36 pagination token." } query: { type: "string" description: "The the search string by which to query for users." } "tweet.fields": { type: "array" description: "The fields available for a Tweet object." items: { type: "string" enum: ["article", "attachments", "author_id", "card_uri", "community_id", "context_annotations", "conversation_id", "created_at", "display_text_range", "edit_controls", "edit_history_tweet_ids", "entities", "geo", "id", "in_reply_to_user_id", "lang", "matched_media_notes", "media_metadata", "non_public_metrics", "note_request_suggestions", "note_tweet", "organic_metrics", "paid_partnership", "possibly_sensitive", "promoted_metrics", "public_metrics", "referenced_tweets", "reply_settings", "scopes", "source", "suggested_source_links", "suggested_source_links_with_counts", "text", "withheld"] } } "user.fields": { type: "array" description: "The fields available for a User object." items: { type: "string" enum: ["affiliation", "confirmed_email", "connection_status", "created_at", "description", "entities", "id", "is_identity_verified", "location", "most_recent_tweet_id", "name", "parody", "pinned_tweet_id", "profile_banner_url", "profile_image_url", "protected", "public_metrics", "receives_your_dm", "subscription", "subscription_type", "url", "username", "verified", "verified_followers_count", "verified_type", "withheld"] } } } required: ["query"] additionalProperties: false } output: { type: "object" properties: { data: { type: "array" items: { type: "object" description: "The X User object." required: ["id", "name", "username"] properties: { affiliation: { type: "object" description: "Metadata about a user's affiliation." properties: { badge_url: { type: "string" format: "uri" description: "The badge URL corresponding to the affiliation." } description: { type: "string" description: "The description of the affiliation." } url: { type: "string" format: "uri" description: "The URL, if available, to details about an affiliation." } user_id: { type: "array" items: { type: "string" description: "Unique identifier of this User. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers." } } } } connection_status: { type: "array" description: "Returns detailed information about the relationship between two users." items: { type: "string" description: "Type of connection between users." enum: ["follow_request_received", "follow_request_sent", "blocking", "followed_by", "following", "muting"] } } created_at: { type: "string" format: "date-time" description: "Creation time of this User." } description: { type: "string" description: "The text of this User's profile description (also known as bio), if the User provided one." } entities: { type: "object" description: "A list of metadata found in the User's profile description." properties: { description: { type: "object" properties: { annotations: { type: "array" items: { description: "Annotation for entities based on the Tweet text." type: "object" } } cashtags: { type: "array" items: { type: "object" } } hashtags: { type: "array" items: { type: "object" } } mentions: { type: "array" items: { type: "object" } } urls: { type: "array" items: { description: "Represent the portion of text recognized as a URL, and its start and end position within the text." type: "object" } } } } url: { type: "object" description: "Expanded details for the URL specified in the User's profile, with start and end indices." properties: { urls: { type: "array" items: { description: "Represent the portion of text recognized as a URL, and its start and end position within the text." type: "object" } } } } } } id: { type: "string" description: "Unique identifier of this User. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers." } location: { type: "string" description: "The location specified in the User's profile, if the User provided one. As this is a freeform value, it may not indicate a valid location, but it may be fuzzily evaluated when performing searches with location queries." } most_recent_tweet_id: { type: "string" description: "Unique identifier of this Tweet. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers." } name: { type: "string" description: "The friendly name of this User, as shown on their profile." } pinned_tweet_id: { type: "string" description: "Unique identifier of this Tweet. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers." } profile_banner_url: { type: "string" format: "uri" description: "The URL to the profile banner for this User." } profile_image_url: { type: "string" format: "uri" description: "The URL to the profile image for this User." } protected: { type: "boolean" description: "Indicates if this User has chosen to protect their Posts (in other words, if this User's Posts are private)." } public_metrics: { type: "object" description: "A list of metrics for this User." required: ["followers_count", "following_count", "tweet_count", "listed_count"] properties: { followers_count: { type: "integer" description: "Number of Users who are following this User." } following_count: { type: "integer" description: "Number of Users this User is following." } like_count: { type: "integer" description: "The number of likes created by this User." } listed_count: { type: "integer" description: "The number of lists that include this User." } tweet_count: { type: "integer" description: "The number of Posts (including Retweets) posted by this User." } } } receives_your_dm: { type: "boolean" description: "Indicates if you can send a DM to this User" } subscription_type: { type: "string" description: "The X Blue subscription type of the user, eg: Basic, Premium, PremiumPlus or None." enum: ["Basic", "Premium", "PremiumPlus", "None"] } url: { type: "string" description: "The URL specified in the User's profile." } username: { type: "string" description: "The X handle (screen name) of this user." } verified: { type: "boolean" description: "Indicate if this User is a verified X User." } verified_type: { type: "string" description: "The X Blue verified type of the user, eg: blue, government, business or none." enum: ["blue", "government", "business", "none"] } withheld: { type: "object" description: "Indicates withholding details for [withheld content](https://help.twitter.com/en/rules-and-policies/tweet-withheld-by-country)." required: ["country_codes"] properties: { country_codes: { type: "array" description: "Provides a list of countries where this content is not available." items: { type: "string" description: "A two-letter ISO 3166-1 alpha-2 country code." } } scope: { type: "string" description: "Indicates that the content being withheld is a `user`." enum: ["user"] } } } } } } errors: { type: "array" items: { type: "object" description: "An HTTP Problem Details object, as defined in IETF RFC 7807 (https://tools.ietf.org/html/rfc7807)." required: ["type", "title"] properties: { detail: { type: "string" } status: { type: "integer" } title: { type: "string" } type: { type: "string" } } } } includes: { type: "object" properties: { media: { type: "array" items: { type: "object" required: ["type"] properties: { height: { type: "integer" description: "The height of the media in pixels." } media_key: { type: "string" description: "The Media Key identifier for this attachment." } type: { type: "string" } width: { type: "integer" description: "The width of the media in pixels." } } } } places: { type: "array" items: { type: "object" required: ["id", "full_name"] properties: { contained_within: { type: "array" items: { type: "string" description: "The identifier for this place." } } country: { type: "string" description: "The full name of the county in which this place exists." } country_code: { type: "string" description: "A two-letter ISO 3166-1 alpha-2 country code." } full_name: { type: "string" description: "The full name of this place." } geo: { type: "object" required: ["type", "bbox", "properties"] properties: { bbox: { type: "array" items: { type: "number" format: "double" } } geometry: { type: "object" description: "A [GeoJson Point](https://tools.ietf.org/html/rfc7946#section-3.1.2) geometry object." required: ["type", "coordinates"] properties: { coordinates: { type: "array" description: "A [GeoJson Position](https://tools.ietf.org/html/rfc7946#section-3.1.1) in the format `[longitude,latitude]`." items: { type: "number" } } type: { type: "string" enum: ["Point"] } } } properties: { type: "object" } type: { type: "string" enum: ["Feature"] } } } id: { type: "string" description: "The identifier for this place." } name: { type: "string" description: "The human readable name of this place." } place_type: { type: "string" enum: ["poi", "neighborhood", "city", "admin", "country", "unknown"] } } } } polls: { type: "array" items: { type: "object" description: "Represent a Poll attached to a Tweet." required: ["id", "options"] properties: { duration_minutes: { type: "integer" format: "int32" } end_datetime: { type: "string" format: "date-time" } id: { type: "string" description: "Unique identifier of this poll." } options: { type: "array" items: { type: "object" description: "Describes a choice in a Poll object." required: ["position", "label", "votes"] properties: { label: { type: "string" description: "The text of a poll choice." } position: { type: "integer" description: "Position of this choice in the poll." } votes: { type: "integer" description: "Number of users who voted for this choice." } } } } voting_status: { type: "string" enum: ["open", "closed"] } } } } topics: { type: "array" items: { type: "object" description: "The topic of a Space, as selected by its creator." required: ["id", "name"] properties: { description: { type: "string" description: "The description of the given topic." } id: { type: "string" description: "Unique identifier of this Topic." } name: { type: "string" description: "The name of the given topic." } } } } tweets: { type: "array" items: { type: "object" properties: { attachments: { type: "object" description: "Specifies the type of attachments (if any) present in this Tweet." properties: { media_keys: { type: "array" description: "A list of Media Keys for each one of the media attachments (if media are attached)." items: { type: "string" description: "The Media Key identifier for this attachment." } } media_source_tweet_id: { type: "array" description: "A list of Posts the media on this Tweet was originally posted in. For example, if the media on a tweet is re-used in another Tweet, this refers to the original, source Tweet.." items: { type: "string" description: "Unique identifier of this Tweet. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers." } } poll_ids: { type: "array" description: "A list of poll IDs (if polls are attached)." items: { type: "string" description: "Unique identifier of this poll." } } } } author_id: { type: "string" description: "Unique identifier of this User. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers." } community_id: { type: "string" description: "The unique identifier of this Community." } context_annotations: { type: "array" items: { type: "object" description: "Annotation inferred from the Tweet text." required: ["domain", "entity"] properties: { domain: { type: "object" description: "Represents the data for the context annotation domain." required: ["id"] properties: { description: { type: "string" description: "Description of the context annotation domain." } id: { type: "string" description: "The unique id for a context annotation domain." } name: { type: "string" description: "Name of the context annotation domain." } } } entity: { type: "object" description: "Represents the data for the context annotation entity." required: ["id"] properties: { description: { type: "string" description: "Description of the context annotation entity." } id: { type: "string" description: "The unique id for a context annotation entity." } name: { type: "string" description: "Name of the context annotation entity." } } } } } } conversation_id: { type: "string" description: "Unique identifier of this Tweet. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers." } created_at: { type: "string" format: "date-time" description: "Creation time of the Tweet." } display_text_range: { type: "array" description: "Represent a boundary range (start and end zero-based indices) for the portion of text that is displayed for a post. `start` must be smaller than `end`. The start index is inclusive, the end index is exclusive." items: { type: "integer" } } edit_controls: { type: "object" required: ["is_edit_eligible", "editable_until", "edits_remaining"] properties: { editable_until: { type: "string" format: "date-time" description: "Time when Tweet is no longer editable." } edits_remaining: { type: "integer" description: "Number of times this Tweet can be edited." } is_edit_eligible: { type: "boolean" description: "Indicates if this Tweet is eligible to be edited." } } } edit_history_tweet_ids: { type: "array" description: "A list of Tweet Ids in this Tweet chain." items: { type: "string" description: "Unique identifier of this Tweet. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers." } } entities: { type: "object" properties: { annotations: { type: "array" items: { description: "Annotation for entities based on the Tweet text." type: "object" } } cashtags: { type: "array" items: { type: "object" } } hashtags: { type: "array" items: { type: "object" } } mentions: { type: "array" items: { type: "object" } } urls: { type: "array" items: { description: "Represent the portion of text recognized as a URL, and its start and end position within the text." type: "object" } } } } geo: { type: "object" description: "The location tagged on the Tweet, if the user provided one." properties: { coordinates: { type: "object" description: "A [GeoJson Point](https://tools.ietf.org/html/rfc7946#section-3.1.2) geometry object." required: ["type", "coordinates"] properties: { coordinates: { type: "array" description: "A [GeoJson Position](https://tools.ietf.org/html/rfc7946#section-3.1.1) in the format `[longitude,latitude]`." items: { type: "number" } } type: { type: "string" enum: ["Point"] } } } place_id: { type: "string" description: "The identifier for this place." } } } id: { type: "string" description: "Unique identifier of this Tweet. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers." } in_reply_to_user_id: { type: "string" description: "Unique identifier of this User. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers." } lang: { type: "string" description: "Language of the Tweet, if detected by X. Returned as a BCP47 language tag." } matched_media_notes: { type: "object" description: "The matched media notes for the post." properties: { match_status: { type: "string" description: "The status of the media note match." } note_id: { type: "string" description: "The unique identifier of this Community Note." } } } non_public_metrics: { type: "object" description: "Nonpublic engagement metrics for the Tweet at the time of the request." properties: { impression_count: { type: "integer" format: "int32" description: "Number of times this Tweet has been viewed." } } } note_request_suggestions: { type: "object" description: "The note request suggestions for the post." properties: { source_link: { description: "Represent the portion of text recognized as a URL, and its start and end position within the text." type: "object" } suggestion: { type: "string" description: "The text of the note request suggestion." } suggestion_id: { type: "string" description: "The unique identifier of the note request suggestion." } } } note_tweet: { type: "object" description: "The full-content of the Tweet, including text beyond 280 characters." properties: { entities: { type: "object" properties: { cashtags: { type: "array" items: { type: "object" } } hashtags: { type: "array" items: { type: "object" } } mentions: { type: "array" items: { type: "object" } } urls: { type: "array" items: { description: "Represent the portion of text recognized as a URL, and its start and end position within the text." type: "object" } } } } text: { type: "string" description: "The note content of the Tweet." } } } organic_metrics: { type: "object" description: "Organic nonpublic engagement metrics for the Tweet at the time of the request." required: ["impression_count", "retweet_count", "reply_count", "like_count"] properties: { impression_count: { type: "integer" description: "Number of times this Tweet has been viewed." } like_count: { type: "integer" description: "Number of times this Tweet has been liked." } reply_count: { type: "integer" description: "Number of times this Tweet has been replied to." } retweet_count: { type: "integer" description: "Number of times this Tweet has been Retweeted." } } } paid_partnership: { type: "boolean" description: "Indicates if this Post is a paid partnership, i.e. it has been disclosed by the author as containing paid promotion." } possibly_sensitive: { type: "boolean" description: "Indicates if this Tweet contains URLs marked as sensitive, for example content suitable for mature audiences." } promoted_metrics: { type: "object" description: "Promoted nonpublic engagement metrics for the Tweet at the time of the request." properties: { impression_count: { type: "integer" format: "int32" description: "Number of times this Tweet has been viewed." } like_count: { type: "integer" format: "int32" description: "Number of times this Tweet has been liked." } reply_count: { type: "integer" format: "int32" description: "Number of times this Tweet has been replied to." } retweet_count: { type: "integer" format: "int32" description: "Number of times this Tweet has been Retweeted." } } } public_metrics: { type: "object" description: "Engagement metrics for the Tweet at the time of the request." required: ["retweet_count", "reply_count", "like_count", "impression_count", "bookmark_count"] properties: { bookmark_count: { type: "integer" format: "int32" description: "Number of times this Tweet has been bookmarked." } impression_count: { type: "integer" format: "int32" description: "Number of times this Tweet has been viewed." } like_count: { type: "integer" description: "Number of times this Tweet has been liked." } quote_count: { type: "integer" description: "Number of times this Tweet has been quoted." } reply_count: { type: "integer" description: "Number of times this Tweet has been replied to." } retweet_count: { type: "integer" description: "Number of times this Tweet has been Retweeted." } } } referenced_tweets: { type: "array" description: "A list of Posts this Tweet refers to. For example, if the parent Tweet is a Retweet, a Quoted Tweet or a Reply, it will include the related Tweet referenced to by its parent." items: { type: "object" required: ["type", "id"] properties: { id: { type: "string" description: "Unique identifier of this Tweet. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers." } type: { type: "string" enum: ["retweeted", "quoted", "replied_to"] } } } } reply_settings: { type: "string" description: "Shows who can reply a Tweet. Fields returned are everyone, mentioned_users, subscribers, verified and following." enum: ["everyone", "mentionedUsers", "following", "other", "subscribers", "verified"] } scopes: { type: "object" description: "The scopes for this tweet" properties: { followers: { type: "boolean" description: "Indicates if this Tweet is viewable by followers without the Tweet ID" } } } source: { type: "string" description: "This is deprecated." } suggested_source_links: { type: "array" items: { description: "Represent the portion of text recognized as a URL, and its start and end position within the text." type: "object" } } suggested_source_links_with_counts: { type: "object" description: "Suggested source links and the number of requests that included each link." properties: { count: { type: "integer" description: "Number of note requests that included the source link." } url: { description: "Represent the portion of text recognized as a URL, and its start and end position within the text." type: "object" } } } text: { type: "string" description: "The content of the Tweet." } username: { type: "string" description: "The X handle (screen name) of this user." } withheld: { type: "object" description: "Indicates withholding details for [withheld content](https://help.twitter.com/en/rules-and-policies/tweet-withheld-by-country)." required: ["copyright", "country_codes"] properties: { copyright: { type: "boolean" description: "Indicates if the content is being withheld for on the basis of copyright infringement." } country_codes: { type: "array" description: "Provides a list of countries where this content is not available." items: { type: "string" description: "A two-letter ISO 3166-1 alpha-2 country code." } } scope: { type: "string" description: "Indicates whether the content being withheld is the `tweet` or a `user`." enum: ["tweet", "user"] } } } } } } users: { type: "array" items: { type: "object" description: "The X User object." required: ["id", "name", "username"] properties: { affiliation: { type: "object" description: "Metadata about a user's affiliation." properties: { badge_url: { type: "string" format: "uri" description: "The badge URL corresponding to the affiliation." } description: { type: "string" description: "The description of the affiliation." } url: { type: "string" format: "uri" description: "The URL, if available, to details about an affiliation." } user_id: { type: "array" items: { type: "string" description: "Unique identifier of this User. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers." } } } } connection_status: { type: "array" description: "Returns detailed information about the relationship between two users." items: { type: "string" description: "Type of connection between users." enum: ["follow_request_received", "follow_request_sent", "blocking", "followed_by", "following", "muting"] } } created_at: { type: "string" format: "date-time" description: "Creation time of this User." } description: { type: "string" description: "The text of this User's profile description (also known as bio), if the User provided one." } entities: { type: "object" description: "A list of metadata found in the User's profile description." properties: { description: { type: "object" properties: { annotations: { type: "array" items: { description: "Annotation for entities based on the Tweet text." type: "object" } } cashtags: { type: "array" items: { type: "object" } } hashtags: { type: "array" items: { type: "object" } } mentions: { type: "array" items: { type: "object" } } urls: { type: "array" items: { description: "Represent the portion of text recognized as a URL, and its start and end position within the text." type: "object" } } } } url: { type: "object" description: "Expanded details for the URL specified in the User's profile, with start and end indices." properties: { urls: { type: "array" items: { description: "Represent the portion of text recognized as a URL, and its start and end position within the text." type: "object" } } } } } } id: { type: "string" description: "Unique identifier of this User. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers." } location: { type: "string" description: "The location specified in the User's profile, if the User provided one. As this is a freeform value, it may not indicate a valid location, but it may be fuzzily evaluated when performing searches with location queries." } most_recent_tweet_id: { type: "string" description: "Unique identifier of this Tweet. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers." } name: { type: "string" description: "The friendly name of this User, as shown on their profile." } pinned_tweet_id: { type: "string" description: "Unique identifier of this Tweet. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers." } profile_banner_url: { type: "string" format: "uri" description: "The URL to the profile banner for this User." } profile_image_url: { type: "string" format: "uri" description: "The URL to the profile image for this User." } protected: { type: "boolean" description: "Indicates if this User has chosen to protect their Posts (in other words, if this User's Posts are private)." } public_metrics: { type: "object" description: "A list of metrics for this User." required: ["followers_count", "following_count", "tweet_count", "listed_count"] properties: { followers_count: { type: "integer" description: "Number of Users who are following this User." } following_count: { type: "integer" description: "Number of Users this User is following." } like_count: { type: "integer" description: "The number of likes created by this User." } listed_count: { type: "integer" description: "The number of lists that include this User." } tweet_count: { type: "integer" description: "The number of Posts (including Retweets) posted by this User." } } } receives_your_dm: { type: "boolean" description: "Indicates if you can send a DM to this User" } subscription_type: { type: "string" description: "The X Blue subscription type of the user, eg: Basic, Premium, PremiumPlus or None." enum: ["Basic", "Premium", "PremiumPlus", "None"] } url: { type: "string" description: "The URL specified in the User's profile." } username: { type: "string" description: "The X handle (screen name) of this user." } verified: { type: "boolean" description: "Indicate if this User is a verified X User." } verified_type: { type: "string" description: "The X Blue verified type of the user, eg: blue, government, business or none." enum: ["blue", "government", "business", "none"] } withheld: { type: "object" description: "Indicates withholding details for [withheld content](https://help.twitter.com/en/rules-and-policies/tweet-withheld-by-country)." required: ["country_codes"] properties: { country_codes: { type: "array" description: "Provides a list of countries where this content is not available." items: { type: "string" description: "A two-letter ISO 3166-1 alpha-2 country code." } } scope: { type: "string" description: "Indicates that the content being withheld is a `user`." enum: ["user"] } } } } } } } } meta: { type: "object" properties: { next_token: { type: "string" description: "The next token." } previous_token: { type: "string" description: "The previous token." } } } } } }