X

The X connector provides integration with a social media platform, enabling the retrieval and analysis of user-generated content and profiles.

X is a powerful social media platform that offers comprehensive search capabilities across its full archive, recent posts, and detailed user profiles. The X connector for Swimlane Turbine enables users to perform full archive searches, recent searches, and user lookups directly within the Swimlane platform. By integrating with X, security teams can harness social media intelligence to enhance threat detection, investigation, and response workflows, leveraging rich social data for security automation and actionable insights.

Limitations

Application-only authentication doesn't include any user-context and is a form of authentication where an application makes API requests on its own behalf. When accessing the REST API, the application uses the App only Access Token to authenticate.

With application-only authentication, you can perform actions such as:

Pull user timelines

Access friends and followers of any account

Access lists resources

Search Tweets

Supported Version

The X connector supports the following versions of the X API:

OAuth 2.0 Bearer Token in X API v2:

Fully supported for app-only authentication.

Used for requests where user authentication is not required (accessing public information).

OAuth 2.0 Bearer Token in X API v1.1:

Supported for specific app-only requests (public data).

Does not replace OAuth 1.0a for user-specific requests.

Configuration

Prerequisites

To effectively utilize the X connector within the Swimlane Turbine platform, ensure you have the following prerequisites:

Custom authentication with the following parameters:

URL: The endpoint for the X API service.

API KEY: Your unique Consumer API Key provided by X.

API SECRET KEY: Your Consumer Secret Key associated with the API Key for secure access.

Authentication Methods

OAuth 2.0 Bearer Token Authentication

Setup Instructions:

You will need to sign up for a developer account and to have created a Twitter App. Once you have those, you'll also need to obtain the API keys found in the developer portal. Follow the steps below:

Navigate to the Twitter App dashboard and open the Twitter App for which you would like to generate access tokens.

Navigate to the "keys and tokens" page.

You'll find the API keys, user Access Tokens on this page.

You can find the Bearer Token for your App with the rest of your "Keys and Tokens".

Copy the following cURL request into your command line after making changes to the following consumer API keys previously obtained from your Twitter App. Note that the consumer API keys used on this page have been decommissioned and will not work for real requests.

API key <API key> e.g.xvz1evFS4wEEPTGEFPHBog
API secret key <API secret key> e.g. L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg

curl -u "$API_KEY:$API_SECRET_KEY" \
  --data 'grant_type=client_credentials' \
  'https://api.x.com/oauth2/token'

Document References:

https://developer.x.com/en/docs/authentication/oauth-2-0/bearer-tokens

https://developer.x.com/en/docs/authentication/oauth-2-0/application-only

Troubleshoot Tips

Note that one App only Access Token is valid for an application at a time. Issuing another request with the same credentials to /oauth2/token will return the same token until it is invalidated.

Capabilities

Full Archive Search

Recent Search

Users Lookup

Full Archive Search

The full-archive search endpoint returns the complete history of public Tweets matching a search query; since the first Tweet was created March 26, 2006. The Tweets returned by this endpoint count towards the Project-level Tweet cap. Only available to those with Pro and Enterprise access More details can be find here.

Recent Search

The recent search endpoint returns Tweets from the last seven days that match a search query. The Tweets returned by this endpoint count towards the Project-level Tweet cap. OAuth 2.0 scopes required by this endpoint : tweet.read , users.read. More details can be find here.

Users Lookup

Returns a variety of information about one or more users specified by their usernames. OAuth 2.0 scopes required by this endpoint : tweet.read , users.read. More details can be find here.

Configurations

X OAuth 2.0 Bearer Token Authentication

Authenticates using Consumer API Key and Consumer Secret Key.

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
api_key	Consumer Key.	string	Required
api_secret_key	Consumer Secret Key.	string	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Actions

Full Archive Search

Executes a comprehensive search within X's full archive using the 'query' parameter to retrieve relevant posts.

Endpoint

URL: /2/tweets/search/all

Method: GET

Input

