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.


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.

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

No expansion required for requested Tweet

Expansion for

Expansion required


Expansion required


Expansion required


Expansion required



Expansion required


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


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


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


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