Fields | Twitter Developer Fields Introduction 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 parameters, you can request additional fields of the object to include in the response. This is done by specifying one of the below parameters, including a comma-separated list of fields that you would like to return. 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 /tweets/search/recent endpoint, you will primarily receive Tweet objects in that response. Without specifying any fields parameters, 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 request would look like the following. If you would like to use this request, make sure to replace $BEARER_TOKEN with your Bearer Token and send it using your command line tool. curl --request GET \ --url 'https://api.twitter.com/2/tweets/search/recent?query=from%3Atwitterdev&tweet.fields=public_metrics' \ --header 'Authorization: Bearer $BEARER_TOKEN' Code copied to clipboard If you send this request in your terminal, then each of the Tweets that return will include the following 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 returned by an endpoint, you will need to include an additional expansions parameter.  For example, if you were using the same GET search/tweets/recent endpoint as earlier, and you wanted to retrieve the author's profile description, you will have to pass the expansions=author_id and user.fields=description with your request. Here is an example of what this might look like. If you would like to try this request, make sure to replace the $BEARER_TOKEN with your Bearer Token before pasting it into your command line tool. curl --request GET \ --url 'https://api.twitter.com/2/tweets/search/recent?query=from%3Atwitterdev&tweet.fields=public_metrics&expansions=author_id&user.fields=description' \ --header 'Authorization: Bearer $BEARER_TOKEN' Code copied to clipboard If you specify this in the request, then each of the Tweets that deliver will have the following fields, and the related user object's default and specified fields will return within includes. The user object can be mapped back to the corresponding Tweet(s) by matching the tweet.author_id and users.id fields.   { "data": [ { "id": "1263150595717730305", "author_id": "2244994945", "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", "public_metrics": { "retweet_count": 12, "reply_count": 13, "like_count": 51, "quote_count": 7 } } ], "includes": { "users": [ { "id": "2244994945", "username": "TwitterDev", "description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.", "name": "Twitter Dev" } ] } } Bear in mind that 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. We have listed all possible fields that you can request in each endpoints' API reference page's parameters table.  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. Next step Learn how to use Fields with Expansions Review the different data objects available with Twitter API v2 Make your first request with Fields and Expansions 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? This page is missing information. The information was hard to follow or confusing. There is inaccurate information. There is a broken link or typo. Specific Feedback Submit feedback Skip Thank you for the feedback. Your comments will help us improve our documents in the future. Developer agreement, policy & terms Follow @twitterdev Subscribe to developer news Twitter platform Twitter.com Status Card validator Privacy Center Transparency Center Twitter, Inc. About the company Twitter for Good Company news Brand toolkit Jobs and internships Investors Help Help Center Using Twitter Twitter Media Ads Help Center Managing your account Safety and security Rules and policies Contact us Developer resources Developer home Documentation Forums Communities Developer blog Engineering blog Developer terms Business resources Advertise Twitter for business Resources and guides Twitter for marketers Marketing insights Brand inspiration Twitter Data Twitter Flight School © 2021 Twitter, Inc. Cookies Privacy Terms and conditions Language Developer By using Twitter’s services you agree to our Cookies Use. We use cookies for purposes including analytics, personalisation, and ads. OK This page and certain other Twitter sites place and read third party cookies on your browser that are used for non-essential purposes including targeting of ads. Through these cookies, Google, LinkedIn and Demandbase collect personal data about you for their own purposes. Learn more. Accept Decline