Fields

Interested in exploring Labs?
The endpoints we release in Labs are previews of tools that may be released more broadly in the future, but will likely undergo changes before then. We encourage you to take that into consideration as you explore. Before getting started, please read more about Twitter Developer Labs.

Overview

By default, only id and text are returned as fields on a Tweet, and only id, name, and username are returned as fields on a User. The fields parameter provides a way to specify which additional fields of data return with an API response using the Labs v2 endpoints. Using expansions with fields provides a way to request additional referenced objects and their fields in a single response. For example, the User object can be expanded on within the Tweet object and vice versa.

This parameter effectively replaces the formats parameter available with v1 endpoints. To learn more about the differences between the two parameters, please review our migration guide.

Data Objects

The Twitter Developer Labs program includes the following five data objects that comprise different sets of fields:

• Tweet
• Media
• Place
• Poll
• User
   

The fields attributed to the parent object are always available to query without expansion. For example, no expansion is required when requesting the full list of tweet.fields on the /tweets endpoint. If you want to see data related to the media, place, poll, or user associated with that Tweet, you need to add the appropriate expansion parameter.
 

A fixed list of values can be queried using fields. Any other value not contained in the lists below will return an error message. Multiple fields can be queried in the same request using comma separation. An error message will be returned if the rate limit has been reached for the field with the lowest limit.

Tweet

Tweet fields that can be requested with the tweet.fields query parameter:

• id (returned by default)
• text (returned by default)
• attachments
• author_id
• created_at
• entities
• geo
• in_reply_to_user_id
• lang
• non_public_metrics
• possibly_sensitive
• referenced_tweets
• source
• public_metrics
• withheld

Media

For Tweets with media, the default response with expansions (e.g. GET /labs/2/tweets/:id?expansions=attachments.media_keys) includes media_key and type. Additional fields can be requested with the media.fields parameter with these values:

• media_key (returned by default)
• type (returned by default)
• duration_ms
• height
• non_public_metrics
• preview_image_url
• public_metrics
• url
• width

Poll

For Tweets with polls, the default response with expansions (e.g. GET /labs/2/tweets/:id?expansions=attachments.poll_ids) includes id and options. Additional fields can be requested with the poll.fields query parameter with these values:

• id (returned by default)
• options (returned by default)
• duration_minutes
• end_datetime
• voting_status

Place

For Tweets with places, the default response with expansions (e.g. GET /labs/2/tweets/:id?expansions=geo.place_id) includes id and full_name. Additional fields can requested with the geo.place_id query parameter with these values:

• id (returned by default)
• full_name (returned by default)
• contained_within
• country
• country_code
• geo
• name
• place_type

User

User fields can be requested with the user.fields query parameter:

• id (returned by default)
• name (returned by default)
• username (returned by default)
• created_at
• description
• entities
• location
• pinned_tweet_id (Note: to request fields for this tweet, use expansions=pinned_tweet_id for default fields id and text, and &tweet.fields=created_at,public_metrics,… for additional fields)
• profile_image_url
• protected
• url
• verified
• withheld

Additional resources

• Learn more about the new Developer Labs on the "About Labs" page.
• Learn more about What’s new.
• Give feedback on Twitter Developer Labs.
• Tell us about your experience using the Twitter Developer Labs endpoints by filling out this survey.