AsyncClient

class tweepy.asynchronous.AsyncClient(bearer_token=None, consumer_key=None, consumer_secret=None, access_token=None, access_token_secret=None, *, return_type=Response, wait_on_rate_limit=False)

Asynchronous Twitter API v2 Client

New in version 4.10.

Changed in version 4.15: Removed block and unblock methods, as the endpoints they use have been removed

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 | aiohttp.ClientResponse | Response]) – Type to return from requests to the API

  • wait_on_rate_limit (bool) – Whether to wait when rate limit is reached

session

Aiohttp client session used to make requests to the API

Type

aiohttp.ClientSession

user_agent

User agent used when making requests to the API

Type

str

Twitter API v2 Endpoint

AsyncClient Method

Tweets

Bookmarks

DELETE /2/users/:id/bookmarks/:tweet_id

AsyncClient.remove_bookmark()

GET /2/users/:id/bookmarks

AsyncClient.get_bookmarks()

POST /2/users/:id/bookmarks

AsyncClient.bookmark()

Hide replies

PUT /2/tweets/:id/hidden

AsyncClient.hide_reply()

PUT /2/tweets/:id/hidden

AsyncClient.unhide_reply()

Likes

DELETE /2/users/:id/likes/:tweet_id

AsyncClient.unlike()

GET /2/tweets/:id/liking_users

AsyncClient.get_liking_users()

GET /2/users/:id/liked_tweets

AsyncClient.get_liked_tweets()

POST /2/users/:id/likes

AsyncClient.like()

Manage Tweets

DELETE /2/tweets/:id

AsyncClient.delete_tweet()

POST /2/tweets

AsyncClient.create_tweet()

Quote Tweets

GET /2/tweets/:id/quote_tweets

AsyncClient.get_quote_tweets()

Retweets

DELETE /2/users/:id/retweets/:source_tweet_id

AsyncClient.unretweet()

GET /2/tweets/:id/retweeted_by

AsyncClient.get_retweeters()

POST /2/users/:id/retweets

AsyncClient.retweet()

Search Tweets

GET /2/tweets/search/all

AsyncClient.search_all_tweets()

GET /2/tweets/search/recent

AsyncClient.search_recent_tweets()

Timelines

GET /2/users/:id/mentions

AsyncClient.get_users_mentions()

GET /2/users/:id/timelines/reverse_chronological

AsyncClient.get_home_timeline()

GET /2/users/:id/tweets

AsyncClient.get_users_tweets()

Tweet counts

GET /2/tweets/counts/all

AsyncClient.get_all_tweets_count()

GET /2/tweets/counts/recent

AsyncClient.get_recent_tweets_count()

Tweet lookup

GET /2/tweets/:id

AsyncClient.get_tweet()

GET /2/tweets

AsyncClient.get_tweets()

Users

Blocks

GET /2/users/:id/blocking

AsyncClient.get_blocked()

Follows

DELETE /2/users/:source_user_id/following/:target_user_id

AsyncClient.unfollow_user()

GET /2/users/:id/followers

AsyncClient.get_users_followers()

GET /2/users/:id/following

AsyncClient.get_users_following()

POST /2/users/:id/following

AsyncClient.follow_user()

Mutes

DELETE /2/users/:source_user_id/muting/:target_user_id

AsyncClient.unmute()

GET /2/users/:id/muting

AsyncClient.get_muted()

POST /2/users/:id/muting

AsyncClient.mute()

User lookup

GET /2/users/:id

AsyncClient.get_user()

GET /2/users/by/username/:username

AsyncClient.get_user()

GET /2/users

AsyncClient.get_users()

GET /2/users/by

AsyncClient.get_users()

GET /2/users/me

AsyncClient.get_me()

Spaces

Search Spaces

GET /2/spaces/search

AsyncClient.search_spaces()

Spaces lookup

GET /2/spaces

AsyncClient.get_spaces()

GET /2/spaces/:id

AsyncClient.get_space()

GET /2/spaces/:id/buyers

