Models

DirectMessageEvent

class tweepy.DirectMessageEvent

Direct Message (DM) conversations are made up of events. The Twitter API v2 currently supports three event types: MessageCreate, ParticipantsJoin, and ParticipantsLeave.

DM event objects are returned by the Direct Message lookup endpoints, and a MessageCreate event is created when Direct Messages are successfully created with the Manage Direct Messages endpoints.

When requesting DM events, there are three default event object attributes, or fields, included: id, event_type, and text. To receive additional event fields, use the fields parameter dm_event.fields to select others. Other available event fields include the following: dm_conversation_id, created_at, sender_id`, ``attachments, participant_ids, and referenced_tweets.

Several of these fields provide the IDs of other Twitter objects related to the Direct Message event:

  • sender_id - The ID of the account that sent the message, or who invited a participant to a group conversation

  • partricipants_ids - An array of account IDs. For ParticipantsJoin and ParticipantsLeave events this array will contain a single ID of the account that created the event

  • attachments - Provides media IDs for content that has been uploaded to Twitter by the sender

  • referenced_tweets - If a Tweet URL is found in the text field, the ID of that Tweet is included in the response

The sender_id, participant_ids, referenced_tweets.id, and attachments.media_keys expansions are available to expand on these Twitter object IDs.

New in version 4.12.

data

The JSON data representing the Direct Message event.

Type

dict

id

The unique identifier of the event.

Type

int

event_type

Describes the type of event. Three types are currently supported:

  • MessageCreate

  • ParticipantsJoin

  • ParticipantsLeave

Type

str

text

The actual UTF-8 text of the Direct Message.

Type

str | None

sender_id

ID of the User creating the event. To expand this object in the response, include sender_id as an expansion and use the user.fields query parameter to specify User object attributes of interest.

Type

int | None

participant_ids

IDs of the participants joining and leaving a group conversation. Also used when creating new group conversations. To expand this object in the response, include participant_ids as an expansion and use the user.fields query parameter to specify User object attributes of interest.

Type

list[int] | None

dm_conversation_id

The unique identifier of the conversation the event is apart of.

Type

str | None

created_at

Creation time (UTC) of the Tweet.

Type

datetime.datetime | None

referenced_tweets

ID for any Tweet mentioned in the Direct Message text. To expand this object in the response, include referenced_tweets.id as an expansion and use the tweet.fields query parameter to specify Tweet object attributes of interest.

Type

list[ReferencedTweet] | None

attachments

For Direct Messages with attached Media, provides the media key of the uploaded content (photo, video, or GIF. To expand this object in the response, include attachments.media_keys as an expansion and use the media.fields query parameter to specify media object attributes of interest. Currently, one attachment is supported.

Type

dict | None

References

https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/dm-events

List

class tweepy.List

The list object contains Twitter Lists metadata describing the referenced List. The List object is the primary object returned in the List lookup endpoint. When requesting additional List fields on this endpoint, simply use the fields parameter list.fields.

At the moment, the List object cannot be found as a child object from any other data object. However, user objects can be found and expanded in the user resource. These objects are available for expansion by adding owner_id to the expansions query parameter. Use the expansion with the field parameter: list.fields when requesting additional fields to complete the primary List object and user.fields to complete the expansion object.

New in version 4.4.

data

The JSON data representing the List.

Type

dict

id

The unique identifier of this List.

Type

str

name

The name of the List, as defined when creating the List.

Type

str

created_at

The UTC datetime that the List was created on Twitter.

Type

datetime.datetime | None

description

A brief description to let users know about the List.

Type

str | None

follower_count

Shows how many users follow this List,

Type

int | None

member_count

Shows how many members are part of this List.

Type

int | None

private

Indicates if the List is private.

Type

bool | None

owner_id

Unique identifier of this List’s owner.

Type

str | None

References

https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/lists

Media

class tweepy.Media

Media refers to any image, GIF, or video attached to a Tweet. The media object is not a primary object on any endpoint, but can be found and expanded in the Tweet object.

The object is available for expansion with ?expansions=attachments.media_keys to get the condensed object with only default fields. Use the expansion with the field parameter: media.fields when requesting additional fields to complete the object..

New in version 4.0.

Changed in version 4.5: Added url field

Changed in version 4.12: Added variants field

data

The JSON data representing the media.

Type

dict

media_key

Unique identifier of the expanded media content.

Type

str

type

Type of content (animated_gif, photo, video).

Type

str

url

A direct URL to the media file on Twitter.

Type

str | None

duration_ms

Available when type is video. Duration in milliseconds of the video.

Type

int | None

height

Height of this content in pixels.

Type

int | None

non_public_metrics

Non-public engagement metrics for the media content at the time of the request.

Requires user context authentication.

Type

dict | None

organic_metrics

Engagement metrics for the media content, tracked in an organic context, at the time of the request.

Requires user context authentication.

Type

dict | None

preview_image_url

URL to the static placeholder preview of this content.

Type

str | None

promoted_metrics

Engagement metrics for the media content, tracked in a promoted context, at the time of the request.

Requires user context authentication.

Type

dict | None

public_metrics

Public engagement metrics for the media content at the time of the request.

Type

dict | None

width

Width of this content in pixels.

Type

int | None

alt_text

A description of an image to enable and support accessibility. Can be up to 1000 characters long. Alt text can only be added to images at the moment.

Type

str | None

variants

Each media object may have multiple display or playback variants, with different resolutions or formats

Type

list[dict] | None

References

https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/media

Place

class tweepy.Place

The place tagged in a Tweet is not a primary object on any endpoint, but can be found and expanded in the Tweet resource.

The object is available for expansion with ?expansions=geo.place_id to get the condensed object with only default fields. Use the expansion with the field parameter: place.fields when requesting additional fields to complete the object.

New in version 4.0.

data

The JSON data representing the place.

Type

dict

full_name

A longer-form detailed place name.

Type

str

id

The unique identifier of the expanded place, if this is a point of interest tagged in the Tweet.

Type

str

contained_within

Returns the identifiers of known places that contain the referenced place.

Type

list

country

The full-length name of the country this place belongs to.

Type

str | None

country_code

The ISO Alpha-2 country code this place belongs to.

Type

str | None

geo

Contains place details in GeoJSON format.

Type

dict | None

name

The short name of this place.

Type

str | None

place_type

Specified the particular type of information represented by this place information, such as a city name, or a point of interest.

Type

str | None

References

https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/place

Poll

class tweepy.Poll

A poll included in a Tweet is not a primary object on any endpoint, but can be found and expanded in the Tweet object.

The object is available for expansion with ?expansions=attachments.poll_ids to get the condensed object with only default fields. Use the expansion with the field parameter: poll.fields when requesting additional fields to complete the object.

New in version 4.0.

data

The JSON data representing the poll.

Type

dict

id

Unique identifier of the expanded poll.

Type

str

options

Contains objects describing each choice in the referenced poll.

Type

list

duration_minutes

Specifies the total duration of this poll.

Type

int | None

end_datetime

Specifies the end date and time for this poll.

Type

datetime.datetime | None

voting_status

Indicates if this poll is still active and can receive votes, or if the voting is now closed.

Type

str | None

References

https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/poll

Space

class tweepy.Space

Spaces allow expression and interaction via live audio conversations. The Space data dictionary contains relevant metadata about a Space; all the details are updated in real time.

User objects can found and expanded in the user resource. These objects are available for expansion by adding at least one of host_ids, creator_id, speaker_ids, mentioned_user_ids to the expansions query parameter.

Unlike Tweets, Spaces are ephemeral and become unavailable after they end or when they are canceled by their creator. When your app handles Spaces data, you are responsible for returning the most up-to-date information, and must remove data that is no longer available from the platform. The Spaces lookup endpoints can help you ensure you respect the users’ expectations and intent.

New in version 4.1.

Changed in version 4.4: Added ended_at and topic_ids fields

Changed in version 4.6: Added subscriber_count field

data

The JSON data representing the Space.

Type

dict

id

The unique identifier of the requested Space.

Type

str

state

Indicates if the Space has started or will start in the future, or if it has ended.

Type

str

created_at

Creation time of this Space.

Type

datetime.datetime | None

ended_at

Time when the Space was ended. Only available for ended Spaces.

Type

datetime.datetime | None

host_ids

The unique identifier of the users who are hosting this Space.

Type

list

lang

Language of the Space, if detected by Twitter. Returned as a BCP47 language tag.

Type

str | None

is_ticketed

Indicates is this is a ticketed Space.

Type

bool | None

invited_user_ids

The list of user IDs that were invited to join as speakers. Usually, users in this list are invited to speak via the Invite user option.

Type

list

participant_count

The current number of users in the Space, including Hosts and Speakers.

Type

int | None

subscriber_count

The number of people who set a reminder to a Space.

Type

int | None

scheduled_start

Indicates the start time of a scheduled Space, as set by the creator of the Space. This field is returned only if the Space has been scheduled; in other words, if the field is returned, it means the Space is a scheduled Space.

Type

datetime.datetime | None

speaker_ids

The list of users who were speaking at any point during the Space. This list contains all the users in invited_user_ids in addition to any user who requested to speak and was allowed via the Add speaker option.

Type

list

started_at

Indicates the actual start time of a Space.

Type

datetime.datetime | None

title

The title of the Space as specified by the creator.

Type

str | None

topic_ids

A list of IDs of the topics selected by the creator of the Space.

Type

list

updated_at

Specifies the date and time of the last update to any of the Space’s metadata, such as its title or scheduled time.

Type

datetime.datetime | None

References

https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/space

Tweet

class tweepy.Tweet

Tweets are the basic building block of all things Twitter. The Tweet object has a long list of ‘root-level’ fields, such as id, text, and created_at. Tweet objects are also the ‘parent’ object to several child objects including user, media, poll, and place. Use the field parameter tweet.fields when requesting these root-level fields on the Tweet object.

The Tweet object that can be found and expanded in the user resource. Additional Tweets related to the requested Tweet can also be found and expanded in the Tweet resource. The object is available for expansion with ?expansions=pinned_tweet_id in the user resource or ?expansions=referenced_tweets.id in the Tweet resource to get the object with only default fields. Use the expansion with the field parameter: tweet.fields when requesting additional fields to complete the object.

New in version 4.0.

Changed in version 4.11: Added edit_history_tweet_ids and edit_controls fields

data

The JSON data representing the Tweet.

Type

dict

id

The unique identifier of the requested Tweet.

Type

int

text

The actual UTF-8 text of the Tweet. See twitter-text for details on what characters are currently considered valid.

Type

str

edit_history_tweet_ids

Unique identifiers indicating all versions of a Tweet. For Tweets with no edits, there will be one ID. For Tweets with an edit history, there will be multiple IDs, arranged in ascending order reflecting the order of edits. The most recent version is the last position of the array.

Type

list[int]

attachments

Specifies the type of attachments (if any) present in this Tweet.

Type

dict | None

author_id

The unique identifier of the User who posted this Tweet.

Type

int | None

context_annotations

Contains context annotations for the Tweet.

Type

list

conversation_id

The Tweet ID of the original Tweet of the conversation (which includes direct replies, replies of replies).

Type

int | None

created_at

Creation time of the Tweet.

Type

datetime.datetime | None

edit_controls

When present, this indicates how much longer the Tweet can be edited and the number of remaining edits. Tweets are only editable for the first 30 minutes after creation and can be edited up to five times.

Type

dict | None

entities

Entities which have been parsed out of the text of the Tweet. Additionally see entities in Twitter Objects.

Type

dict | None

geo

Contains details about the location tagged by the user in this Tweet, if they specified one.

Type

dict | None

in_reply_to_user_id

If the represented Tweet is a reply, this field will contain the original Tweet’s author ID. This will not necessarily always be the user directly mentioned in the Tweet.

Type

int | None

lang

Language of the Tweet, if detected by Twitter. Returned as a BCP47 language tag.

Type

str | None

non_public_metrics

Non-public engagement metrics for the Tweet at the time of the request.

Requires user context authentication.

Type

dict | None

organic_metrics

Engagement metrics, tracked in an organic context, for the Tweet at the time of the request.

Requires user context authentication.

Type

dict | None

possibly_sensitive

This field only surfaces when a Tweet contains a link. The meaning of the field doesn’t pertain to the Tweet content itself, but instead it is an indicator that the URL contained in the Tweet may contain content or media identified as sensitive content.

Type

bool | None

promoted_metrics

Engagement metrics, tracked in a promoted context, for the Tweet at the time of the request.

Requires user context authentication.

Type

dict | None

public_metrics

Public engagement metrics for the Tweet at the time of the request.

Type

dict | None

referenced_tweets

A list of Tweets this Tweet refers to. For example, if the parent Tweet is a Retweet, a Retweet with comment (also known as Quoted Tweet) or a Reply, it will include the related Tweet referenced to by its parent.

Type

list[ReferencedTweet] | None

reply_settings

Shows you who can reply to a given Tweet. Fields returned are “everyone”, “mentioned_users”, and “followers”.

Type

str | None

source

The name of the app the user Tweeted from.

Type

str | None

withheld

When present, contains withholding details for withheld content.

Type

dict | None

References

https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/tweet

class tweepy.ReferencedTweet

New in version 4.0.

Changed in version 4.12: Changed type to be optional

data

The JSON data representing the referenced Tweet.

Type

dict

id

The unique identifier of the referenced Tweet.

Type

int

type
Type

str | None

References

https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/tweet

User

class tweepy.User

The user object contains Twitter user account metadata describing the referenced user. The user object is the primary object returned in the users lookup endpoint. When requesting additional user fields on this endpoint, simply use the fields parameter user.fields.

The user object can also be found as a child object and expanded in the Tweet object. The object is available for expansion with ?expansions=author_id or ?expansions=in_reply_to_user_id to get the condensed object with only default fields. Use the expansion with the field parameter: user.fields when requesting additional fields to complete the object.

New in version 4.0.

data

The JSON data representing the user.

Type

dict

id

The unique identifier of this user.

Type

int

name

The name of the user, as they’ve defined it on their profile. Not necessarily a person’s name. Typically capped at 50 characters, but subject to change.

Type

str

username

The Twitter screen name, handle, or alias that this user identifies themselves with. Usernames are unique but subject to change. Typically a maximum of 15 characters long, but some historical accounts may exist with longer names.

Type

str

created_at

The UTC datetime that the user account was created on Twitter.

Type

datetime.datetime | None

description

The text of this user’s profile description (also known as bio), if the user provided one.

Type

str | None

entities

Contains details about text that has a special meaning in the user’s description.

Type

dict | None

location

The location specified in the user’s profile, if the user provided one. As this is a freeform value, it may not indicate a valid location, but it may be fuzzily evaluated when performing searches with location queries.

Type

str | None

pinned_tweet_id

Unique identifier of this user’s pinned Tweet.

Type

int | None

profile_image_url

The URL to the profile image for this user, as shown on the user’s profile.

Type

str | None

protected

Indicates if this user has chosen to protect their Tweets (in other words, if this user’s Tweets are private).

Type

bool | None

public_metrics

Contains details about activity for this user.

Type

dict | None

url

The URL specified in the user’s profile, if present.

Type

str | None

verified

Indicates if this user is a verified Twitter User.

Type

bool | None

withheld

Contains withholding details for withheld content, if applicable.

Type

dict | None

References

https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/user