Twitter Tweets & Archive Search (V2) - Data API Endpoint

Tweets & Archive Search (V2) by query, bearer token, pagination token, expansions, fields (media), fields (places), fields (polls) and fields (tweets).


Download Twitter Tweets & Archive Search (V2) data from the Official Twitter API | 👥  Contributors: steve 🚩  Report

✏️ Inputs

Query query Required

Search query to run on Twitter, see Twitter API Query Builder Documentation for examples and the Twitter Search API Quick Start Guide.

Some common example (you can combine these with a space in between to do an AND search):

  • from:twitterdev Gets tweets from the @twitterdev account (leave out the @ in your query)
  • #beer Gets tweets containing the hashtag #beer
  • @twitterdev Gets tweets mentioning @twitterdev
  • lang:en Restrict tweets to a certain language. See all codes in building a query (scroll to the bottom).
  • conversation_id:1555434849908903936 Only retrieve Tweets that belong to a conversation (e.g. replies, retweets, etc…) by passing in the Tweet ID. E.g. if you want to get all the replies to https://twitter.com/Google/status/1555434849908903936 then pass in conversation_id:1555434849908903936 as your query. You can also use this with deeper threads by looking for conversation_id in responses.

These require the Academic Research Project:

  • place:"new york city" Get Tweets geo-located in New York City
  • $TWTR Gets tweets mentioning the cashtag $TWTR

You may also want to add -is:retweet -is:reply -is:quote to your query to avoid these other types.

E.g. #beer lang:en -is:retweet -is:reply -is:quote
Bearer Token access_token Required

Your Twitter app’s Bearer Token for collecting data with. If you don’t have one, see How to Get a Twitter API Key Without Approval or check out Twitter’s docs on Bearer Tokens for more information.

If you get the error client-not-enrolled, then make sure you’re not using a standalone app and try creating a new application with the Add App button under a project and NOT under the standalone section.

Pagination Token pagination_token Optional

Used for pagination. Provide the next_token you see in a response here to get the next page of results.

Expansions expansions Optional

A comma-separated list of additional data to return back in the response. See Twitter API Expansions for possible values or copy the example value here to get as much data back as possible.

E.g. author_id,referenced_tweets.id,in_reply_to_user_id,attachments.media_keys,attachments.poll_ids,geo.place_id,entities.mentions.username,referenced_tweets.id.author_id
Fields (Media) media_fields Optional

A comma-separated list of fields you would like back for media objects (photos, videos, etc…). See the Twitter API Media Model or just use the example value here to get back as much data as possible.

E.g. duration_ms,height,preview_image_url,public_metrics,width
Fields (Places) place_fields Optional

A comma-separated list of fields you would like back for places tagged in Tweets within the response. See the Twitter API Places Model for details or just use the example value here to get back as much data as possible.

E.g. contained_within,country,country_code,geo,name,place_type
Fields (Polls) poll_fields Optional

A comma-separated list of fields you to return for Tweets with attached polls. See the Twitter API Poll Model for details or just use the example value here to get back as much data as possible.

E.g. duration_minutes,end_datetime,voting_status
Fields (Tweets) tweet_fields Optional

A comma-separated list of fields you would like back for Tweets returned in the response. See the Twitter API Tweet Model for all possible values or just use the example value here to get as much data back as possible.

E.g. attachments,author_id,context_annotations,conversation_id,created_at,entities,geo,in_reply_to_user_id,lang,possibly_sensitive,public_metrics,referenced_tweets,reply_settings,source,withheld
Fields (Users) user_fields Optional

A comma-separated list of fields you would like back for users in the response. See the Twitter API User Model for more information or just use the example value here to get as much data back as possible.

E.g. created_at,description,entities,location,pinned_tweet_id,profile_image_url,protected,public_metrics,url,verified,withheld
Time Range (Ending Time) end_time Optional

End time range of the Tweets to fetch. This is exclusive, e.g. 2021-01-01T00:00:01Z will exclude the first second of 2021. Format is in YYYY-MM-DDTHH:mm:ssZ. If querying the archive (beyond 7 days ago), make sure you set “Recent or All” to all.

E.g. 2021-02-01T00:00:00Z
Time Range (Starting Time) start_time Optional

The starting timestamp of Tweets to return in the query. This is inclusive, so 2020-01-01T00:00:00 will include the first second of the new year. If querying the archive (beyond 7 days ago), make sure you set “Recent or All” to all.

E.g. 2020-01-01T00:00:00Z
Recent or All recent_or_all Default recent

Leave this as the default recent to search for Tweets published in the last 7 days. Change this to all to access the Twitter API V2 Full Archive Search (only available to users on the Academic Research product track) - this will return the most recent 30 days unless you provide a time range.

Limit limit Optional

How many results to return on each request.

📝 Notes

Twitter API V2 for searching recent Tweets or from the full archive since 2006. See the Twitter Search API Endpoint for more information.

Posted by steve on Sept. 30, 2022, 6:30 a.m. 🚩  Report

⚡️ Endpoint

GET https://api.twitter.com/2/tweets/search/{{recent_or_all}}?query={{query}}&max_results={{ limit }}&tweet.fields={{tweet_fields}}&user.fields={{user_fields}}&media.fields={{media_fields}}&poll.fields={{poll_fields}}&place.fields={{place_fields}}&expansions={{expansions}}&next_token={{pagination_token}}&end_time={{end_time}}&start_time={{start_time}}

Body

None

Headers

Authorization
Bearer {{access_token}}