Argument Name	Type	Required	Description
parameters.query	string	Required	One query/rule/filter for matching Posts. Refer to https://t.co/rulelength to identify the max query length. The string length should be between 1 and 4096 characters.
parameters.start_time	string	Optional	YYYY-MM-DDTHH:mm:ssZ. The oldest UTC timestamp from which the Posts will be provided. Timestamp is in second granularity and is inclusive (i.e. 12:00:01 includes the first second of the minute).
parameters.end_time	string	Optional	YYYY-MM-DDTHH:mm:ssZ. The newest, most recent UTC timestamp to which the Posts will be provided. Timestamp is in second granularity and is exclusive (i.e. 12:00:01 excludes the first second of the minute).
parameters.since_id	string	Optional	Returns results with a Post ID greater than (that is, more recent than) the specified ID.
parameters.until_id	string	Optional	Returns results with a Post ID less than (that is, older than) the specified ID.
parameters.max_results	number	Optional	The maximum number of search results to be returned by a request. Required range 10 < x < 500.
parameters.next_token	string	Optional	This parameter is used to get the next 'page' of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified. Minimum length - 1.
parameters.pagination_token	string	Optional	This parameter is used to get the next 'page' of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified. Minimum length - 1.
parameters.sort_order	string	Optional	This order in which to return results.
parameters.tweet.fields	string	Optional	A comma separated list of Tweet fields to display. Possible values are 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, media_metadata, non_public_metrics, note_tweet, organic_metrics, possibly_sensitive, promoted_metrics, public_metrics, referenced_tweets, reply_settings, scopes, source, text, withheld.
parameters.expansions	string	Optional	A comma separated list of fields to expand. Possible values are article.cover_media, article.media_entities, attachments.media_keys, attachments.media_source_tweet, attachments.poll_ids, author_id, edit_history_tweet_ids, entities.mentions.username, geo.place_id, in_reply_to_user_id, entities.note.mentions.username, referenced_tweets.id, referenced_tweets.id.author_id.
parameters.media.fields	string	Optional	A comma separated list of Media fields to display. Possible values are alt_text, duration_ms, height, media_key, non_public_metrics, organic_metrics, preview_image_url, promoted_metrics, public_metrics, type, url, variants, width.
parameters.poll.fields	string	Optional	A comma separated list of Poll fields to display. Possible values are duration_minutes, end_datetime, id, options, voting_status.
parameters.user.fields	string	Optional	A comma separated list of User fields to display. Possible values are affiliation, 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.
parameters.place.fields	string	Optional	A comma separated list of Place fields to display. Possible values are contained_within, country, country_code, full_name, geo, id, name, place_type.

Input Example

