Client
- class tweepy.Client(bearer_token=None, consumer_key=None, consumer_secret=None, access_token=None, access_token_secret=None, *, return_type=Response, wait_on_rate_limit=False)
Twitter API v2 Client
New in version 4.0.
- Parameters
bearer_token (str | None) – Twitter API OAuth 2.0 Bearer Token / Access Token
consumer_key (str | None) – Twitter API OAuth 1.0a Consumer Key
consumer_secret (str | None) – Twitter API OAuth 1.0a Consumer Secret
access_token (str | None) – Twitter API OAuth 1.0a Access Token
access_token_secret (str | None) – Twitter API OAuth 1.0a Access Token Secret
return_type (type[dict | requests.Response | Response]) – Type to return from requests to the API
wait_on_rate_limit (bool) – Whether to wait when rate limit is reached
- session
Requests Session used to make requests to the API
- Type
Twitter API v2 Endpoint |
|
|---|---|
Tweets
Bookmarks
- Client.remove_bookmark(tweet_id)
Allows a user or authenticated user ID to remove a Bookmark of a Tweet.
Note
A request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once per
Clientinstance for each access token used.New in version 4.8.
- Parameters
tweet_id (int | str) – The ID of the Tweet that you would like the
idto remove a Bookmark of.- Raises
TypeError – If the access token isn’t set
- Returns
- Return type
References
- Client.get_bookmarks(*, expansions=None, max_results=None, media_fields=None, pagination_token=None, place_fields=None, poll_fields=None, tweet_fields=None, user_fields=None)
Allows you to get an authenticated user’s 800 most recent bookmarked Tweets.
Note
A request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once per
Clientinstance for each access token used.New in version 4.8.
- Parameters
expansions (list[str] | str | None) – expansions Parameter
max_results (int | None) – The maximum number of results to be returned per page. This can be a number between 1 and 100. By default, each page will return 100 results.
media_fields (list[str] | str | None) – media_fields
pagination_token (str | None) – Used to request the next page of results if all results weren’t returned with the latest request, or to go back to the previous page of results. To return the next page, pass the
next_tokenreturned in your previous response. To go back one page, pass theprevious_tokenreturned in your previous response.place_fields (list[str] | str | None) – place_fields
poll_fields (list[str] | str | None) – poll_fields
tweet_fields (list[str] | str | None) – tweet_fields
user_fields (list[str] | str | None) – user_fields
- Raises
TypeError – If the access token isn’t set
- Returns
- Return type
References
- Client.bookmark(tweet_id)
Causes the authenticating user to Bookmark the target Tweet provided in the request body.
Note
A request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once per
Clientinstance for each access token used.New in version 4.8.
- Parameters
tweet_id (int | str) – The ID of the Tweet that you would like the user
idto Bookmark.- Raises
TypeError – If the access token isn’t set
- Returns
- Return type
References
Hide replies
- Client.hide_reply(id, *, user_auth=True)
Hides a reply to a Tweet.
Changed in version 4.5: Added
user_authparameter- Parameters
- Returns
- Return type
References
- Client.unhide_reply(id, *, user_auth=True)
Unhides a reply to a Tweet.
Changed in version 4.5: Added
user_authparameter- Parameters
- Returns
- Return type
References
Likes
- Client.unlike(tweet_id, *, user_auth=True)
Unlike a Tweet.
The request succeeds with no action when the user sends a request to a user they’re not liking the Tweet or have already unliked the Tweet.
Note
When using OAuth 2.0 Authorization Code Flow with PKCE with
user_auth=False, a request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once perClientinstance for each access token used.Changed in version 4.5: Added
user_authparameterChanged in version 4.8: Added support for using OAuth 2.0 Authorization Code Flow with PKCE
Changed in version 4.8: Changed to raise
TypeErrorwhen the access token isn’t set- Parameters
- Raises
TypeError – If the access token isn’t set
- Returns
- Return type
References
- Client.get_liking_users(id, *, expansions=None, max_results=None, media_fields=None, pagination_token=None, place_fields=None, poll_fields=None, tweet_fields=None, user_fields=None, user_auth=False)
Allows you to get information about a Tweet’s liking users.
Changed in version 4.6: Added
max_resultsandpagination_tokenparameters- Parameters
id (int | str) – Tweet ID of the Tweet to request liking users of.
expansions (list[str] | str | None) – expansions Parameter
max_results (int | None) – The maximum number of results to be returned per page. This can be a number between 1 and 100. By default, each page will return 100 results.
media_fields (list[str] | str | None) – media_fields
pagination_token (str | None) – Used to request the next page of results if all results weren’t returned with the latest request, or to go back to the previous page of results. To return the next page, pass the
next_tokenreturned in your previous response. To go back one page, pass theprevious_tokenreturned in your previous response.place_fields (list[str] | str | None) – place_fields
poll_fields (list[str] | str | None) – poll_fields
tweet_fields (list[str] | str | None) – tweet_fields
user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Returns
- Return type
References
- Client.get_liked_tweets(id, *, expansions=None, max_results=None, media_fields=None, pagination_token=None, place_fields=None, poll_fields=None, tweet_fields=None, user_fields=None, user_auth=False)
Allows you to get information about a user’s liked Tweets.
The Tweets returned by this endpoint count towards the Project-level Tweet cap.
- Parameters
id (int | str) – User ID of the user to request liked Tweets for.
expansions (list[str] | str | None) – expansions Parameter
max_results (int | None) – The maximum number of results to be returned per page. This can be a number between 5 and 100. By default, each page will return 100 results.
media_fields (list[str] | str | None) – media_fields
pagination_token (str | None) – Used to request the next page of results if all results weren’t returned with the latest request, or to go back to the previous page of results. To return the next page, pass the
next_tokenreturned in your previous response. To go back one page, pass theprevious_tokenreturned in your previous response.place_fields (list[str] | str | None) – place_fields
poll_fields (list[str] | str | None) – poll_fields
tweet_fields (list[str] | str | None) – tweet_fields
user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Returns
- Return type
References
- Client.like(tweet_id, *, user_auth=True)
Like a Tweet.
Note
When using OAuth 2.0 Authorization Code Flow with PKCE with
user_auth=False, a request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once perClientinstance for each access token used.Changed in version 4.5: Added
user_authparameterChanged in version 4.8: Added support for using OAuth 2.0 Authorization Code Flow with PKCE
Changed in version 4.8: Changed to raise
TypeErrorwhen the access token isn’t set- Parameters
- Raises
TypeError – If the access token isn’t set
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/tweets/likes/api-reference/post-users-id-likes
Manage Tweets
- Client.delete_tweet(id, *, user_auth=True)
Allows an authenticated user ID to delete a Tweet.
New in version 4.3.
Changed in version 4.5: Added
user_authparameter- Parameters
- Returns
- Return type
References
- Client.create_tweet(*, direct_message_deep_link=None, for_super_followers_only=None, place_id=None, media_ids=None, media_tagged_user_ids=None, poll_duration_minutes=None, poll_options=None, quote_tweet_id=None, exclude_reply_user_ids=None, in_reply_to_tweet_id=None, reply_settings=None, text=None, user_auth=True)
Creates a Tweet on behalf of an authenticated user.
New in version 4.3.
Changed in version 4.5: Added
user_authparameter- Parameters
direct_message_deep_link (str | None) – Tweets a link directly to a Direct Message conversation with an account.
for_super_followers_only (bool | None) – Allows you to Tweet exclusively for Super Followers.
place_id (str | None) – Place ID being attached to the Tweet for geo location.
media_ids (list[int | str] | None) – A list of Media IDs being attached to the Tweet. This is only required if the request includes the
tagged_user_ids.media_tagged_user_ids (list[int | str] | None) – A list of User IDs being tagged in the Tweet with Media. If the user you’re tagging doesn’t have photo-tagging enabled, their names won’t show up in the list of tagged users even though the Tweet is successfully created.
poll_duration_minutes (int | None) – Duration of the poll in minutes for a Tweet with a poll. This is only required if the request includes
poll.options.poll_options (list[str] | None) – A list of poll options for a Tweet with a poll.
quote_tweet_id (int | str | None) – Link to the Tweet being quoted.
exclude_reply_user_ids (list[int | str] | None) – A list of User IDs to be excluded from the reply Tweet thus removing a user from a thread.
in_reply_to_tweet_id (int | str | None) – Tweet ID of the Tweet being replied to. Please note that
in_reply_to_tweet_idneeds to be in the request ifexclude_reply_user_idsis present.reply_settings (str | None) – Settings to indicate who can reply to the Tweet. Limited to “mentionedUsers” and “following”. If the field isn’t specified, it will default to everyone.
text (str | None) – Text of the Tweet being created. This field is required if
media.media_idsis not present.user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/tweets/manage-tweets/api-reference/post-tweets
Quote Tweets
- Client.get_quote_tweets(id, *, exclude=None, expansions=None, max_results=None, media_fields=None, pagination_token=None, place_fields=None, poll_fields=None, tweet_fields=None, user_fields=None, user_auth=False)
Returns Quote Tweets for a Tweet specified by the requested Tweet ID.
The Tweets returned by this endpoint count towards the Project-level Tweet cap.
New in version 4.7.
Changed in version 4.11: Added
excludeparameter- Parameters
exclude (list[str] | str | None) – Comma-separated list of the types of Tweets to exclude from the response.
expansions (list[str] | str | None) – expansions Parameter
max_results (int | None) – Specifies the number of Tweets to try and retrieve, up to a maximum of 100 per distinct request. By default, 10 results are returned if this parameter is not supplied. The minimum permitted value is 10. It is possible to receive less than the
max_resultsper request throughout the pagination process.media_fields (list[str] | str | None) – media_fields
pagination_token (str | None) – This parameter is used to move forwards through ‘pages’ of results, based on the value of the
next_token. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.place_fields (list[str] | str | None) – place_fields
poll_fields (list[str] | str | None) – poll_fields
tweet_fields (list[str] | str | None) – tweet_fields
user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Returns
- Return type
References
Retweets
- Client.unretweet(source_tweet_id, *, user_auth=True)
Allows an authenticated user ID to remove the Retweet of a Tweet.
The request succeeds with no action when the user sends a request to a user they’re not Retweeting the Tweet or have already removed the Retweet of.
Note
When using OAuth 2.0 Authorization Code Flow with PKCE with
user_auth=False, a request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once perClientinstance for each access token used.Changed in version 4.5: Added
user_authparameterChanged in version 4.8: Added support for using OAuth 2.0 Authorization Code Flow with PKCE
Changed in version 4.8: Changed to raise
TypeErrorwhen the access token isn’t set- Parameters
- Raises
TypeError – If the access token isn’t set
- Returns
- Return type
References
- Client.get_retweeters(id, *, expansions=None, max_results=None, media_fields=None, pagination_token=None, place_fields=None, poll_fields=None, tweet_fields=None, user_fields=None, user_auth=False)
Allows you to get information about who has Retweeted a Tweet.
Changed in version 4.6: Added
max_resultsandpagination_tokenparameters- Parameters
id (int | str) – Tweet ID of the Tweet to request Retweeting users of.
expansions (list[str] | str | None) – expansions Parameter
max_results (int | None) – The maximum number of results to be returned per page. This can be a number between 1 and 100. By default, each page will return 100 results.
media_fields (list[str] | str | None) – media_fields
pagination_token (str | None) – Used to request the next page of results if all results weren’t returned with the latest request, or to go back to the previous page of results. To return the next page, pass the
next_tokenreturned in your previous response. To go back one page, pass theprevious_tokenreturned in your previous response.place_fields (list[str] | str | None) – place_fields
poll_fields (list[str] | str | None) – poll_fields
tweet_fields (list[str] | str | None) – tweet_fields
user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Returns
- Return type
References
- Client.retweet(tweet_id, *, user_auth=True)
Causes the user ID to Retweet the target Tweet.
Note
When using OAuth 2.0 Authorization Code Flow with PKCE with
user_auth=False, a request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once perClientinstance for each access token used.Changed in version 4.5: Added
user_authparameterChanged in version 4.8: Added support for using OAuth 2.0 Authorization Code Flow with PKCE
Changed in version 4.8: Changed to raise
TypeErrorwhen the access token isn’t set- Parameters
- Raises
TypeError – If the access token isn’t set
- Returns
- Return type
References
Search Tweets
- Client.search_all_tweets(query, *, end_time=None, expansions=None, max_results=None, media_fields=None, next_token=None, place_fields=None, poll_fields=None, since_id=None, sort_order=None, start_time=None, tweet_fields=None, until_id=None, user_fields=None)
This endpoint is only available to those users who have been approved for the Academic Research product track.
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.
Note
By default, a request will return Tweets from up to 30 days ago if the
start_timeparameter is not provided.Changed in version 4.6: Added
sort_orderparameter- Parameters
query (str) – One query for matching Tweets. Up to 1024 characters.
end_time (datetime.datetime | str | None) – YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). Used with
start_time. The newest, most recent UTC timestamp to which the Tweets will be provided. Timestamp is in second granularity and is exclusive (for example, 12:00:01 excludes the first second of the minute). If used withoutstart_time, Tweets from 30 days beforeend_timewill be returned by default. If not specified,end_timewill default to [now - 30 seconds].expansions (list[str] | str | None) – expansions Parameter
max_results (int | None) – The maximum number of search results to be returned by a request. A number between 10 and the system limit (currently 500). By default, a request response will return 10 results.
media_fields (list[str] | str | None) – media_fields
next_token (str | None) – 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. You can learn more by visiting our page on pagination.
place_fields (list[str] | str | None) – place_fields
poll_fields (list[str] | str | None) – poll_fields
since_id (int | str | None) – Returns results with a Tweet ID greater than (for example, more recent than) the specified ID. The ID specified is exclusive and responses will not include it. If included with the same request as a
start_timeparameter, onlysince_idwill be used.sort_order (str | None) – This parameter is used to specify the order in which you want the Tweets returned. By default, a request will return the most recent Tweets first (sorted by recency).
start_time (datetime.datetime | str | None) – YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The oldest UTC timestamp from which the Tweets will be provided. Timestamp is in second granularity and is inclusive (for example, 12:00:01 includes the first second of the minute). By default, a request will return Tweets from up to 30 days ago if you do not include this parameter.
tweet_fields (list[str] | str | None) – tweet_fields
until_id (int | str | None) – Returns results with a Tweet ID less than (that is, older than) the specified ID. Used with
since_id. The ID specified is exclusive and responses will not include it.user_fields (list[str] | str | None) – user_fields
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/tweets/search/api-reference/get-tweets-search-all
- Client.search_recent_tweets(query, *, end_time=None, expansions=None, max_results=None, media_fields=None, next_token=None, place_fields=None, poll_fields=None, since_id=None, sort_order=None, start_time=None, tweet_fields=None, until_id=None, user_fields=None, user_auth=False)
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.
Changed in version 4.6: Added
sort_orderparameter- Parameters
query (str) – One rule for matching Tweets. If you are using a Standard Project at the Basic access level, you can use the basic set of operators and can make queries up to 512 characters long. If you are using an Academic Research Project at the Basic access level, you can use all available operators and can make queries up to 1,024 characters long.
end_time (datetime.datetime | str | None) – YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The newest, most recent UTC timestamp to which the Tweets will be provided. Timestamp is in second granularity and is exclusive (for example, 12:00:01 excludes the first second of the minute). By default, a request will return Tweets from as recent as 30 seconds ago if you do not include this parameter.
expansions (list[str] | str | None) – expansions Parameter
max_results (int | None) – The maximum number of search results to be returned by a request. A number between 10 and 100. By default, a request response will return 10 results.
media_fields (list[str] | str | None) – media_fields
next_token (str | None) – 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.
place_fields (list[str] | str | None) – place_fields
poll_fields (list[str] | str | None) – poll_fields
since_id (int | str | None) – Returns results with a Tweet ID greater than (that is, more recent than) the specified ID. The ID specified is exclusive and responses will not include it. If included with the same request as a
start_timeparameter, onlysince_idwill be used.sort_order (str | None) – This parameter is used to specify the order in which you want the Tweets returned. By default, a request will return the most recent Tweets first (sorted by recency).
start_time (datetime.datetime | str | None) – YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The oldest UTC timestamp (from most recent seven days) from which the Tweets will be provided. Timestamp is in second granularity and is inclusive (for example, 12:00:01 includes the first second of the minute). If included with the same request as a
since_idparameter, onlysince_idwill be used. By default, a request will return Tweets from up to seven days ago if you do not include this parameter.tweet_fields (list[str] | str | None) – tweet_fields
until_id (int | str | None) – Returns results with a Tweet ID less than (that is, older than) the specified ID. The ID specified is exclusive and responses will not include it.
user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Returns
- Return type
References
Timelines
- Client.get_users_mentions(id, *, end_time=None, expansions=None, max_results=None, media_fields=None, pagination_token=None, place_fields=None, poll_fields=None, since_id=None, start_time=None, tweet_fields=None, until_id=None, user_fields=None, user_auth=False)
Returns Tweets mentioning a single user specified by the requested user ID. By default, the most recent ten Tweets are returned per request. Using pagination, up to the most recent 800 Tweets can be retrieved.
The Tweets returned by this endpoint count towards the Project-level Tweet cap.
- Parameters
id (int | str) – Unique identifier of the user for whom to return Tweets mentioning the user. User ID can be referenced using the user/lookup endpoint. More information on Twitter IDs is here.
end_time (datetime.datetime | str | None) –
YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The new UTC timestamp from which the Tweets will be provided. Timestamp is in second granularity and is inclusive (for example, 12:00:01 includes the first second of the minute).
Please note that this parameter does not support a millisecond value.
expansions (list[str] | str | None) – expansions Parameter
max_results (int | None) – Specifies the number of Tweets to try and retrieve, up to a maximum of 100 per distinct request. By default, 10 results are returned if this parameter is not supplied. The minimum permitted value is 5. It is possible to receive less than the
max_resultsper request throughout the pagination process.media_fields (list[str] | str | None) – media_fields
pagination_token (str | None) – This parameter is used to move forwards or backwards through ‘pages’ of results, based on the value of the
next_tokenorprevious_tokenin the response. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.place_fields (list[str] | str | None) – place_fields
poll_fields (list[str] | str | None) – poll_fields
since_id (int | str | None) – Returns results with a Tweet ID greater than (that is, more recent than) the specified ‘since’ Tweet ID. There are limits to the number of Tweets that can be accessed through the API. If the limit of Tweets has occurred since the
since_id, thesince_idwill be forced to the oldest ID available. More information on Twitter IDs is here.start_time (datetime.datetime | str | None) –
YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The oldest UTC timestamp from which the Tweets will be provided. Timestamp is in second granularity and is inclusive (for example, 12:00:01 includes the first second of the minute).
Please note that this parameter does not support a millisecond value.
tweet_fields (list[str] | str | None) – tweet_fields
until_id (int | str | None) – Returns results with a Tweet ID less less than (that is, older than) the specified ‘until’ Tweet ID. There are limits to the number of Tweets that can be accessed through the API. If the limit of Tweets has occurred since the
until_id, theuntil_idwill be forced to the most recent ID available. More information on Twitter IDs is here.user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Returns
- Return type
References
- Client.get_home_timeline(*, end_time=None, exclude=None, expansions=None, max_results=None, media_fields=None, pagination_token=None, place_fields=None, poll_fields=None, since_id=None, start_time=None, tweet_fields=None, until_id=None, user_fields=None, user_auth=True)
Allows you to retrieve a collection of the most recent Tweets and Retweets posted by you and users you follow. This endpoint returns up to the last 3200 Tweets.
Note
When using OAuth 2.0 Authorization Code Flow with PKCE with
user_auth=False, a request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once perClientinstance for each access token used.- Parameters
end_time (datetime.datetime | str | None) –
YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The new UTC timestamp from which the Tweets will be provided. Timestamp is in second granularity and is inclusive (for example, 12:00:01 includes the first second of the minute).
Please note that this parameter does not support a millisecond value.
exclude (list[str] | str | None) – Comma-separated list of the types of Tweets to exclude from the response.
expansions (list[str] | str | None) – expansions Parameter
max_results (int | None) – Specifies the number of Tweets to try and retrieve, up to a maximum of 100 per distinct request. By default, 100 results are returned if this parameter is not supplied. The minimum permitted value is 1. It is possible to receive less than the
max_resultsper request throughout the pagination process.media_fields (list[str] | str | None) – media_fields
pagination_token (str | None) – This parameter is used to move forwards or backwards through ‘pages’ of results, based on the value of the
next_tokenorprevious_tokenin the response. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.place_fields (list[str] | str | None) – place_fields
poll_fields (list[str] | str | None) – poll_fields
since_id (int | str | None) – Returns results with a Tweet ID greater than (that is, more recent than) the specified ‘since’ Tweet ID. There are limits to the number of Tweets that can be accessed through the API. If the limit of Tweets has occurred since the
since_id, thesince_idwill be forced to the oldest ID available. More information on Twitter IDs is here.start_time (datetime.datetime | str | None) –
YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The oldest UTC timestamp from which the Tweets will be provided. Timestamp is in second granularity and is inclusive (for example, 12:00:01 includes the first second of the minute).
Please note that this parameter does not support a millisecond value.
tweet_fields (list[str] | str | None) – tweet_fields
until_id (int | str | None) – Returns results with a Tweet ID less than (that is, older than) the specified ‘until’ Tweet ID. There are limits to the number of Tweets that can be accessed through the API. If the limit of Tweets has occurred since the
until_id, theuntil_idwill be forced to the most recent ID available. More information on Twitter IDs is here.user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Returns
- Return type
References
- Client.get_users_tweets(id, *, end_time=None, exclude=None, expansions=None, max_results=None, media_fields=None, pagination_token=None, place_fields=None, poll_fields=None, since_id=None, start_time=None, tweet_fields=None, until_id=None, user_fields=None, user_auth=False)
Returns Tweets composed by a single user, specified by the requested user ID. By default, the most recent ten Tweets are returned per request. Using pagination, the most recent 3,200 Tweets can be retrieved.
The Tweets returned by this endpoint count towards the Project-level Tweet cap.
- Parameters
id (int | str) – Unique identifier of the Twitter account (user ID) for whom to return results. User ID can be referenced using the user/lookup endpoint. More information on Twitter IDs is here.
end_time (datetime.datetime | str | None) –
YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The newest or most recent UTC timestamp from which the Tweets will be provided. Only the 3200 most recent Tweets are available. Timestamp is in second granularity and is inclusive (for example, 12:00:01 includes the first second of the minute). Minimum allowable time is 2010-11-06T00:00:01Z
Please note that this parameter does not support a millisecond value.
exclude (list[str] | str | None) – Comma-separated list of the types of Tweets to exclude from the response. When
exclude=retweetsis used, the maximum historical Tweets returned is still 3200. When theexclude=repliesparameter is used for any value, only the most recent 800 Tweets are available.expansions (list[str] | str | None) – expansions Parameter
max_results (int | None) – Specifies the number of Tweets to try and retrieve, up to a maximum of 100 per distinct request. By default, 10 results are returned if this parameter is not supplied. The minimum permitted value is 5. It is possible to receive less than the
max_resultsper request throughout the pagination process.media_fields (list[str] | str | None) – media_fields
pagination_token (str | None) – This parameter is used to move forwards or backwards through ‘pages’ of results, based on the value of the
next_tokenorprevious_tokenin the response. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.place_fields (list[str] | str | None) – place_fields
poll_fields (list[str] | str | None) – poll_fields
since_id (int | str | None) – Returns results with a Tweet ID greater than (that is, more recent than) the specified ‘since’ Tweet ID. Only the 3200 most recent Tweets are available. The result will exclude the
since_id. If the limit of Tweets has occurred since thesince_id, thesince_idwill be forced to the oldest ID available.start_time (datetime.datetime | str | None) –
YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The oldest or earliest UTC timestamp from which the Tweets will be provided. Only the 3200 most recent Tweets are available. Timestamp is in second granularity and is inclusive (for example, 12:00:01 includes the first second of the minute). Minimum allowable time is 2010-11-06T00:00:00Z
Please note that this parameter does not support a millisecond value.
tweet_fields (list[str] | str | None) – tweet_fields
until_id (int | str | None) – Returns results with a Tweet ID less less than (that is, older than) the specified ‘until’ Tweet ID. Only the 3200 most recent Tweets are available. The result will exclude the
until_id. If the limit of Tweets has occurred since theuntil_id, theuntil_idwill be forced to the most recent ID available.user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/tweets/timelines/api-reference/get-users-id-tweets
Tweet counts
- Client.get_all_tweets_count(query, *, end_time=None, granularity=None, next_token=None, since_id=None, start_time=None, until_id=None)
This endpoint is only available to those users who have been approved for the Academic Research product track.
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.
- Parameters
query (str) – One query for matching Tweets. Up to 1024 characters.
end_time (datetime.datetime | str | None) – YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). Used with
start_time. The newest, most recent UTC timestamp to which the Tweets will be provided. Timestamp is in second granularity and is exclusive (for example, 12:00:01 excludes the first second of the minute). If used withoutstart_time, Tweets from 30 days beforeend_timewill be returned by default. If not specified,end_timewill default to [now - 30 seconds].granularity (str | None) – This is the granularity that you want the timeseries count data to be grouped by. You can request
minute,hour, ordaygranularity. The default granularity, if not specified ishour.next_token (str | None) – 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. You can learn more by visiting our page on pagination.
since_id (int | str | None) – Returns results with a Tweet ID greater than (for example, more recent than) the specified ID. The ID specified is exclusive and responses will not include it. If included with the same request as a
start_timeparameter, onlysince_idwill be used.start_time (datetime.datetime | str | None) – YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The oldest UTC timestamp from which the Tweets will be provided. Timestamp is in second granularity and is inclusive (for example, 12:00:01 includes the first second of the minute). By default, a request will return Tweets from up to 30 days ago if you do not include this parameter.
until_id (int | str | None) – Returns results with a Tweet ID less than (that is, older than) the specified ID. Used with
since_id. The ID specified is exclusive and responses will not include it.
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/tweets/counts/api-reference/get-tweets-counts-all
- Client.get_recent_tweets_count(query, *, end_time=None, granularity=None, since_id=None, start_time=None, until_id=None)
The recent Tweet counts endpoint returns count of Tweets from the last seven days that match a search query.
- Parameters
query (str) – One rule for matching Tweets. If you are using a Standard Project at the Basic access level, you can use the basic set of operators and can make queries up to 512 characters long. If you are using an Academic Research Project at the Basic access level, you can use all available operators and can make queries up to 1,024 characters long.
end_time (datetime.datetime | str | None) – YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The newest, most recent UTC timestamp to which the Tweets will be provided. Timestamp is in second granularity and is exclusive (for example, 12:00:01 excludes the first second of the minute). By default, a request will return Tweets from as recent as 30 seconds ago if you do not include this parameter.
granularity (str | None) – This is the granularity that you want the timeseries count data to be grouped by. You can request
minute,hour, ordaygranularity. The default granularity, if not specified ishour.since_id (int | str | None) – Returns results with a Tweet ID greater than (that is, more recent than) the specified ID. The ID specified is exclusive and responses will not include it. If included with the same request as a
start_timeparameter, onlysince_idwill be used.start_time (datetime.datetime | str | None) – YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The oldest UTC timestamp (from most recent seven days) from which the Tweets will be provided. Timestamp is in second granularity and is inclusive (for example, 12:00:01 includes the first second of the minute). If included with the same request as a
since_idparameter, onlysince_idwill be used. By default, a request will return Tweets from up to seven days ago if you do not include this parameter.until_id (int | str | None) – Returns results with a Tweet ID less than (that is, older than) the specified ID. The ID specified is exclusive and responses will not include it.
- Returns
- Return type
References
Tweet lookup
- Client.get_tweet(id, *, expansions=None, media_fields=None, place_fields=None, poll_fields=None, tweet_fields=None, user_fields=None, user_auth=False)
Returns a variety of information about a single Tweet specified by the requested ID.
- Parameters
expansions (list[str] | str | None) – expansions Parameter
media_fields (list[str] | str | None) – media_fields
place_fields (list[str] | str | None) – place_fields
poll_fields (list[str] | str | None) – poll_fields
tweet_fields (list[str] | str | None) – tweet_fields
user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/tweets/lookup/api-reference/get-tweets-id
- Client.get_tweets(ids, *, expansions=None, media_fields=None, place_fields=None, poll_fields=None, tweet_fields=None, user_fields=None, user_auth=False)
Returns a variety of information about the Tweet specified by the requested ID or list of IDs.
- Parameters
ids (list[int | str] | str) – A comma separated list of Tweet IDs. Up to 100 are allowed in a single request. Make sure to not include a space between commas and fields.
expansions (list[str] | str | None) – expansions Parameter
media_fields (list[str] | str | None) – media_fields
place_fields (list[str] | str | None) – place_fields
poll_fields (list[str] | str | None) – poll_fields
tweet_fields (list[str] | str | None) – tweet_fields
user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/tweets/lookup/api-reference/get-tweets
Users
Blocks
- Client.unblock(target_user_id, *, user_auth=True)
Unblock another user.
The request succeeds with no action when the user sends a request to a user they’re not blocking or have already unblocked.
Note
When using OAuth 2.0 Authorization Code Flow with PKCE with
user_auth=False, a request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once perClientinstance for each access token used.Changed in version 4.5: Added
user_authparameterChanged in version 4.8: Added support for using OAuth 2.0 Authorization Code Flow with PKCE
Changed in version 4.8: Changed to raise
TypeErrorwhen the access token isn’t set- Parameters
- Raises
TypeError – If the access token isn’t set
- Returns
- Return type
References
- Client.get_blocked(*, expansions=None, max_results=None, pagination_token=None, tweet_fields=None, user_fields=None, user_auth=True)
Returns a list of users who are blocked by the authenticating user.
Note
When using OAuth 2.0 Authorization Code Flow with PKCE with
user_auth=False, a request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once perClientinstance for each access token used.Changed in version 4.5: Added
user_authparameterChanged in version 4.8: Added support for using OAuth 2.0 Authorization Code Flow with PKCE
Changed in version 4.8: Changed to raise
TypeErrorwhen the access token isn’t set- Parameters
expansions (list[str] | str | None) – expansions Parameter
max_results (int | None) – The maximum number of results to be returned per page. This can be a number between 1 and 1000. By default, each page will return 100 results.
pagination_token (str | None) – Used to request the next page of results if all results weren’t returned with the latest request, or to go back to the previous page of results.
tweet_fields (list[str] | str | None) – tweet_fields
user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Raises
TypeError – If the access token isn’t set
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/users/blocks/api-reference/get-users-blocking
- Client.block(target_user_id, *, user_auth=True)
Block another user.
Note
When using OAuth 2.0 Authorization Code Flow with PKCE with
user_auth=False, a request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once perClientinstance for each access token used.Changed in version 4.5: Added
user_authparameterChanged in version 4.8: Added support for using OAuth 2.0 Authorization Code Flow with PKCE
Changed in version 4.8: Changed to raise
TypeErrorwhen the access token isn’t set- Parameters
- Raises
TypeError – If the access token isn’t set
- Returns
- Return type
References
Follows
- Client.unfollow_user(target_user_id, *, user_auth=True)
Allows a user ID to unfollow another user.
The request succeeds with no action when the authenticated user sends a request to a user they’re not following or have already unfollowed.
Note
When using OAuth 2.0 Authorization Code Flow with PKCE with
user_auth=False, a request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once perClientinstance for each access token used.Changed in version 4.2: Renamed from
Client.unfollow()Changed in version 4.5: Added
user_authparameterChanged in version 4.8: Added support for using OAuth 2.0 Authorization Code Flow with PKCE
Changed in version 4.8: Changed to raise
TypeErrorwhen the access token isn’t set- Parameters
- Raises
TypeError – If the access token isn’t set
- Returns
- Return type
References
- Client.unfollow(target_user_id, *, user_auth=True)
Alias for
Client.unfollow_user()Deprecated since version 4.2: Use
Client.unfollow_user()instead.
- Client.get_users_followers(id, *, expansions=None, max_results=None, pagination_token=None, tweet_fields=None, user_fields=None, user_auth=False)
Returns a list of users who are followers of the specified user ID.
- Parameters
id (int | str) – The user ID whose followers you would like to retrieve.
expansions (list[str] | str | None) – expansions Parameter
max_results (int | None) – The maximum number of results to be returned per page. This can be a number between 1 and the 1000. By default, each page will return 100 results.
pagination_token (str | None) – Used to request the next page of results if all results weren’t returned with the latest request, or to go back to the previous page of results. To return the next page, pass the
next_tokenreturned in your previous response. To go back one page, pass theprevious_tokenreturned in your previous response.tweet_fields (list[str] | str | None) – tweet_fields
user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/users/follows/api-reference/get-users-id-followers
- Client.get_users_following(id, *, expansions=None, max_results=None, pagination_token=None, tweet_fields=None, user_fields=None, user_auth=False)
Returns a list of users the specified user ID is following.
- Parameters
id (int | str) – The user ID whose following you would like to retrieve.
expansions (list[str] | str | None) – expansions Parameter
max_results (int | None) – The maximum number of results to be returned per page. This can be a number between 1 and the 1000. By default, each page will return 100 results.
pagination_token (str | None) – Used to request the next page of results if all results weren’t returned with the latest request, or to go back to the previous page of results. To return the next page, pass the
next_tokenreturned in your previous response. To go back one page, pass theprevious_tokenreturned in your previous response.tweet_fields (list[str] | str | None) – tweet_fields
user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/users/follows/api-reference/get-users-id-following
- Client.follow_user(target_user_id, *, user_auth=True)
Allows a user ID to follow another user.
If the target user does not have public Tweets, this endpoint will send a follow request.
The request succeeds with no action when the authenticated user sends a request to a user they’re already following, or if they’re sending a follower request to a user that does not have public Tweets.
Note
When using OAuth 2.0 Authorization Code Flow with PKCE with
user_auth=False, a request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once perClientinstance for each access token used.Changed in version 4.2: Renamed from
Client.follow()Changed in version 4.5: Added
user_authparameterChanged in version 4.8: Added support for using OAuth 2.0 Authorization Code Flow with PKCE
Changed in version 4.8: Changed to raise
TypeErrorwhen the access token isn’t set- Parameters
- Raises
TypeError – If the access token isn’t set
- Returns
- Return type
References
- Client.follow(target_user_id, *, user_auth=True)
Alias for
Client.follow_user()Deprecated since version 4.2: Use
Client.follow_user()instead.
Mutes
- Client.unmute(target_user_id, *, user_auth=True)
Allows an authenticated user ID to unmute the target user.
The request succeeds with no action when the user sends a request to a user they’re not muting or have already unmuted.
Note
When using OAuth 2.0 Authorization Code Flow with PKCE with
user_auth=False, a request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once perClientinstance for each access token used.Changed in version 4.5: Added
user_authparameterChanged in version 4.8: Added support for using OAuth 2.0 Authorization Code Flow with PKCE
Changed in version 4.8: Changed to raise
TypeErrorwhen the access token isn’t set- Parameters
- Raises
TypeError – If the access token isn’t set
- Returns
- Return type
References
- Client.get_muted(*, expansions=None, max_results=None, pagination_token=None, tweet_fields=None, user_fields=None, user_auth=True)
Returns a list of users who are muted by the authenticating user.
Note
When using OAuth 2.0 Authorization Code Flow with PKCE with
user_auth=False, a request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once perClientinstance for each access token used.New in version 4.1.
Changed in version 4.5: Added
user_authparameterChanged in version 4.8: Added support for using OAuth 2.0 Authorization Code Flow with PKCE
Changed in version 4.8: Changed to raise
TypeErrorwhen the access token isn’t set- Parameters
expansions (list[str] | str | None) – expansions Parameter
max_results (int | None) – The maximum number of results to be returned per page. This can be a number between 1 and 1000. By default, each page will return 100 results.
pagination_token (str | None) – Used to request the next page of results if all results weren’t returned with the latest request, or to go back to the previous page of results.
tweet_fields (list[str] | str | None) – tweet_fields
user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Raises
TypeError – If the access token isn’t set
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/users/mutes/api-reference/get-users-muting
- Client.mute(target_user_id, *, user_auth=True)
Allows an authenticated user ID to mute the target user.
Note
When using OAuth 2.0 Authorization Code Flow with PKCE with
user_auth=False, a request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once perClientinstance for each access token used.Changed in version 4.5: Added
user_authparameterChanged in version 4.8: Added support for using OAuth 2.0 Authorization Code Flow with PKCE
Changed in version 4.8: Changed to raise
TypeErrorwhen the access token isn’t set- Parameters
- Raises
TypeError – If the access token isn’t set
- Returns
- Return type
References
User lookup
- Client.get_user(*, id=None, username=None, expansions=None, tweet_fields=None, user_fields=None, user_auth=False)
Returns a variety of information about a single user specified by the requested ID or username.
- Parameters
username (str | None) – The Twitter username (handle) of the user.
expansions (list[str] | str | None) – expansions Parameter
tweet_fields (list[str] | str | None) – tweet_fields
user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Raises
TypeError – If ID and username are not passed or both are passed
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/users/lookup/api-reference/get-users-id https://developer.twitter.com/en/docs/twitter-api/users/lookup/api-reference/get-users-by-username-username
- Client.get_users(*, ids=None, usernames=None, expansions=None, tweet_fields=None, user_fields=None, user_auth=False)
Returns a variety of information about one or more users specified by the requested IDs or usernames.
- Parameters
ids (list[int | str] | str | None) – A comma separated list of user IDs. Up to 100 are allowed in a single request. Make sure to not include a space between commas and fields.
usernames (list[str] | str | None) – A comma separated list of Twitter usernames (handles). Up to 100 are allowed in a single request. Make sure to not include a space between commas and fields.
expansions (list[str] | str | None) – expansions Parameter
tweet_fields (list[str] | str | None) – tweet_fields
user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Raises
TypeError – If IDs and usernames are not passed or both are passed
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/users/lookup/api-reference/get-users https://developer.twitter.com/en/docs/twitter-api/users/lookup/api-reference/get-users-by
- Client.get_me(*, expansions=None, tweet_fields=None, user_fields=None, user_auth=True)
Returns information about an authorized user.
New in version 4.5.
- Parameters
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/users/lookup/api-reference/get-users-me
Spaces
Search Spaces
- Client.search_spaces(query, *, expansions=None, max_results=None, space_fields=None, state=None, user_fields=None)
Return live or scheduled Spaces matching your specified search terms
New in version 4.1.
Changed in version 4.2:
stateis now an optional parameter.- Parameters
query (str) – Your search term. This can be any text (including mentions and Hashtags) present in the title of the Space.
expansions (list[str] | str | None) – expansions Parameter
max_results (int | None) – The maximum number of results to return in this request. Specify a value between 1 and 100.
space_fields (list[str] | str | None) – space_fields
state (str | None) – Determines the type of results to return. This endpoint returns all Spaces by default. Use
liveto only return live Spaces orscheduledto only return upcoming Spaces.user_fields (list[str] | str | None) – user_fields
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/spaces/search/api-reference/get-spaces-search
Spaces lookup
- Client.get_spaces(*, ids=None, user_ids=None, expansions=None, space_fields=None, user_fields=None)
Returns details about multiple live or scheduled Spaces (created by the specified user IDs if specified). Up to 100 comma-separated Space or user IDs can be looked up using this endpoint.
New in version 4.1.
- Parameters
ids (list[str] | str | None) – A comma separated list of Spaces (up to 100).
user_ids (list[int | str] | str | None) – A comma separated list of user IDs (up to 100).
expansions (list[str] | str | None) – expansions Parameter
space_fields (list[str] | str | None) – space_fields
user_fields (list[str] | str | None) – user_fields
- Raises
TypeError – If IDs and user IDs are not passed or both are passed
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/api-reference/get-spaces https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/api-reference/get-spaces-by-creator-ids
- Client.get_space(id, *, expansions=None, space_fields=None, user_fields=None)
Returns a variety of information about a single Space specified by the requested ID.
New in version 4.1.
- Parameters
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/api-reference/get-spaces-id
- Client.get_space_buyers(id, *, expansions=None, media_fields=None, place_fields=None, poll_fields=None, tweet_fields=None, user_fields=None)
Returns a list of user who purchased a ticket to the requested Space. You must authenticate the request using the Access Token of the creator of the requested Space.
New in version 4.4.
- Parameters
id (str) – Unique identifier of the Space for which you want to request Tweets.
expansions (list[str] | str | None) – expansions Parameter
media_fields (list[str] | str | None) – media_fields
place_fields (list[str] | str | None) – place_fields
poll_fields (list[str] | str | None) – poll_fields
tweet_fields (list[str] | str | None) – tweet_fields
user_fields (list[str] | str | None) – user_fields
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/api-reference/get-spaces-id-buyers
- Client.get_space_tweets(id, *, expansions=None, media_fields=None, place_fields=None, poll_fields=None, tweet_fields=None, user_fields=None)
Returns Tweets shared in the requested Spaces.
New in version 4.6.
- Parameters
id (str) – Unique identifier of the Space containing the Tweets you’d like to access.
expansions (list[str] | str | None) – expansions Parameter
media_fields (list[str] | str | None) – media_fields
place_fields (list[str] | str | None) – place_fields
poll_fields (list[str] | str | None) – poll_fields
tweet_fields (list[str] | str | None) – tweet_fields
user_fields (list[str] | str | None) – user_fields
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/api-reference/get-spaces-id-tweets
Direct Messages
Direct Messages lookup
- Client.get_direct_message_events(*, dm_conversation_id=None, participant_id=None, dm_event_fields=None, event_types=None, expansions=None, max_results=None, media_fields=None, pagination_token=None, tweet_fields=None, user_fields=None, user_auth=True)
If
dm_conversation_idis passed, returns a list of Direct Messages within the conversation specified. Messages are returned in reverse chronological order.If
participant_idis passed, returns a list of Direct Messages (DM) events within a 1-1 conversation with the user specified. Messages are returned in reverse chronological order.If neither is passed, returns a list of Direct Messages for the authenticated user, both sent and received. Direct Message events are returned in reverse chronological order. Supports retrieving events from the previous 30 days.
Note
There is an alias for this method named
get_dm_events.New in version 4.12.
- Parameters
dm_conversation_id (str | None) – The
idof the Direct Message conversation for which events are being retrieved.participant_id (int | str | None) – The
participant_idof the user that the authenicating user is having a 1-1 conversation with.dm_event_fields (list[str] | str | None) – Extra fields to include in the event payload.
idandevent_typeare returned by default. Thetextvalue isn’t included forParticipantsJoinandParticipantsLeaveevents.event_types (str) – The type of Direct Message event to returm. If not included, all types are returned.
expansions (list[str] | str | None) – expansions Parameter
max_results (int | None) – The maximum number of results to be returned in a page. Must be between 1 and 100. The default is 100.
media_fields (list[str] | str | None) – media_fields
pagination_token (str | None) – Contains either the
next_tokenorprevious_tokenvalue.tweet_fields (list[str] | str | None) – tweet_fields
user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Raises
TypeError – If both
dm_conversation_idandparticipant_idare passed- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/direct-messages/lookup/api-reference/get-dm_events https://developer.twitter.com/en/docs/twitter-api/direct-messages/lookup/api-reference/get-dm_conversations-with-participant_id-dm_events https://developer.twitter.com/en/docs/twitter-api/direct-messages/lookup/api-reference/get-dm_conversations-dm_conversation_id-dm_events
Manage Direct Messages
- Client.create_direct_message(*, dm_conversation_id=None, participant_id=None, media_id=None, text=None, user_auth=True)
If
dm_conversation_idis passed, creates a Direct Message on behalf of the authenticated user, and adds it to the specified conversation.If
participant_idis passed, creates a one-to-one Direct Message and adds it to the one-to-one conversation. This method either creates a new one-to-one conversation or retrieves the current conversation and adds the Direct Message to it.Note
There is an alias for this method named
create_dm.New in version 4.12.
- Parameters
dm_conversation_id (str | None) – The
dm_conversation_idof the conversation to add the Direct Message to. Supports both 1-1 and group conversations.participant_id (int | str | None) – The User ID of the account this one-to-one Direct Message is to be sent to.
media_id (int | str | None) – A single Media ID being attached to the Direct Message. This field is required if
textis not present. For this launch, only 1 attachment is supported.text (str | None) – Text of the Direct Message being created. This field is required if
media_idis not present. Text messages support up to 10,000 characters.user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Raises
TypeError – If
dm_conversation_idandparticipant_idare not passed or both are passed- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/direct-messages/manage/api-reference/post-dm_conversations-dm_conversation_id-messages https://developer.twitter.com/en/docs/twitter-api/direct-messages/manage/api-reference/post-dm_conversations-with-participant_id-messages
- Client.create_direct_message_conversation(*, media_id=None, text=None, participant_ids, user_auth=True)
Creates a new group conversation and adds a Direct Message to it on behalf of the authenticated user.
Note
There is an alias for this method named
create_dm_conversation.New in version 4.12.
- Parameters
media_id (int | str | None) – A single Media ID being attached to the Direct Message. This field is required if
textis not present. For this launch, only 1 attachment is supported.text (str | None) – Text of the Direct Message being created. This field is required if
media_idis not present. Text messages support up to 10,000 characters.participant_ids (list[int | str]) – An array of User IDs that the conversation is created with. Conversations can have up to 50 participants.
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Returns
- Return type
References
Lists
List Tweets lookup
- Client.get_list_tweets(id, *, expansions=None, max_results=None, media_fields=None, pagination_token=None, place_fields=None, poll_fields=None, tweet_fields=None, user_fields=None, user_auth=False)
Returns a list of Tweets from the specified List.
New in version 4.4.
Changed in version 4.10.1: Added
media_fields,place_fields, andpoll_fieldsparameters- Parameters
id (list[str] | str) – The ID of the List whose Tweets you would like to retrieve.
expansions (list[str] | str | None) – expansions Parameter
max_results (int | None) – The maximum number of results to be returned per page. This can be a number between 1 and 100. By default, each page will return 100 results.
media_fields (list[str] | str | None) – media_fields
pagination_token (str | None) – Used to request the next page of results if all results weren’t returned with the latest request, or to go back to the previous page of results. To return the next page, pass the next_token returned in your previous response. To go back one page, pass the previous_token returned in your previous response.
place_fields (list[str] | str | None) – place_fields
poll_fields (list[str] | str | None) – poll_fields
tweet_fields (list[str] | str | None) – tweet_fields
user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Returns
- Return type
References
List follows
- Client.unfollow_list(list_id, *, user_auth=True)
Enables the authenticated user to unfollow a List.
Note
When using OAuth 2.0 Authorization Code Flow with PKCE with
user_auth=False, a request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once perClientinstance for each access token used.New in version 4.2.
Changed in version 4.5: Added
user_authparameterChanged in version 4.8: Added support for using OAuth 2.0 Authorization Code Flow with PKCE
Changed in version 4.8: Changed to raise
TypeErrorwhen the access token isn’t set- Parameters
- Raises
TypeError – If the access token isn’t set
- Returns
- Return type
References
- Client.get_list_followers(id, *, expansions=None, max_results=None, pagination_token=None, tweet_fields=None, user_fields=None, user_auth=False)
Returns a list of users who are followers of the specified List.
New in version 4.4.
- Parameters
id (list[str] | str) – The ID of the List whose followers you would like to retrieve.
expansions (list[str] | str | None) – expansions Parameter
max_results (int | None) – The maximum number of results to be returned per page. This can be a number between 1 and 100. By default, each page will return 100 results.
pagination_token (str | None) – Used to request the next page of results if all results weren’t returned with the latest request, or to go back to the previous page of results. To return the next page, pass the next_token returned in your previous response. To go back one page, pass the previous_token returned in your previous response.
tweet_fields (list[str] | str | None) – tweet_fields
user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Returns
- Return type
References
- Client.get_followed_lists(id, *, expansions=None, list_fields=None, max_results=None, pagination_token=None, user_fields=None, user_auth=False)
Returns all Lists a specified user follows.
New in version 4.4.
- Parameters
id (list[str] | str) – The user ID whose followed Lists you would like to retrieve.
expansions (list[str] | str | None) – expansions Parameter
list_fields (list[str] | str | None) – list_fields
max_results (int | None) – The maximum number of results to be returned per page. This can be a number between 1 and 100. By default, each page will return 100 results.
pagination_token (str | None) – Used to request the next page of results if all results weren’t returned with the latest request, or to go back to the previous page of results. To return the next page, pass the next_token returned in your previous response. To go back one page, pass the previous_token returned in your previous response.
user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Returns
- Return type
References
- Client.follow_list(list_id, *, user_auth=True)
Enables the authenticated user to follow a List.
Note
When using OAuth 2.0 Authorization Code Flow with PKCE with
user_auth=False, a request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once perClientinstance for each access token used.New in version 4.2.
Changed in version 4.5: Added
user_authparameterChanged in version 4.8: Added support for using OAuth 2.0 Authorization Code Flow with PKCE
Changed in version 4.8: Changed to raise
TypeErrorwhen the access token isn’t set- Parameters
- Raises
TypeError – If the access token isn’t set
- Returns
- Return type
References
List lookup
- Client.get_list(id, *, expansions=None, list_fields=None, user_fields=None, user_auth=False)
Returns the details of a specified List.
New in version 4.4.
- Parameters
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/lists/list-lookup/api-reference/get-lists-id
- Client.get_owned_lists(id, *, expansions=None, list_fields=None, max_results=None, pagination_token=None, user_fields=None, user_auth=False)
Returns all Lists owned by the specified user.
New in version 4.4.
- Parameters
id (list[str] | str) – The user ID whose owned Lists you would like to retrieve.
expansions (list[str] | str | None) – expansions Parameter
list_fields (list[str] | str | None) – list_fields
max_results (int | None) – The maximum number of results to be returned per page. This can be a number between 1 and 100. By default, each page will return 100 results.
pagination_token (str | None) – Used to request the next page of results if all results weren’t returned with the latest request, or to go back to the previous page of results. To return the next page, pass the next_token returned in your previous response. To go back one page, pass the previous_token returned in your previous response.
user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Returns
- Return type
References
List members
- Client.remove_list_member(id, user_id, *, user_auth=True)
Enables the authenticated user to remove a member from a List they own.
New in version 4.2.
Changed in version 4.5: Added
user_authparameter- Parameters
- Returns
- Return type
References
- Client.get_list_members(id, *, expansions=None, max_results=None, pagination_token=None, tweet_fields=None, user_fields=None, user_auth=False)
Returns a list of users who are members of the specified List.
New in version 4.4.
- Parameters
id (list[str] | str) – The ID of the List whose members you would like to retrieve.
expansions (list[str] | str | None) – expansions Parameter
max_results (int | None) – The maximum number of results to be returned per page. This can be a number between 1 and 100. By default, each page will return 100 results.
pagination_token (str | None) – Used to request the next page of results if all results weren’t returned with the latest request, or to go back to the previous page of results. To return the next page, pass the next_token returned in your previous response. To go back one page, pass the previous_token returned in your previous response.
tweet_fields (list[str] | str | None) – tweet_fields
user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Returns
- Return type
References
- Client.get_list_memberships(id, *, expansions=None, list_fields=None, max_results=None, pagination_token=None, user_fields=None, user_auth=False)
Returns all Lists a specified user is a member of.
New in version 4.4.
- Parameters
id (list[str] | str) – The user ID whose List memberships you would like to retrieve.
expansions (list[str] | str | None) – expansions Parameter
list_fields (list[str] | str | None) – list_fields
max_results (int | None) – The maximum number of results to be returned per page. This can be a number between 1 and 100. By default, each page will return 100 results.
pagination_token (str | None) – Used to request the next page of results if all results weren’t returned with the latest request, or to go back to the previous page of results. To return the next page, pass the next_token returned in your previous response. To go back one page, pass the previous_token returned in your previous response.
user_fields (list[str] | str | None) – user_fields
user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate
- Returns
- Return type
References
- Client.add_list_member(id, user_id, *, user_auth=True)
Enables the authenticated user to add a member to a List they own.
New in version 4.2.
Changed in version 4.5: Added
user_authparameter- Parameters
- Returns
- Return type
References
Manage Lists
- Client.delete_list(id, *, user_auth=True)
Enables the authenticated user to delete a List that they own.
New in version 4.2.
Changed in version 4.5: Added
user_authparameter- Parameters
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/lists/manage-lists/api-reference/delete-lists-id
- Client.update_list(id, *, description=None, name=None, private=None, user_auth=True)
Enables the authenticated user to update the meta data of a specified List that they own.
New in version 4.2.
Changed in version 4.5: Added
user_authparameter- Parameters
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/lists/manage-lists/api-reference/put-lists-id
- Client.create_list(name, *, description=None, private=None, user_auth=True)
Enables the authenticated user to create a List.
New in version 4.2.
Changed in version 4.5: Added
user_authparameter- Parameters
- Returns
- Return type
References
https://developer.twitter.com/en/docs/twitter-api/lists/manage-lists/api-reference/post-lists
Pinned Lists
- Client.unpin_list(list_id, *, user_auth=True)
Enables the authenticated user to unpin a List.
Note
When using OAuth 2.0 Authorization Code Flow with PKCE with
user_auth=False, a request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once perClientinstance for each access token used.New in version 4.2.
Changed in version 4.5: Added
user_authparameterChanged in version 4.8: Added support for using OAuth 2.0 Authorization Code Flow with PKCE
Changed in version 4.8: Changed to raise
TypeErrorwhen the access token isn’t set- Parameters
- Raises
TypeError – If the access token isn’t set
- Returns
- Return type
References
- Client.get_pinned_lists(*, expansions=None, list_fields=None, user_fields=None, user_auth=True)
Returns the Lists pinned by a specified user.
Note
When using OAuth 2.0 Authorization Code Flow with PKCE with
user_auth=False, a request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once perClientinstance for each access token used.New in version 4.4.
Changed in version 4.5: Added
user_authparameterChanged in version 4.8: Added support for using OAuth 2.0 Authorization Code Flow with PKCE
Changed in version 4.8: Changed to raise
TypeErrorwhen the access token isn’t set- Parameters
- Raises
TypeError – If the access token isn’t set
- Returns
- Return type
References
- Client.pin_list(list_id, *, user_auth=True)
Enables the authenticated user to pin a List.
Note
When using OAuth 2.0 Authorization Code Flow with PKCE with
user_auth=False, a request is made beforehand to Twitter’s API to determine the authenticating user’s ID. This is cached and only done once perClientinstance for each access token used.New in version 4.2.
Changed in version 4.5: Added
user_authparameterChanged in version 4.8: Added support for using OAuth 2.0 Authorization Code Flow with PKCE
Changed in version 4.8: Changed to raise
TypeErrorwhen the access token isn’t set- Parameters
- Raises
TypeError – If the access token isn’t set
- Returns
- Return type
References
Compliance
Batch compliance
- Client.get_compliance_jobs(type, *, status=None)
Returns a list of recent compliance jobs.
New in version 4.1.
- Parameters
- Returns
- Return type
References
- Client.get_compliance_job(id)
Get a single compliance job with the specified ID.
New in version 4.1.
- Parameters
id (int | str) – The unique identifier for the compliance job you want to retrieve.
- Returns
- Return type
References
- Client.create_compliance_job(type, *, name=None, resumable=None)
Creates a new compliance job for Tweet IDs or user IDs.
A compliance job will contain an ID and a destination URL. The destination URL represents the location that contains the list of IDs consumed by your app.
You can run one batch job at a time.
New in version 4.1.
- Parameters
type (str) – Specify whether you will be uploading tweet or user IDs. You can either specify tweets or users.
name (str | None) – A name for this job, useful to identify multiple jobs using a label you define.
resumable (bool | None) – Specifies whether to enable the upload URL with support for resumable uploads. If true, this endpoint will return a pre-signed URL with resumable uploads enabled.
- Returns
- Return type
References