AsyncClient.get_space_buyers()

GET /2/spaces/:id/tweets

AsyncClient.get_space_tweets()

GET /2/spaces/by/creator_ids

AsyncClient.get_spaces()

Direct Messages

Direct Messages lookup

GET /2/dm_conversations/:dm_conversation_id/dm_events

AsyncClient.get_direct_message_events()

GET /2/dm_conversations/with/:participant_id/dm_events

AsyncClient.get_direct_message_events()

GET /2/dm_events

AsyncClient.get_direct_message_events()

Manage Direct Messages

POST /2/dm_conversations

AsyncClient.create_direct_message_conversation()

POST /2/dm_conversations/:dm_conversation_id/messages

AsyncClient.create_direct_message()

POST /2/dm_conversations/with/:participant_id/messages

AsyncClient.create_direct_message()

Lists

List Tweets lookup

GET /2/lists/:id/tweets

AsyncClient.get_list_tweets()

List follows

DELETE /2/users/:id/followed_lists/:list_id

AsyncClient.unfollow_list()

GET /2/lists/:id/followers

AsyncClient.get_list_followers()

GET /2/users/:id/followed_lists

AsyncClient.get_followed_lists()

POST /2/users/:id/followed_lists

AsyncClient.follow_list()

List lookup

GET /2/lists/:id

AsyncClient.get_list()

GET /2/users/:id/owned_lists

AsyncClient.get_owned_lists()

List members

DELETE /2/lists/:id/members/:user_id

AsyncClient.remove_list_member()

GET /2/lists/:id/members

AsyncClient.get_list_members()

GET /2/users/:id/list_memberships

AsyncClient.get_list_memberships()

POST /2/lists/:id/members

AsyncClient.add_list_member()

Manage Lists

DELETE /2/lists/:id

AsyncClient.delete_list()

PUT /2/lists/:id

AsyncClient.update_list()

POST /2/lists

AsyncClient.create_list()

Pinned Lists

DELETE /2/users/:id/pinned_lists/:list_id

AsyncClient.unpin_list()

GET /2/users/:id/pinned_lists

AsyncClient.get_pinned_lists()

POST /2/users/:id/pinned_lists

AsyncClient.pin_list()

Compliance

Batch Compliance

GET /2/compliance/jobs

AsyncClient.get_compliance_jobs()

GET /2/compliance/jobs/:id

AsyncClient.get_compliance_job()

POST /2/compliance/jobs

AsyncClient.create_compliance_job()

Tweets

Bookmarks

async AsyncClient.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 AsyncClient instance for each access token used.

Parameters

tweet_id (int | str) – The ID of the Tweet that you would like the id to remove a Bookmark of.

Raises

TypeError – If the access token isn’t set

Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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 AsyncClient instance for each access token used.

Parameters
Raises

TypeError – If the access token isn’t set

Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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 AsyncClient instance for each access token used.

Parameters

tweet_id (int | str) – The ID of the Tweet that you would like the user id to Bookmark.

Raises

TypeError – If the access token isn’t set

Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

Hide replies

async AsyncClient.hide_reply(id, *, user_auth=True)

Hides a reply to a Tweet.

