Fields: Labs v2 only

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.

The fields parameter is currently available with the following Labs endpoints:

  • Tweets v2
  • Users v2
  • Recent Search v2
     

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.
 

  tweet.fields media.fields place.fields poll.fields user.fields
/tweets

No expansion required for requested Tweet

Expansion for
referenced_tweets:

referenced_tweets.id

Expansion required

attachments.media_keys

Expansion required

geo.place_id

Expansion required

attachments.poll_ids

Expansion required

author_id
/users  

Expansion required

pinned_tweet_id

 N/A N/A N/A No expansion required

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

Was this document helpful?

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?

Thank you for the feedback. Your comments will help us improve our documents in the future.