Models

`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

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

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.

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

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

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.

data

The JSON data representing the referenced Tweet.

Type: dict

id

The unique identifier of the referenced Tweet.

Type: int

type

Type: str

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