Parameters
  • id (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

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.unhide_reply(id, *, user_auth=True)

Unhides a reply to a Tweet.

Parameters
  • id (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

dict | aiohttp.ClientResponse | Response

References

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

Likes

async AsyncClient.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 per AsyncClient instance for each access token used.

Parameters
  • tweet_id (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

Raises

TypeError – If the access token isn’t set

Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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.

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_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

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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_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

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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 per AsyncClient instance for each access token used.

Parameters
  • tweet_id (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

Raises

TypeError – If the access token isn’t set

Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

Manage Tweets

async AsyncClient.delete_tweet(id, *, user_auth=True)

Allows an authenticated user ID to delete a Tweet.

Parameters
  • id (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

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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.

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_id needs to be in the request if exclude_reply_user_ids is 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_ids is not present.

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

Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

Quote Tweets

async AsyncClient.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.

Changed in version 4.11: Added exclude parameter

Parameters
  • id (int | str) – Unique identifier of the Tweet to request.

  • 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_results per 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

dict | aiohttp.ClientResponse | Response

References

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

Retweets

async AsyncClient.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 per AsyncClient instance for each access token used.

Parameters
  • source_tweet_id (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

Raises

TypeError – If the access token isn’t set

Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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.

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_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

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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 per AsyncClient instance for each access token used.

Parameters
  • tweet_id (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

Raises

TypeError – If the access token isn’t set

Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

Search Tweets

async AsyncClient.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_time parameter is not provided.

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 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 (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_time parameter, only since_id will 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

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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.

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_time parameter, only since_id will 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_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 (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

dict | aiohttp.ClientResponse | Response

References

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

Timelines

async AsyncClient.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_results per 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_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 (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, the since_id will 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, the until_id will 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

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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 per AsyncClient instance 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_results per 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_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 (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, the since_id will 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, the until_id will 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

dict | requests.Response | Response

References

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

async AsyncClient.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=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 (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_results per 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_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 (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 the since_id, the since_id will 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 the until_id, the until_id will 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

dict | aiohttp.ClientResponse | Response

References

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

Tweet counts

async AsyncClient.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 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 | None) – 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 | 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_time parameter, only since_id will 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

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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, or day granularity. The default granularity, if not specified is hour.

  • 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_time parameter, only since_id will 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_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 (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

dict | aiohttp.ClientResponse | Response

References

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

Tweet lookup

async AsyncClient.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
Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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
Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

Users

Blocks

async AsyncClient.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 per AsyncClient instance for each access token used.

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

dict | aiohttp.ClientResponse | Response

References

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

Follows

async AsyncClient.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 per AsyncClient instance for each access token used.

Parameters
  • target_user_id (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

Raises

TypeError – If the access token isn’t set

Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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.

Note

The Twitter API endpoint that this method uses has been removed from the Basic and Pro tiers 1.

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_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

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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.

Note

The Twitter API endpoint that this method uses has been removed from the Basic and Pro tiers 1.

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_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

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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 per AsyncClient instance for each access token used.

Parameters
  • target_user_id (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

Raises

TypeError – If the access token isn’t set

Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

Mutes

async AsyncClient.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 per AsyncClient instance for each access token used.

Parameters
  • target_user_id (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

Raises

TypeError – If the access token isn’t set

Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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 per AsyncClient instance for each access token used.

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

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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 per AsyncClient instance for each access token used.

Parameters
  • target_user_id (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

Raises

TypeError – If the access token isn’t set

Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

User lookup

async AsyncClient.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
Raises

TypeError – If ID and username are not passed or both are passed

Returns

Return type

dict | aiohttp.ClientResponse | 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

async AsyncClient.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

dict | aiohttp.ClientResponse | 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

async AsyncClient.get_me(*, expansions=None, tweet_fields=None, user_fields=None, user_auth=True)

Returns information about an authorized user.

Parameters
Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

Spaces

Search Spaces

async AsyncClient.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

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 live to only return live Spaces or scheduled to only return upcoming Spaces.

  • user_fields (list[str] | str | None) – user_fields

Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

Spaces lookup

async AsyncClient.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.

Parameters
Raises

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

Returns

Return type

dict | aiohttp.ClientResponse | 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

async AsyncClient.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.

Parameters
Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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.

Parameters
Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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.

Parameters
Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

Direct Messages

Direct Messages lookup

async AsyncClient.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_id is passed, returns a list of Direct Messages within the conversation specified. Messages are returned in reverse chronological order.

If participant_id is 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 id of the Direct Message conversation for which events are being retrieved.

  • participant_id (int | str | None) – The participant_id of 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. id and event_type are returned by default. The text value isn’t included for ParticipantsJoin and ParticipantsLeave events.

  • 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_token or previous_token value.

  • 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_id and participant_id are passed

Returns

Return type

dict | aiohttp.ClientResponse | Response

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

async AsyncClient.create_direct_message(*, dm_conversation_id=None, participant_id=None, media_id=None, text=None, user_auth=True)

If dm_conversation_id is passed, creates a Direct Message on behalf of the authenticated user, and adds it to the specified conversation.

If participant_id is 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_id of 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 text is 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_id is 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_id and participant_id are not passed or both are passed

Returns

Return type

dict | aiohttp.ClientResponse | Response

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

async AsyncClient.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 text is 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_id is 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

dict | aiohttp.ClientResponse | Response

References

https://developer.twitter.com/en/docs/twitter-api/direct-messages/manage/api-reference/post-dm_conversations

Lists

List Tweets lookup

async AsyncClient.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.

Changed in version 4.10.1: Added media_fields, place_fields, and poll_fields parameters

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

dict | aiohttp.ClientResponse | Response

References

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

List follows

async AsyncClient.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 per AsyncClient instance for each access token used.

Parameters
  • list_id (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

Raises

TypeError – If the access token isn’t set

Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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.

Note

The Twitter API endpoint that this method uses has been removed from the Basic and Pro tiers 1.

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

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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.

Note

The Twitter API endpoint that this method uses has been removed from the Basic and Pro tiers 1.

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

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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 per AsyncClient instance for each access token used.

Parameters
  • list_id (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

Raises

TypeError – If the access token isn’t set

Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

List lookup

async AsyncClient.get_list(id, *, expansions=None, list_fields=None, user_fields=None, user_auth=False)

Returns the details of a specified List.

Parameters
Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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.

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

dict | aiohttp.ClientResponse | Response

References

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

List members

async AsyncClient.remove_list_member(id, user_id, *, user_auth=True)

Enables the authenticated user to remove a member from a List they own.

Parameters
  • id (int | str) – The ID of the List you are removing a member from.

  • user_id (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

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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.

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

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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.

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

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.add_list_member(id, user_id, *, user_auth=True)

Enables the authenticated user to add a member to a List they own.

Parameters
  • id (int | str) – The ID of the List you are adding a member to.

  • user_id (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

dict | aiohttp.ClientResponse | Response

References

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

Manage Lists

async AsyncClient.delete_list(id, *, user_auth=True)

Enables the authenticated user to delete a List that they own.

Parameters
  • id (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

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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.

Parameters
  • id (int | str) – The ID of the List to be updated.

  • description (str | None) – Updates the description of the List.

  • name (str | None) – Updates the name of the List.

  • private (bool | None) – 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

dict | aiohttp.ClientResponse | Response

References

https://developer.twitter.com/en/docs/twitter-api/lists/manage-lists/api-reference/put-lists-id

async AsyncClient.create_list(name, *, description=None, private=None, user_auth=True)

Enables the authenticated user to create a List.

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

  • description (str | None) – Description of the List.

  • private (bool | None) – 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

dict | aiohttp.ClientResponse | Response

References

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

Pinned Lists

async AsyncClient.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 per AsyncClient instance for each access token used.

Parameters
  • list_id (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

Raises

TypeError – If the access token isn’t set

Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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 per AsyncClient instance for each access token used.

Parameters
Raises

TypeError – If the access token isn’t set

Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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 per AsyncClient instance for each access token used.

Parameters
  • list_id (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

Raises

TypeError – If the access token isn’t set

Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

Compliance

Batch compliance

async AsyncClient.get_compliance_jobs(type, *, status=None)

Returns a list of recent compliance jobs.

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 | None) – Allows to filter by job status. Only one filter can be specified per request. Default: all

Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.get_compliance_job(id)

Get a single compliance job with the specified ID.

Parameters

id (int | str) – The unique identifier for the compliance job you want to retrieve.

Returns

Return type

dict | aiohttp.ClientResponse | Response

References

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

async AsyncClient.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.

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

dict | aiohttp.ClientResponse | Response

References

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

Footnotes

1(1,2,3,4)

https://developer.twitter.com/en/updates/changelog