{"parameters":{"query":"","start_time":"2023-11-07T05:31:56Z","end_time":"2023-11-07T05:31:56Z","since_id":"","until_id":"","max_results":10,"next_token":"","pagination_token":"","sort_order":"recency","tweet.fields":"author_id, created_at, id","expansions":"author_id, edit_history_tweet_ids","media.fields":"height, promoted_metrics, duration_ms","poll.fields":"duration_minutes, end_datetime","user.fields":"entities, created_at","place.fields":"country, full_name"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
data	array	Response data
data.author_id	string	Response data
data.created_at	string	Response data
data.id	string	Response data
data.edit_history_tweet_ids	array	Response data
data.text	string	Response data
data.username	string	Response data
data.attachments	object	Response data
data.attachments.media_keys	array	Response data
data.attachments.media_source_tweet_id	array	Response data
data.attachments.poll_ids	array	Response data
data.community_id	string	Response data
data.context_annotations	array	Response data
data.context_annotations.domain	object	Response data
data.context_annotations.domain.id	string	Response data
data.context_annotations.domain.description	string	Response data
data.context_annotations.domain.name	string	Response data
data.context_annotations.entity	object	Response data
data.context_annotations.entity.id	string	Response data
data.context_annotations.entity.description	string	Response data
data.context_annotations.entity.name	string	Response data
data.conversation_id	string	Response data
data.edit_controls	object	Response data

Output Example

{"data":[{"author_id":"string","created_at":"string","id":"12345678-1234-1234-1234-123456789abc","edit_history_tweet_ids":[],"text":"string","username":"Example Name","attachments":{},"community_id":"string","context_annotations":[],"conversation_id":"string","edit_controls":{},"entities":{},"geo":{},"in_reply_to_user_id":"string","lang":"string"}],"errors":[{"title":"string","type":"string","detail":"string","status":123}],"includes":{"media":[{}],"places":[{}],"polls":[{}],"topics":[{}],"tweet...

Recent Search

Retrieves Tweets from the past week that match a specified 'query' parameter, contributing to the project-level Tweet cap.

Endpoint

URL: /2/tweets/search/recent

Method: GET

Input

Argument Name	Type	Required	Description
parameters.query	string	Required	One query/rule/filter for matching Posts. Refer to https://t.co/rulelength to identify the max query length. The string length should be between 1 and 4096 characters.
parameters.start_time	string	Optional	YYYY-MM-DDTHH:mm:ssZ. The oldest UTC timestamp from which the Posts will be provided. Timestamp is in second granularity and is inclusive (i.e. 12:00:01 includes the first second of the minute).
parameters.end_time	string	Optional	YYYY-MM-DDTHH:mm:ssZ. The newest, most recent UTC timestamp to which the Posts will be provided. Timestamp is in second granularity and is exclusive (i.e. 12:00:01 excludes the first second of the minute).
parameters.since_id	string	Optional	Returns results with a Post ID greater than (that is, more recent than) the specified ID.
parameters.until_id	string	Optional	Returns results with a Post ID less than (that is, older than) the specified ID.
parameters.max_results	number	Optional	The maximum number of search results to be returned by a request. Required range 10 < x < 100.
parameters.next_token	string	Optional	This parameter is used to get the next 'page' of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified. Minimum length - 1.
parameters.pagination_token	string	Optional	This parameter is used to get the next 'page' of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified. Minimum length - 1.
parameters.sort_order	string	Optional	This order in which to return results.
parameters.tweet.fields	string	Optional	A comma separated list of Tweet fields to display. Possible values are 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, media_metadata, non_public_metrics, note_tweet, organic_metrics, possibly_sensitive, promoted_metrics, public_metrics, referenced_tweets, reply_settings, scopes, source, text, withheld.
parameters.expansions	string	Optional	A comma separated list of fields to expand. Possible values are article.cover_media, article.media_entities, attachments.media_keys, attachments.media_source_tweet, attachments.poll_ids, author_id, edit_history_tweet_ids, entities.mentions.username, geo.place_id, in_reply_to_user_id, entities.note.mentions.username, referenced_tweets.id, referenced_tweets.id.author_id.
parameters.media.fields	string	Optional	A comma separated list of Media fields to display. Possible values are alt_text, duration_ms, height, media_key, non_public_metrics, organic_metrics, preview_image_url, promoted_metrics, public_metrics, type, url, variants, width.
parameters.poll.fields	string	Optional	A comma separated list of Poll fields to display. Possible values are duration_minutes, end_datetime, id, options, voting_status.
parameters.user.fields	string	Optional	A comma separated list of User fields to display. Possible values are affiliation, 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.
parameters.place.fields	string	Optional	A comma separated list of Place fields to display. Possible values are contained_within, country, country_code, full_name, geo, id, name, place_type.

Input Example

{"parameters":{"query":"","start_time":"2020-01-01T00:00:00Z","end_time":"2020-01-01T00:00:00Z","since_id":"","until_id":"","max_results":10,"next_token":"","pagination_token":"","sort_order":"recency","tweet.fields":"article, author_id","expansions":"attachments.poll_ids, edit_history_tweet_ids","media.fields":"alt_text, duration_ms","poll.fields":"duration_minutes, end_datetime","user.fields":"affiliation, profile_image_url","place.fields":"contained_within, username"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
data	array	Response data
data.author_id	string	Response data
data.created_at	string	Response data
data.id	string	Response data
data.edit_history_tweet_ids	array	Response data
data.text	string	Response data
data.username	string	Response data
data.attachments	object	Response data
data.attachments.media_keys	array	Response data
data.attachments.media_source_tweet_id	array	Response data
data.attachments.poll_ids	array	Response data
data.community_id	string	Response data
data.context_annotations	array	Response data
data.context_annotations.domain	object	Response data
data.context_annotations.domain.id	string	Response data
data.context_annotations.domain.description	string	Response data
data.context_annotations.domain.name	string	Response data
data.context_annotations.entity	object	Response data
data.context_annotations.entity.id	string	Response data
data.context_annotations.entity.description	string	Response data
data.context_annotations.entity.name	string	Response data
data.conversation_id	string	Response data
data.edit_controls	object	Response data

Output Example

Users Lookup

Retrieves detailed profiles and settings for specified users using the 'usernames' parameter.

Endpoint

URL: /2/users/by

Method: GET

Input

Argument Name	Type	Required	Description
parameters.usernames	string	Required	A list of usernames, comma-separated.
parameters.user.fields	string	Optional	A comma separated list of User fields to display. Possible values are affiliation, 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.
parameters.expansions	string	Optional	A comma separated list of fields to expand. Possible values are affiliation.user_id, most_recent_tweet_id, pinned_tweet_id.
parameters.tweet.fields	string	Optional	A comma separated list of Tweet fields to display. Possible values are 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, media_metadata, non_public_metrics, note_tweet, organic_metrics, possibly_sensitive, promoted_metrics, public_metrics, referenced_tweets, reply_settings, scopes, source, text, withheld.

Input Example

{"parameters":{"usernames":"Example Name","user.fields":"string","expansions":"string","tweet.fields":"string"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
data	array	Response data
data.created_at	string	Response data
data.id	string	Response data
data.name	string	Response data
data.protected	boolean	Response data
data.username	string	Response data
data.affiliation	object	Response data
data.affiliation.badge_url	string	Response data
data.affiliation.description	string	Response data
data.affiliation.url	string	Response data
data.affiliation.user_id	string	Response data
data.connection_status	array	Response data
data.description	string	Response data
data.entities	object	Response data
data.entities.description	object	Response data
data.entities.description.annotations	array	Response data
data.entities.description.annotations.end	number	Response data
data.entities.description.annotations.start	number	Response data
data.entities.description.annotations.normalized_text	string	Response data
data.entities.description.annotations.probability	number	Response data
data.entities.description.annotations.type	string	Response data
data.entities.description.cashtags	array	Response data
data.entities.description.cashtags.end	number	Response data

Output Example

{"data":[{"created_at":"string","id":"12345678-1234-1234-1234-123456789abc","name":"Example Name","protected":true,"username":"Example Name","affiliation":{},"connection_status":[],"description":"string","entities":{},"location":"string","most_recent_tweet_id":"string","pinned_tweet_id":"string","profile_banner_url":"string","public_metrics":{},"receives_your_dm":true}],"errors":[{"detail":"string","status":123,"title":"string","type":"string"}],"includes":{"media":[{}],"places":[{}],"polls":[{}...

Response Headers

Header	Description	Example
content-length	The length of the response body in bytes
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Thu, 01 Jan 2024 00:00:00 GMT