Fields

The Twitter API v2 endpoints are equipped with a new set of parameters called fields, which allows you to select just the data that you want from each of our objects in your endpoint response. For example, if you only need to retrieve a Tweet’s created date, or a user’s bio description, you can specifically request that data to return with a set of other default fields without the full set of fields that associate with that data object. This provides a higher degree of customization by enabling you to only request the fields you require depending on your use case.

Default fields will always be returned in the response. With the fields query parameter, you can request additional fields of the object to include in the response. This is done by specifying the object, followed by the dot (.) operator, then fields.

Each object has its own parameter which is used to specifically request the fields that are associated with that object. Here are the different fields parameters that are currently available:

  • Tweet → tweet.fields
  • User → user.fields
  • Media → media.fields
  • Poll → poll.fields
  • Place → place.fields

When using an endpoint that primarily returns a particular object, simply use the matching field parameter and specify the field(s) desired in a comma-separated list as the value to that parameter to retrieve those fields in the response.;

For example, if you are using the GET /search/tweets endpoint, you will primarily receive Tweet objects in that response. Without specifying any fields, you will just receive the default values, id and text. If you are interested in receiving the public metrics of the Tweets that are returned in the response, you will want to include the tweet.fields parameter in your request, with public_metrics set as the value. This will look like the following:

 ?tweet.fields=public_metrics

If you specify this in the request, then each of the Tweets that deliver with your request will return with the following included fields:

{
   "data": {
       "id": "1263150595717730305",
       "public_metrics": {
           "retweet_count": 12,
           "reply_count": 14,
           "like_count": 49,
           "quote_count": 7
       },
       "text": "Do you 👀our new Tweet settings?\n\nWe want to know how and why you’d use a feature like this in the API. Get the details and let us know what you think👇\nhttps://t.co/RtMhhfAcIB https://t.co/8wxeZ9fJER"
   }
}

If you would like to retrieve a set of fields from a secondary object that is associated with the primary object that is returned in the endpoint you are using, you will need to include an additional expansions parameter.

Bear in mind you cannot request specific subfields (for example, public_metrics.retweet_count). All subfields will be returned when the top-level field (public_metrics) is specified.

A full list of fields are listed in the object model. To expand and request fields on an object that is not that endpoint’s primary resource, use the expansions parameter with fields.

Was this document helpful?

Thank you

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.