# `tweepy.Client` — Twitter API v2 Reference

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 (Optional[str]) – Twitter API Bearer Token

    - consumer_key (Optional[str]) – Twitter API Consumer Key

    - consumer_secret (Optional[str]) – Twitter API Consumer Secret

    - access_token (Optional[str]) – Twitter API Access Token

    - access_token_secret (Optional[str]) – Twitter API Access Token Secret

    - return_type (Type[Union[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

      requests.Session

  user_agent

    User agent used when making requests to the API

    Type

      str

Twitter API v2 Endpoint | `Client` Method
--- | ---
Tweets
Hide replies
PUT /2/tweets/:id/hidden | `Client.hide_reply()`
PUT /2/tweets/:id/hidden | `Client.unhide_reply()`
Likes
DELETE /2/users/:id/likes/:tweet_id | `Client.unlike()`
GET /2/tweets/:id/liking_users | `Client.get_liking_users()`
GET /2/users/:id/liked_tweets | `Client.get_liked_tweets()`
POST /2/users/:id/likes | `Client.like()`
Manage Tweets
DELETE /2/tweets/:id | `Client.delete_tweet()`
POST /2/tweets | `Client.create_tweet()`
Retweets
DELETE /2/users/:id/retweets/:source_tweet_id | `Client.unretweet()`
GET /2/tweets/:id/retweeted_by | `Client.get_retweeters()`
POST /2/users/:id/retweets | `Client.retweet()`
Search Tweets
GET /2/tweets/search/all | `Client.search_all_tweets()`
GET /2/tweets/search/recent | `Client.search_recent_tweets()`
Timelines
GET /2/users/:id/mentions | `Client.get_users_mentions()`
GET /2/users/:id/tweets | `Client.get_users_tweets()`
Tweet counts
GET /2/tweets/counts/all | `Client.get_all_tweets_count()`
GET /2/tweets/counts/recent | `Client.get_recent_tweets_count()`
Tweet lookup
GET /2/tweets/:id | `Client.get_tweet()`
GET /2/tweets | `Client.get_tweets()`
Users
Blocks
DELETE /2/users/:source_user_id/blocking/:target_user_id | `Client.unblock()`
GET /2/users/:id/blocking | `Client.get_blocked()`
POST /2/users/:id/blocking | `Client.block()`
Follows
DELETE /2/users/:source_user_id/following/:target_user_id | `Client.unfollow_user()`
GET /2/users/:id/followers | `Client.get_users_followers()`
GET /2/users/:id/following | `Client.get_users_following()`
POST /2/users/:id/following | `Client.follow_user()`
Mutes
DELETE /2/users/:source_user_id/muting/:target_user_id | `Client.unmute()`
GET /2/users/:id/muting | `Client.get_muted()`
POST /2/users/:id/muting | `Client.mute()`
User lookup
GET /2/users/:id | `Client.get_user()`
GET /2/users/by/username/:username | `Client.get_user()`
GET /2/users | `Client.get_users()`
GET /2/users/by | `Client.get_users()`
GET /2/users/me | `Client.get_me()`
Spaces
Search Spaces
GET /2/spaces/search | `Client.search_spaces()`
Spaces lookup
GET /2/spaces | `Client.get_spaces()`
GET /2/spaces/:id | `Client.get_space()`
GET /2/spaces/:id/buyers | `Client.get_space_buyers()`
GET /2/spaces/by/creator_ids | `Client.get_spaces()`
Lists
List Tweets lookup
GET /2/lists/:id/tweets | `Client.get_list_tweets()`
List follows
DELETE /2/users/:id/followed_lists/:list_id | `Client.unfollow_list()`
GET /2/lists/:id/followers | `Client.get_list_followers()`
GET /2/users/:id/followed_lists | `Client.get_followed_lists()`
POST /2/users/:id/followed_lists | `Client.follow_list()`
List lookup
GET /2/lists/:id | `Client.get_list()`
GET /2/users/:id/owned_lists | `Client.get_owned_lists()`
List members
DELETE /2/lists/:id/members/:user_id | `Client.remove_list_member()`
GET /2/lists/:id/members | `Client.get_list_members()`
GET /2/users/:id/list_memberships | `Client.get_list_memberships()`
POST /2/lists/:id/members | `Client.add_list_member()`
Manage Lists
DELETE /2/lists/:id | `Client.delete_list()`
PUT /2/lists/:id | `Client.update_list()`
POST /2/lists | `Client.create_list()`
Pinned Lists
DELETE /2/users/:id/pinned_lists/:list_id | `Client.unpin_list()`
GET /2/users/:id/pinned_lists | `Client.get_pinned_lists()`
POST /2/users/:id/pinned_lists | `Client.pin_list()`
Compliance
Batch Compliance
GET /2/compliance/jobs | `Client.get_compliance_jobs()`
GET /2/compliance/jobs/:id | `Client.get_compliance_job()`
POST /2/compliance/jobs | `Client.create_compliance_job()`

## Tweets

### Hide replies

Client.hide_reply(id, *, user_auth=True)

  Hides a reply to a Tweet.

  Changed in version 4.5: Added `user_auth` parameter

  Parameters

    - id (Union[int, str]) – Unique identifier of the Tweet to hide. The Tweet must belong to a conversation initiated by the authenticating user.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/tweets/hide-replies/api-reference/put-tweets-id-hidden

Client.unhide_reply(id, *, user_auth=True)

  Unhides a reply to a Tweet.

  Changed in version 4.5: Added `user_auth` parameter

  Parameters

    - id (Union[int, str]) – Unique identifier of the Tweet to unhide. The Tweet must belong to a conversation initiated by the authenticating user.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/tweets/hide-replies/api-reference/put-tweets-id-hidden

### 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.

  Changed in version 4.5: Added `user_auth` parameter

  Parameters

    - tweet_id (Union[int, str]) – The ID of the Tweet that you would like to unlike.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/tweets/likes/api-reference/delete-users-id-likes-tweet_id

Client.get_liking_users(id, *, expansions, media_fields, place_fields, poll_fields, tweet_fields, user_fields, user_auth=False)

  Allows you to get information about a Tweet’s liking users.

  Parameters

    - id (Union[int, str]) – Tweet ID of the Tweet to request liking users of.

    - expansions (Union[List[str], str]) – expansions

    - media_fields (Union[List[str], str]) – media_fields

    - place_fields (Union[List[str], str]) – place_fields

    - poll_fields (Union[List[str], str]) – poll_fields

    - tweet_fields (Union[List[str], str]) – tweet_fields

    - user_fields (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/tweets/likes/api-reference/get-tweets-id-liking_users

Client.get_liked_tweets(id, *, expansions, max_results, media_fields, pagination_token, place_fields, poll_fields, tweet_fields, user_fields, 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 (Union[int, str]) – User ID of the user to request liked Tweets for.

    - expansions (Union[List[str], str]) – expansions

    - max_results (int) – 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 (Union[List[str], str]) – media_fields

    - pagination_token (str) – 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 (Union[List[str], str]) – place_fields

    - poll_fields (Union[List[str], str]) – poll_fields

    - tweet_fields (Union[List[str], str]) – tweet_fields

    - user_fields (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/tweets/likes/api-reference/get-users-id-liked_tweets

Client.like(tweet_id, *, user_auth=True)

  Like a Tweet.

  Changed in version 4.5: Added `user_auth` parameter

  Parameters

    - tweet_id (Union[int, str]) – The ID of the Tweet that you would like to Like.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  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_auth` parameter

  Parameters

    - id (Union[int, str]) – The Tweet ID you are deleting.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/tweets/manage-tweets/api-reference/delete-tweets-id

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_auth` parameter

  Parameters

    - direct_message_deep_link (Optional[str]) – Tweets a link directly to a Direct Message conversation with an account.

    - for_super_followers_only (Optional[bool]) – Allows you to Tweet exclusively for Super Followers.

    - place_id (Optional[str]) – Place ID being attached to the Tweet for geo location.

    - media_ids (Optional[List[int, str]]) – 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 (Optional[List[Union[int, str]]]) – 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 (Optional[int]) – Duration of the poll in minutes for a Tweet with a poll. This is only required if the request includes `poll.options`.

    - poll_options (Optional[List[str]]) – A list of poll options for a Tweet with a poll.

    - quote_tweet_id (Optional[Union[int, str]]) – Link to the Tweet being quoted.

    - exclude_reply_user_ids (Optional[List[Union[int, str]]]) – A list of User IDs to be excluded from the reply Tweet thus removing a user from a thread.

    - in_reply_to_tweet_id (Optional[Union[int, str]]) – Tweet ID of the Tweet being replied to. Please note that `in_reply_to_tweet_id` needs to be in the request if `exclude_reply_user_ids` is present.

    - reply_settings (Optional[str]) – 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 (Optional[str]) – Text of the Tweet being created. This field is required if `media.media_ids` is not present.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/tweets/manage-tweets/api-reference/post-tweets

### 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.

  Changed in version 4.5: Added `user_auth` parameter

  Parameters

    - source_tweet_id (Union[int, str]) – The ID of the Tweet that you would like to remove the Retweet of.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/tweets/retweets/api-reference/delete-users-id-retweets-tweet_id

Client.get_retweeters(id, *, expansions, media_fields, place_fields, poll_fields, tweet_fields, user_fields, user_auth=False)

  Allows you to get information about who has Retweeted a Tweet.

  Parameters

    - id (Union[int, str]) – Tweet ID of the Tweet to request Retweeting users of.

    - expansions (Union[List[str], str]) – expansions

    - media_fields (Union[List[str], str]) – media_fields

    - place_fields (Union[List[str], str]) – place_fields

    - poll_fields (Union[List[str], str]) – poll_fields

    - tweet_fields (Union[List[str], str]) – tweet_fields

    - user_fields (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/tweets/retweets/api-reference/get-tweets-id-retweeted_by

Client.retweet(tweet_id, *, user_auth=True)

  Causes the user ID to Retweet the target Tweet.

  Changed in version 4.5: Added `user_auth` parameter

  Parameters

    - tweet_id (Union[int, str]) – The ID of the Tweet that you would like to Retweet.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/tweets/retweets/api-reference/post-users-id-retweets

### Search Tweets

Client.search_all_tweets(query, *, end_time, expansions, max_results, media_fields, next_token, place_fields, poll_fields, since_id, start_time, tweet_fields, until_id, user_fields)

  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.

  Parameters

    - query (str) – One query for matching Tweets. Up to 1024 characters.

    - end_time (Union[datetime.datetime, str]) – 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 without `start_time`, Tweets from 30 days before `end_time` will be returned by default. If not specified, `end_time` will default to [now - 30 seconds].

    - expansions (Union[List[str], str]) – expansions

    - max_results (int) – 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 (Union[List[str], str]) – media_fields

    - next_token (str) – 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 (Union[List[str], str]) – place_fields

    - poll_fields (Union[List[str], str]) – poll_fields

    - since_id (Union[int, str]) – 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_time` parameter, only `since_id` will be used.

    - start_time (Union[datetime.datetime, str]) – 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 (Union[List[str], str]) – tweet_fields

    - until_id (Union[int, str]) – 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 (Union[List[str], str]) – user_fields

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/tweets/search/api-reference/get-tweets-search-all

Client.search_recent_tweets(query, *, end_time, expansions, max_results, media_fields, next_token, place_fields, poll_fields, since_id, start_time, tweet_fields, until_id, user_fields, 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.

  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 (Union[datetime.datetime, str]) – 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 (Union[List[str], str]) – expansions

    - max_results (int) – 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 (Union[List[str], str]) – media_fields

    - next_token (str) – 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 (Union[List[str], str]) – place_fields

    - poll_fields (Union[List[str], str]) – poll_fields

    - since_id (Union[int, str]) – 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_time` parameter, only `since_id` will be used.

    - start_time (Union[datetime.datetime, str]) – 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_id` parameter, only `since_id` will be used. By default, a request will return Tweets from up to seven days ago if you do not include this parameter.

    - tweet_fields (Union[List[str], str]) – tweet_fields

    - until_id (Union[int, str]) – 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 (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/tweets/search/api-reference/get-tweets-search-recent

### Timelines

Client.get_users_mentions(id, *, end_time, expansions, max_results, media_fields, pagination_token, place_fields, poll_fields, since_id, start_time, tweet_fields, until_id, user_fields, 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 (Union[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 (Union[datetime.datetime, str]) –

      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 (Union[List[str], str]) – expansions

    - max_results (int) – 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_results` per request throughout the pagination process.

    - media_fields (Union[List[str], str]) – media_fields

    - pagination_token (str) – This parameter is used to move forwards or backwards through ‘pages’ of results, based on the value of the `next_token` or `previous_token` in 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 (Union[List[str], str]) – place_fields

    - poll_fields (Union[List[str], str]) – poll_fields

    - since_id (Union[int, str]) – 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`, the `since_id` will be forced to the oldest ID available. More information on Twitter IDs is here.

    - start_time (Union[datetime.datetime, str]) –

      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 (Union[List[str], str]) – tweet_fields

    - until_id (Union[int, str]) – 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`, the `until_id` will be forced to the most recent ID available. More information on Twitter IDs is here.

    - user_fields (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/tweets/timelines/api-reference/get-users-id-mentions

Client.get_users_tweets(id, *, end_time, exclude, expansions, max_results, media_fields, pagination_token, place_fields, poll_fields, since_id, start_time, tweet_fields, until_id, user_fields, 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 (Union[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 (Union[datetime.datetime, str]) –

      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 (Union[List[str], str]) – Comma-separated list of the types of Tweets to exclude from the response. When `exclude=retweets` is used, the maximum historical Tweets returned is still 3200. When the `exclude=replies` parameter is used for any value, only the most recent 800 Tweets are available.

    - expansions (Union[List[str], str]) – expansions

    - max_results (int) – 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_results` per request throughout the pagination process.

    - media_fields (Union[List[str], str]) – media_fields

    - pagination_token (str) – This parameter is used to move forwards or backwards through ‘pages’ of results, based on the value of the `next_token` or `previous_token` in 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 (Union[List[str], str]) – place_fields

    - poll_fields (Union[List[str], str]) – poll_fields

    - since_id (Union[int, str]) – 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 the `since_id`, the `since_id` will be forced to the oldest ID available.

    - start_time (Union[datetime.datetime, str]) –

      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 (Union[List[str], str]) – tweet_fields

    - until_id (Union[int, str]) – 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 the `until_id`, the `until_id` will be forced to the most recent ID available.

    - user_fields (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  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, granularity, next_token, since_id, start_time, until_id)

  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 (Union[datetime.datetime, str]) – 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 without `start_time`, Tweets from 30 days before `end_time` will be returned by default. If not specified, `end_time` will default to [now - 30 seconds].

    - granularity (str) – This is the granularity that you want the timeseries count data to be grouped by. You can request `minute`, `hour`, or `day` granularity. The default granularity, if not specified is `hour`.

    - next_token (str) – 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 (Union[int, str]) – 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_time` parameter, only `since_id` will be used.

    - start_time (Union[datetime.datetime, str]) – 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 (Union[int, str]) – 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

    Union[dict, requests.Response, Response]

  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, granularity, since_id, start_time, until_id)

  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 (Union[datetime.datetime, str]) – 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) – This is the granularity that you want the timeseries count data to be grouped by. You can request `minute`, `hour`, or `day` granularity. The default granularity, if not specified is `hour`.

    - since_id (Union[int, str]) – 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_time` parameter, only `since_id` will be used.

    - start_time (Union[datetime.datetime, str]) – 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_id` parameter, only `since_id` will be used. By default, a request will return Tweets from up to seven days ago if you do not include this parameter.

    - until_id (Union[int, str]) – 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

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/tweets/counts/api-reference/get-tweets-counts-recent

### Tweet lookup

Client.get_tweet(id, *, expansions, media_fields, place_fields, poll_fields, twitter_fields, user_fields, user_auth=False)

  Returns a variety of information about a single Tweet specified by the requested ID.

  Parameters

    - id (Union[int, str]) – Unique identifier of the Tweet to request

    - expansions (Union[List[str], str]) – expansions

    - media_fields (Union[List[str], str]) – media_fields

    - place_fields (Union[List[str], str]) – place_fields

    - poll_fields (Union[List[str], str]) – poll_fields

    - tweet_fields (Union[List[str], str]) – tweet_fields

    - user_fields (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/tweets/lookup/api-reference/get-tweets-id

Client.get_tweets(ids, *, expansions, media_fields, place_fields, poll_fields, twitter_fields, user_fields, user_auth=False)

  Returns a variety of information about the Tweet specified by the requested ID or list of IDs.

  Parameters

    - ids (Union[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 (Union[List[str], str]) – expansions

    - media_fields (Union[List[str], str]) – media_fields

    - place_fields (Union[List[str], str]) – place_fields

    - poll_fields (Union[List[str], str]) – poll_fields

    - tweet_fields (Union[List[str], str]) – tweet_fields

    - user_fields (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  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.

  Changed in version 4.5: Added `user_auth` parameter

  Parameters

    - target_user_id (Union[int, str]) – The user ID of the user that you would like to unblock.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/users/blocks/api-reference/delete-users-user_id-blocking

Client.get_blocked(*, expansions, max_results, pagination_token, tweet_fields, user_fields, user_auth=True)

  Returns a list of users who are blocked by the authenticating user.

  Changed in version 4.5: Added `user_auth` parameter

  Parameters

    - expansions (Union[List[str], str]) – expansions

    - max_results (int) – 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) – 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 (Union[List[str], str]) – tweet_fields

    - user_fields (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  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.

  Changed in version 4.5: Added `user_auth` parameter

  Parameters

    - target_user_id (Union[int, str]) – The user ID of the user that you would like to block.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/users/blocks/api-reference/post-users-user_id-blocking

### 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.

  Changed in version 4.2: Renamed from `Client.unfollow()`

  Changed in version 4.5: Added `user_auth` parameter

  Parameters

    - target_user_id (Union[int, str]) – The user ID of the user that you would like to unfollow.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/users/follows/api-reference/delete-users-source_id-following

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, max_results, pagination_token, tweet_fields, user_fields, user_auth=False)

  Returns a list of users who are followers of the specified user ID.

  Parameters

    - id (Union[int, str]) – The user ID whose followers you would like to retrieve.

    - expansions (Union[List[str], str]) – expansions

    - max_results (int) – 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) – 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 (Union[List[str], str]) – tweet_fields

    - user_fields (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/users/follows/api-reference/get-users-id-followers

Client.get_users_following(id, *, expansions, max_results, pagination_token, tweet_fields, user_fields, user_auth=False)

  Returns a list of users the specified user ID is following.

  Parameters

    - id (Union[int, str]) – The user ID whose following you would like to retrieve.

    - expansions (Union[List[str], str]) – expansions

    - max_results (int) – 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) – 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 (Union[List[str], str]) – tweet_fields

    - user_fields (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  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.

  Changed in version 4.2: Renamed from `Client.follow()`

  Changed in version 4.5: Added `user_auth` parameter

  Parameters

    - target_user_id (Union[int, str]) – The user ID of the user that you would like to follow.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/users/follows/api-reference/post-users-source_user_id-following

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.

  Changed in version 4.5: Added `user_auth` parameter

  Parameters

    - target_user_id (Union[int, str]) – The user ID of the user that you would like to unmute.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/users/mutes/api-reference/delete-users-user_id-muting

Client.get_muted(*, expansions, max_results, pagination_token, tweet_fields, user_fields, user_auth=True)

  Returns a list of users who are muted by the authenticating user.

  New in version 4.1.

  Changed in version 4.5: Added `user_auth` parameter

  Parameters

    - expansions (Union[List[str], str]) – expansions

    - max_results (int) – 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) – 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 (Union[List[str], str]) – tweet_fields

    - user_fields (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  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.

  Changed in version 4.5: Added `user_auth` parameter

  Parameters

    - target_user_id (Union[int, str]) – The user ID of the user that you would like to mute.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/users/mutes/api-reference/post-users-user_id-muting

### User lookup

Client.get_user(*, id, username, expansions, tweet_fields, user_fields, user_auth=False)

  Returns a variety of information about a single user specified by the requested ID or username.

  Parameters

    - id (Union[int, str]) – The ID of the user to lookup.

    - username (str) – The Twitter username (handle) of the user.

    - expansions (Union[List[str], str]) – expansions

    - tweet_fields (Union[List[str], str]) – tweet_fields

    - user_fields (Union[List[str], str]) – 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

    Union[dict, requests.Response, Response]

  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, usernames, expansions, tweet_fields, user_fields, user_auth=False)

  Returns a variety of information about one or more users specified by the requested IDs or usernames.

  Parameters

    - ids (Union[List[int, str], str]) – 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 (Union[List[str], str]) – 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 (Union[List[str], str]) – expansions

    - tweet_fields (Union[List[str], str]) – tweet_fields

    - user_fields (Union[List[str], str]) – 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

    Union[dict, requests.Response, Response]

  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, tweet_fields, user_fields, user_auth=True)

  Returns information about an authorized user.

  New in version 4.5.

  Parameters

    - expansions (Union[List[str], str]) – expansions

    - tweet_fields (Union[List[str], str]) – tweet_fields

    - user_fields (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/users/lookup/api-reference/get-users-me

## Spaces

### Search Spaces

Client.search_spaces(query, *, expansions, max_results, space_fields, state, user_fields)

  Return live or scheduled Spaces matching your specified search terms

  New in version 4.1.

  Changed in version 4.2: `state` is 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 (Union[List[str], str]) – expansions

    - max_results (int) – The maximum number of results to return in this request. Specify a value between 1 and 100.

    - space_fields (Union[List[str], str]) – space_fields

    - state (str) – Determines the type of results to return. This endpoint returns all Spaces by default. Use `live` to only return live Spaces or `scheduled` to only return upcoming Spaces.

    - user_fields (Union[List[str], str]) – user_fields

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/spaces/search/api-reference/get-spaces-search

### Spaces lookup

Client.get_spaces(*, ids, user_ids, expansions, space_fields, user_fields)

  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 (Union[List[str], str]) – A comma separated list of Spaces (up to 100).

    - user_ids (Union[List[int, str], str]) – A comma separated list of user IDs (up to 100).

    - expansions (Union[List[str], str]) – expansions

    - space_fields (Union[List[str], str]) – space_fields

    - user_fields (Union[List[str], str]) – user_fields

  Raises

    TypeError – If IDs and user IDs are not passed or both are passed

  Returns

  Return type

    Union[dict, requests.Response, Response]

  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, space_fields, user_fields)

  Returns a variety of information about a single Space specified by the requested ID.

  New in version 4.1.

  Parameters

    - id (Union[List[str], str]) – Unique identifier of the Space to request.

    - expansions (Union[List[str], str]) – expansions

    - space_fields (Union[List[str], str]) – space_fields

    - user_fields (Union[List[str], str]) – user_fields

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/api-reference/get-spaces-id

Client.get_space_buyers(id, *, expansions, media_fields, place_fields, poll_fields, tweet_fields, user_fields)

  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 (Union[List[str], str]) – expansions

    - media_fields (Union[List[str], str]) – media_fields

    - place_fields (Union[List[str], str]) – place_fields

    - poll_fields (Union[List[str], str]) – poll_fields

    - tweet_fields (Union[List[str], str]) – tweet_fields

    - user_fields (Union[List[str], str]) – user_fields

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/api-reference/get-spaces-id-buyers

## Lists

### List Tweets lookup

Client.get_list_tweets(id, *, expansions, max_results, pagination_token, tweet_fields, user_fields, user_auth=False)

  Returns a list of Tweets from the specified List.

  New in version 4.4.

  Parameters

    - id (Union[List[str], str]) – The ID of the List whose Tweets you would like to retrieve.

    - expansions (Union[List[str], str]) – expansions

    - max_results (int) – 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) – 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 (Union[List[str], str]) – tweet_fields

    - user_fields (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/lists/list-tweets/api-reference/get-lists-id-tweets

### List follows

Client.unfollow_list(list_id, *, user_auth=True)

  Enables the authenticated user to unfollow a List.

  New in version 4.2.

  Changed in version 4.5: Added `user_auth` parameter

  Parameters

    - list_id (Union[int, str]) – The ID of the List that you would like the user to unfollow.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/lists/list-follows/api-reference/delete-users-id-followed-lists-list_id

Client.get_list_followers(id, *, expansions, max_results, pagination_token, tweet_fields, user_fields, user_auth=False)

  Returns a list of users who are followers of the specified List.

  New in version 4.4.

  Parameters

    - id (Union[List[str], str]) – The ID of the List whose followers you would like to retrieve.

    - expansions (Union[List[str], str]) – expansions

    - max_results (int) – 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) – 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 (Union[List[str], str]) – tweet_fields

    - user_fields (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/lists/list-follows/api-reference/get-lists-id-followers

Client.get_followed_lists(id, *, expansions, list_fields, max_results, pagination_token, user_fields, user_auth=False)

  Returns all Lists a specified user follows.

  New in version 4.4.

  Parameters

    - id (Union[List[str], str]) – The user ID whose followed Lists you would like to retrieve.

    - expansions (Union[List[str], str]) – expansions

    - list_fields (Union[List[str], str]) – list_fields

    - max_results (int) – 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) – 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 (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/lists/list-follows/api-reference/get-users-id-followed_lists

Client.follow_list(list_id, *, user_auth=True)

  Enables the authenticated user to follow a List.

  New in version 4.2.

  Changed in version 4.5: Added `user_auth` parameter

  Parameters

    - list_id (Union[int, str]) – The ID of the List that you would like the user to follow.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/lists/list-follows/api-reference/post-users-id-followed-lists

### List lookup

Client.get_list(id, *, expansions, list_fields, user_fields, user_auth=False)

  Returns the details of a specified List.

  New in version 4.4.

  Parameters

    - id (Union[List[str], str]) – The ID of the List to lookup.

    - expansions (Union[List[str], str]) – expansions

    - list_fields (Union[List[str], str]) – list_fields

    - user_fields (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/lists/list-lookup/api-reference/get-lists-id

Client.get_owned_lists(id, *, expansions, list_fields, max_results, pagination_token, user_fields, user_auth=False)

  Returns all Lists owned by the specified user.

  New in version 4.4.

  Parameters

    - id (Union[List[str], str]) – The user ID whose owned Lists you would like to retrieve.

    - expansions (Union[List[str], str]) – expansions

    - list_fields (Union[List[str], str]) – list_fields

    - max_results (int) – 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) – 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 (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/lists/list-lookup/api-reference/get-users-id-owned_lists

### 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_auth` parameter

  Parameters

    - id (Union[int, str]) – The ID of the List you are removing a member from.

    - user_id (Union[int, str]) – The ID of the user you wish to remove as a member of the List.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/lists/list-members/api-reference/delete-lists-id-members-user_id

Client.get_list_members(id, *, expansions, max_results, pagination_token, tweet_fields, user_fields, user_auth=False)

  Returns a list of users who are members of the specified List.

  New in version 4.4.

  Parameters

    - id (Union[List[str], str]) – The ID of the List whose members you would like to retrieve.

    - expansions (Union[List[str], str]) – expansions

    - max_results (int) – 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) – 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 (Union[List[str], str]) – tweet_fields

    - user_fields (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/lists/list-members/api-reference/get-lists-id-members

Client.get_list_memberships(id, *, expansions, list_fields, max_results, pagination_token, user_fields, user_auth=False)

  Returns all Lists a specified user is a member of.

  New in version 4.4.

  Parameters

    - id (Union[List[str], str]) – The user ID whose List memberships you would like to retrieve.

    - expansions (Union[List[str], str]) – expansions

    - list_fields (Union[List[str], str]) – list_fields

    - max_results (int) – 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) – 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 (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/lists/list-members/api-reference/get-users-id-list_memberships

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_auth` parameter

  Parameters

    - id (Union[int, str]) – The ID of the List you are adding a member to.

    - user_id (Union[int, str]) – The ID of the user you wish to add as a member of the List.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/lists/list-members/api-reference/post-lists-id-members

### 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_auth` parameter

  Parameters

    - id (Union[int, str]) – The ID of the List to be deleted.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  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_auth` parameter

  Parameters

    - id (Union[int, str]) – The ID of the List to be updated.

    - description (str) – Updates the description of the List.

    - name (str) – Updates the name of the List.

    - private (bool) – Determines whether the List should be private.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  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_auth` parameter

  Parameters

    - name (str) – The name of the List you wish to create.

    - description (str) – Description of the List.

    - private (bool) – Determine whether the List should be private.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  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.

  New in version 4.2.

  Changed in version 4.5: Added `user_auth` parameter

  Parameters

    - list_id (Union[int, str]) – The ID of the List that you would like the user to unpin.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/lists/pinned-lists/api-reference/delete-users-id-pinned-lists-list_id

Client.get_pinned_lists(*, expansions, list_fields, user_fields, user_auth=True)

  Returns the Lists pinned by a specified user.

  New in version 4.4.

  Changed in version 4.5: Added `user_auth` parameter

  Parameters

    - expansions (Union[List[str], str]) – expansions

    - list_fields (Union[List[str], str]) – list_fields

    - user_fields (Union[List[str], str]) – user_fields

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/lists/pinned-lists/api-reference/get-users-id-pinned_lists

Client.pin_list(list_id, *, user_auth=True)

  Enables the authenticated user to pin a List.

  New in version 4.2.

  Changed in version 4.5: Added `user_auth` parameter

  Parameters

    - list_id (Union[int, str]) – The ID of the List that you would like the user to pin.

    - user_auth (bool) – Whether or not to use OAuth 1.0a User Context to authenticate

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/lists/pinned-lists/api-reference/post-users-id-pinned-lists

## Compliance

### Batch compliance

Client.get_compliance_jobs(type, *, status)

  Returns a list of recent compliance jobs.

  New in version 4.1.

  Parameters

    - type (str) – Allows to filter by job type - either by tweets or user ID. Only one filter (tweets or users) can be specified per request.

    - status (str) – Allows to filter by job status. Only one filter can be specified per request. Default: `all`

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/compliance/batch-compliance/api-reference/get-compliance-jobs

Client.get_compliance_job(id)

  Get a single compliance job with the specified ID.

  New in version 4.1.

  Parameters

    id (Union[int, str]) – The unique identifier for the compliance job you want to retrieve.

  Returns

  Return type

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/compliance/batch-compliance/api-reference/get-compliance-jobs-id

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) – A name for this job, useful to identify multiple jobs using a label you define.

    - resumable (bool) – 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

    Union[dict, requests.Response, Response]

  References

  https://developer.twitter.com/en/docs/twitter-api/compliance/batch-compliance/api-reference/post-compliance-jobs

## Expansions and Fields Parameters

### `expansions`

Expansions enable you to request additional data objects that relate to the originally returned List, Space, Tweets, or users. Submit a list of desired expansions in a comma-separated list without spaces. The ID that represents the expanded data object will be included directly in the List, Space, Tweet, or user data object, but the expanded object metadata will be returned within the `includes` response object, and will also include the ID so that you can match this data object to the original Space, Tweet, or user object.

At this time, the only expansion available to endpoints that primarily return List objects is `expansions=owner_id`. You will find the expanded user data object living in the `includes` response object.

For methods that return Spaces, the following data objects can be expanded using this parameter:

- The Spaces creator’s user object

- The user objects of any Space co-host

- Any mentioned users’ object

- Any speaker’s user object

For methods that return Tweets, the following data objects can be expanded using this parameter:

- The Tweet author’s user object

- The user object of the Tweet’s author that the original Tweet is responding to

- Any mentioned users’ object

- Any referenced Tweets’ author’s user object

- Attached media’s object

- Attached poll’s object

- Attached place’s object

- Any referenced Tweets’ object

At this time, the only expansion available to endpoints that primarily return user objects is `expansions=pinned_tweet_id`. You will find the expanded Tweet data object living in the `includes` response object.

### `list_fields`

This fields parameter enables you to select which specific List fields will deliver with each returned List objects. Specify the desired fields in a comma-separated list without spaces between commas and fields. These specified List fields will display directly in the List data objects.

### `media_fields`

This fields parameter enables you to select which specific media fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet will only return media fields if the Tweet contains media and if you’ve also included the `expansions=attachments.media_keys` query parameter in your request. While the media ID will be located in the Tweet object, you will find this ID and all additional media fields in the `includes` data object.

### `place_fields`

This fields parameter enables you to select which specific place fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet will only return place fields if the Tweet contains a place and if you’ve also included the `expansions=geo.place_id` query parameter in your request. While the place ID will be located in the Tweet object, you will find this ID and all additional place fields in the `includes` data object.

### `poll_fields`

This fields parameter enables you to select which specific poll fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet will only return poll fields if the Tweet contains a poll and if you’ve also included the `expansions=attachments.poll_ids` query parameter in your request. While the poll ID will be located in the Tweet object, you will find this ID and all additional poll fields in the `includes` data object.

### `space_fields`

This fields parameter enables you to select which specific Space fields will deliver in each returned Space. Specify the desired fields in a comma-separated list.

### `tweet_fields`

For methods that return Tweets, this fields parameter enables you to select which specific Tweet fields will deliver in each returned Tweet object. Specify the desired fields in a comma-separated list without spaces between commas and fields. You can also pass the `expansions=referenced_tweets.id` expansion to return the specified fields for both the original Tweet and any included referenced Tweets. The requested Tweet fields will display in both the original Tweet data object, as well as in the referenced Tweet expanded data object that will be located in the `includes` data object.

For methods that return users, this fields parameter enables you to select which specific Tweet fields will deliver in each returned pinned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet fields will only return if the user has a pinned Tweet and if you’ve also included the `expansions=pinned_tweet_id` query parameter in your request. While the referenced Tweet ID will be located in the original Tweet object, you will find this ID and all additional Tweet fields in the `includes` data object.

### `user_fields`

For methods that return Spaces or Tweets, this fields parameter enables you to select which specific user fields will deliver in each returned Space or Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. While the user ID will be located in the original Tweet object, you will find this ID and all additional user fields in the `includes` data object.

You must also pass one of the user expansions to return the desired user fields:

- `expansions=author_id`

- `expansions=entities.mentions.username`

- `expansions=in_reply_to_user_id`

- `expansions=referenced_tweets.id.author_id`

For methods that return users, this fields parameter enables you to select which specific user fields will deliver with each returned users objects. Specify the desired fields in a comma-separated list without spaces between commas and fields. These specified user fields will display directly in the user data objects.

## `Response`

class tweepy.Response(data, includes, errors, meta)

  The `Response` returned by `Client` methods is a `collections.namedtuple`, with `data`, `includes`, `errors`, and `meta` fields, corresponding with the fields in responses from Twitter’s API.

  New in version 4.0.