Recent search v2 (retired)
Please note:
We graduated the Labs version of recent search into Twitter API v2: Early Access and retired it in November 2020.
Learn more about the new recent search endpoint, and review our migration resources to update to The New Twitter API.
GET /labs/2/tweets/search
The Labs recent search endpoint returns Tweets from the last 7 days that match a search query.
Endpoint URL
https://api.twitter.com/labs/2/tweets/search
Authentication and rate limits
Authentication methods supported by this endpoint |
|
---|---|
Rate limit | 225 requests per 15-minute window |
Learn more about rate limits.
Query parameters
Name | Type | Description |
---|---|---|
end_time Optional |
date (ISO 8601) | YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The newest, most recent UTC timestamp to which the Tweets will be provided. Timestamp is in second granularity and is exclusive (i.e. 12:00:01 excludes the first second of the minute). |
expansions Optional |
enum (attachments.poll_ids , attachments.media_keys , author_id , entities.mentions.username , geo.place_id , in_reply_to_user_id , referenced_tweets.id , referenced_tweets.id.author_id ) |
Comma-separated list of fields to expand. Expansions enable requests to expand an ID into a full object in the includes response object. |
max_results Optional |
integer | The maximum number of search results to be returned by a request. A number between 10 and the system limit (currently 100). By default, a request response will return 10 results. |
media.fields Optional |
enum (duration_ms , height , media_key , preview_image_url , public_metrics , type , url , width ) |
Comma-separated list of media fields to return in the Tweet media object. The response will contain the selected fields only if a Tweet contains media attachments. |
next_token Optional |
string | This parameter is used to get the next 'page' of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified. |
place.fields Optional |
enum (contained_within , country , country_code , full_name , geo , id , name , place_type ) |
Comma-separated list of location fields to return. The response will contain the selected fields only if location data is present in any of the response objects. |
poll.fields Optional |
enum (duration_minutes , end_datetime , id , options , voting_status ) |
Comma-separated list of fields to return in the Tweet poll object. The response will contain the selected fields only if a Tweet contains a poll. |
query Required |
string | One query/rule/filter for matching Tweets. Up to 512 characters. |
since_id Optional |
string | Returns results with a Tweet ID greater than (that is, more recent than) the specified ID. The ID specified is exclusive and responses will not include it. |
start_time Optional |
date (ISO 8601) | YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The oldest UTC timestamp (from most recent 7 days) from which the Tweets will be provided. Timestamp is in second granularity and is inclusive (i.e. 12:00:01 includes the first second of the minute). |
tweet.fields Optional |
enum (attachments , author_id , context_annotations , created_at , entities , geo , id , in_reply_to_user_id , lang , possibly_sensitive , referenced_tweets , source , public_metrics , text , withheld ) |
Comma-separated list of fields to return in the Tweet object. By default, the endpoint only returns id and text . |
until_id Optional |
string | Returns results with a Tweet ID less than (that is, older than) the specified ID. The ID specified is exclusive and responses will not include it. |
user.fields Optional |
enum (created_at , description , entities , id , location , name , pinned_tweet_id , profile_image_url , protected , public_metrics , urls , username , verified , withheld ) |
Comma-separated list of additional fields to return in the User object. By default, the endpoint does not return any user field. |
Example requests
- cURL
curl -X GET -H "Authorization: Bearer $BEARER_TOKEN" "https://api.twitter.com/labs/2/tweets/search?query=snow"
Example responses
- Default Fields
- Optional Fields
{
"data": [
{
"id": "1227733226325774338",
"text": "@RU_DunYet Lol nah he not I get the buy one get one free ones so if it rains in snow I can get another one"
},
{
"id": "1227733226170413056",
"text": "RT @jonaxxology: \"I... loved Achilles Riego truly, Snow. He was admitted to the Philippine Navy because of me... Because I want him to succ…"
},
{
"id": "1227733225855836160",
"text": "RT @AngelFuji88812: SixTONES vs Snow Man Snow M... の 【メーカー特典あり 6タイプセット】 Imitation Rain / D.D.(SixTONES初回仕様3枚)+D... を Amazon でチェック! \nhttps:/…"
},
{
"id": "1227733222395564032",
"text": "RT @Snow8Woman8: おはようございまSnow Man⛄️\n忙しくてなかなかRT活動できないので、D.D.できるときにできるだけ!せっせとD.D.のラジオリクエストを送ってます。。\nCrazy F-R-E-S-H Beat とSnow Worldもあるから、なかなか…"
},
{
"id": "1227733222382915584",
"text": "RT @modelpress: 「Snow Manが好きすぎる!」人気声優・寺島拓篤が魅力を熱弁\n\n▼記事詳細はこちら\n\nhttps://t.co/V4xpJ7merY"
},
{
"id": "1227733221200318464",
"text": "RT @MorristownPDIN: @SeanAshWX @MorristownIN has switched from sleet to snow about 15 mins ago. Roadways are snow covered and slick from th…"
},
{
"id": "1227733220546039815",
"text": "Snow in the North Hills. Another live update @wpxi in #weather 6:17 pm. #PAwx https://t.co/aqD75WerdS"
},
{
"id": "1227733218293469184",
"text": "RT @SnowDDMan55: てか部屋割りお知らせしてくれるなんて阿部ちゃんデキジュ!…ってもうジュじゃなーいうわーん嬉しい!Snow Manさんデビューしてるし、D.D.売れてるし、Crazy F-R-E-S-H Beat見つかったし、この世は全て輝いている!!なんて素晴…"
},
{
"id": "1227733217509302272",
"text": "Official mascot of the Badtoss family is always a bit freaked out by snow. https://t.co/pj0iY2BF8I"
},
{
"id": "1227733214967496705",
"text": "私の推しトップ5!\n1位 佐久間 大介\n2位 阿部 亮平\n3位 岩本 照\n3位 深澤 辰哉\n3位 ラウール \n\n「Snow Man」のメンバーソート(画像付き)\nhttps://t.co/p0WWrwmw71\n #SnowMan"
}
],
"meta": {
"newest_id": "1227733226325774338",
"oldest_id": "1227733214967496705",
"next_token": "b26v89c19zqg8o3fo71grizwuro2f5cui3zug0s3wk8sd",
"result_count": 10
}
}
{
"data": [
{
"author_id": "899394650657759235",
"created_at": "2020-02-12T22:35:49.000Z",
"id": "1227723008200056834",
"referenced_tweets": [
{
"type": "retweeted",
"id": "1227722707942432768"
}
],
"text": "RT @gracesimon40: @OFCSSuper @OFstudentfans How many students do we need at the girls basketball senior night for a snow day tomorrow???"
},
{
"author_id": "916856066918334464",
"created_at": "2020-02-12T22:35:49.000Z",
"id": "1227723004957708288",
"referenced_tweets": [
{
"type": "retweeted",
"id": "1227655874128171008"
}
],
"text": "RT @snow_snow_dd: 大好きなSnow Manの力になりたくて、Billboardチャートランク上げ活動をしています!『Snow Man / D.D. / Crazy F-R-E-S-H Beat / Snow Worldの記載のあるツイートをRTするだけでも協力…"
},
{
"author_id": "34934156",
"created_at": "2020-02-12T22:35:48.000Z",
"id": "1227723003175129088",
"text": "SIOUX CITY IA Feb 12 Climate: Hi: None Lo: 19 Precip: Trace Snow: Missing https://t.co/RsfgL3oYvL"
},
{
"author_id": "34934156",
"created_at": "2020-02-12T22:35:48.000Z",
"id": "1227723003045089280",
"text": "HURON Feb 12 Climate: Hi: 32 Lo: -3 Precip: 0.08 Snow: 1.0 https://t.co/HBjFuH0449"
},
{
"author_id": "118870812",
"created_at": "2020-02-12T22:35:48.000Z",
"id": "1227723002998968321",
"referenced_tweets": [
{
"type": "retweeted",
"id": "1202225478502928384"
}
],
"text": "RT @247LovingLife: #etsyshop #Dimensions #Garden #Shed #Snowman #snow #Christmas #christmascountdown #CutenessOverload #crossstitch #Hobbie…"
},
{
"author_id": "34934156",
"created_at": "2020-02-12T22:35:48.000Z",
"id": "1227723002994757633",
"text": "SIOUX FALLS Feb 12 Climate: Hi: None Lo: 5 Precip: Trace Snow: Trace https://t.co/8XGrc6lonp"
},
{
"author_id": "34934156",
"created_at": "2020-02-12T22:35:48.000Z",
"id": "1227723002986426368",
"text": "MITCHELL SD Feb 12 Climate: Hi: 35 Lo: -1 Precip: Trace Snow: Missing https://t.co/dDWR8ineuK"
},
{
"author_id": "172865791",
"created_at": "2020-02-12T22:35:48.000Z",
"id": "1227723002621677570",
"text": "this SNOW tho?! im going home & having wine for dinner."
},
{
"author_id": "1048694178027327488",
"created_at": "2020-02-12T22:35:48.000Z",
"id": "1227723001258545153",
"referenced_tweets": [
{
"type": "quoted",
"id": "1227403947499040768"
}
],
"text": ".@jarpad going for a little refreshing walk in the snow https://t.co/RAIvjfZioc"
},
{
"author_id": "1218791108567650306",
"created_at": "2020-02-12T22:35:47.000Z",
"id": "1227722998850805761",
"referenced_tweets": [
{
"type": "replied_to",
"id": "1227722600626835457"
}
],
"text": "@ren_snow_man_ かわいい !"
}
],
"meta": {
"newest_id": "1227723008200056834",
"oldest_id": "1227722998850805761",
"next_token": "b26v89c19zqg8o3fo71grizm0v664moysldjqu8zh5qbh",
"result_count": 10
}
}
Response fields
Name | Type | Description |
---|---|---|
newest_id | string | Tweet ID of the most recent (largest ID) Tweet in the response. When implementing a polling use pattern, the first response contains the ID needed for setting the ```since_id``` for the next polling request. |
oldest_id | string | Tweet ID of the oldest (smallest ID) Tweet in the response. |
next_token | string | Included when there is an additional 'page' of data to request. |
result_count | integer | Indicated the number of Tweets in the response. |
id | string | Unique identifier of this Tweet. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers. |
created_at | date (ISO 8601) | Creation time of the Tweet (ISO 8601). |
text | string | The content of the Tweet. |
author_id | string | Unique identifier of this User. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers. You can obtain the expanded object in includes.users by adding expansions=author_id in the request's query parameter. |
in_reply_to_user_id | string | If this Tweet is a reply, indicates the User ID of the parent Tweet's author. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers. You can obtain the expanded object in includes.users by adding expansions=in_reply_to_user_id in the request's query parameter. |
referenced_tweets | array | A list of Tweets this Tweet refers to. For example, if the parent Tweet is a Retweet, a Quoted Tweet or a Reply, it will include the related Tweet referenced to by its parent. |
referenced_tweets.type | enum (retweeted , quoted , replied_to ) | Indicates the type of relationship between this Tweet and the Tweet returned in the response: retweeted (this Tweet is a Retweet), quoted (a Retweet with comment, also known as Quoted Tweet), or replied_to (this Tweet is a reply). |
referenced_tweets.id | string | The unique identifier of the referenced Tweet. You can obtain the expanded object in includes.tweets by adding expansions=referenced_tweets.id in the request's query parameter. |
referenced_tweets.id.author_id | string | The unique identifier of the author of the referenced Tweet. You can obtain the expanded object in includes.users by adding expansions=referenced_tweets.id.author_id in the request's query parameter. |
attachments | object | Specifies the type of attachments (if any) present in this Tweet. |
attachments.media_keys | array | List of unique identifiers of media attached to this Tweet. These identifiers use the same media key format as those returned by the Media Library. You can obtain the expanded object in includes.media by adding expansions=attachments.media_keys in the request's query parameter. |
attachments.poll_ids | array | List of unique identifiers of polls present in the Tweet delivered. These are returned as a string in order to avoid complications with languages and tools that cannot handle large integers. You can obtain the expanded object in includes.polls by adding expansions=attachments.poll_ids in the request's query parameter. |
geo | object | Contains details about the location tagged by the user in this Tweet, if they specified one. |
geo.coordinates.type | string | Describes the type of coordinate. The only value supported at present is Point . |
geo.coordinates.coordinates | array | A pair of decimal values representing the precise location of the user (latitude, longitude). This value be null unless the user explicitly shared their precise location. |
geo.place_id | string | The unique identifier of the place, if this is a point of interest tagged in the Tweet. You can obtain the expanded object in includes.places by adding expansions=geo.place_id in the request's query parameter. |
context_annotations | array | Contains context annotations for the Tweet. To return this field, add tweet.fields=context_annotations in the request's query parameter. |
context_annotations.domain | object | Contains elements which identify detailed information regarding the domain classification based on Tweet text. |
context_annotations.domain.id | string | Contains the numeric value of the domain. |
context_annotations.domain.name | string | Domain name based on the Tweet text. |
context_annotations.domain.description | string | Long form description of domain classification. |
context_annotations.entity | object | Contains elements which identify detailed information regarding the domain classification bases on Tweet text. |
context_annotations.entity.id | string | Unique value which correlates to an explicitly mentioned Person, Place, Product or Organization |
context_annotations.entity.name | string | Name or reference of entity referenced in the Tweet. |
context_annotations.entity.description | string | Additional information regarding referenced entity. |
entities | object | Contains details about text that has a special meaning in a Tweet. |
entities.urls | array | Contains details about text recognized as a URL. |
entities.urls.start | integer | The start position (zero-based) of the recognized URL within the Tweet. |
entities.urls.end | integer | The end position (zero-based) of the recognized URL within the Tweet. |
entities.urls.url | string | The URL in the format Tweeted by the user. |
entities.urls.expanded_url | string | The fully resolved URL. |
entities.urls.display_url | string | The URL as displayed in the Twitter client. |
entities.urls.unwound_url | string | The full destination URL. |
entities.hashtags | array | Contains details about text recognized as a hashtag. |
entities.hashtags.start | integer | The start position (zero-based) of the recognized hashtag within the Tweet. |
entities.hashtags.end | integer | The end position (zero-based) of the recognized hashtag within the Tweet. |
entities.hashtags.tag | string | The text of the hashtag. |
entities.mentions | array | Contains details about text recognized as a user mention. |
entities.mentions.start | integer | The start position (zero-based) of the recognized user mention within the Tweet. |
entities.mentions.end | integer | The end position (zero-based) of the recognized user mention within the Tweet. |
entities.mentions.username | string | The part of text recognized as a user mention. You can obtain the expanded object in includes.users by adding expansions=entities.mentions.username in the request's query parameter. |
entities.cashtags | array | Contains details about text recognized as a cashtag. |
entities.cashtags.start | integer | The start position (zero-based) of the recognized cashtag within the Tweet. |
entities.cashtags.end | integer | The end position (zero-based) of the recognized cashtag within the Tweet. |
entities.cashtags.tag | string | The text of the cashtag. |
withheld | object | Contains withholding details for withheld content. |
withheld.copyright | boolean | Indicates if the content is being withheld for on the basis of copyright infringement. |
withheld.country_codes | array | Provides a list of countries where this content is not available. |
withheld.scope | enum (tweet , user ) | Indicates whether the content being withheld is a Tweet or a user. |
public_metrics | object | Engagement metrics for the Tweet at the time of the request. |
public_metrics.retweet_count | integer | Number of times this Tweet has been Retweeted. |
public_metrics.reply_count | integer | Number of replies of this Tweet. |
public_metrics.like_count | integer | Number of Likes of this Tweet. |
public_metrics.quote_count | integer | Number of times this Tweet has been Retweeted with a comment (also known as Quote). |
possibly_sensitive | boolean | Indicates if this Tweet contains URLs marked as sensitive, for example content suitable for mature audiences. |
lang | string | Language of the Tweet, if detected by Twitter. Returned as a BCP47 language tag. |
source | string | The name of the app the user Tweeted from. |
includes | object | Returns the requested expansions, if available. |
includes.tweets | array | For referenced Tweets, this is a list of objects with the same structure as the one described in this page. |
includes.users | array | For referenced users, this is a list of objects with the same structure as the one described by GET /users. |
includes.places.id | string | The unique identifier of the place, if this is a point of interest tagged in the Tweet. |
includes.places.name | string | The short name of this place, for example San Francisco . |
includes.places.full_name | string | A longer-form detailed place name, for example San Francisco, CA . |
includes.places.place_type | enum (city , unknown , country , admin , neighborhood , poi , zip_code , metro , admin0 , admin1 ) | Specified the particular type of information represented by this place information, such as a city name, or a point of interest. |
includes.places.country_code | string | The ISO Alpha-2 country code this place belongs to. |
includes.places.country | string | The full-length name of the country this place belongs to. |
includes.places.contained_within | array | Returns the identifiers of known places that contain the referenced place. |
includes.places.geo | object | Contains place details in GeoJSON format. |
includes.places.geo.type | string | The type of place described by this object. At present, this API only returns objects of type Feature . |
includes.places.geo.bbox | array | The bounding box coordinates for this place (latitude_start, longitude_start, latitude_end, longitude_end). |
includes.places.geo.geometry | object | Contains GeoJSON point information for this place, if available. |
includes.places.geo.coordinates.type | string | Describes the type of coordinate. The only value supported at present is Point . |
includes.places.geo.coordinates.coordinates | array | A pair of decimal values representing the precise location of the user (latitude, longitude). This value be null unless the user explicitly shared their precise location. |
includes.places.geo.coordinates.properties | object | A dictionary containing additional properties, as defined by the GeoJSON specification. Can be empty. |
includes.media | array | For referenced media attachments, this is a list of objects describing media content. |
includes.media.media_key | string | Unique identifiers for this expanded media content. This is returned using the same media key format as returned by the Media Library. |
includes.media.height | integer | Height of this content in pixels. |
includes.media.public_metrics | object | Engagement metrics for the media content at the time of the request. |
includes.media.public_metrics.view_count | integer | The count of how many times the video attached to this Tweet has been viewed. This is the number of video views aggregated across all Tweets in which the given video has been posted. That means that the metric includes the combined views from any instance where the video has been Retweeted or reposted in separate Tweets. This returns the total count of video views from both organic and paid contexts, in order to maintain consistency with the counts shown publicly on Twitter. |
includes.media.width | integer | Width of this content in pixels. |
includes.media.preview_image_url | string | URL to the static placeholder preview of this content. |
includes.media.duration_ms | integer | Available when `includes.media.type` is `video`. Duration in milliseconds of the video. |
includes.media.type | enum (animated_gif , photo , video ) | Type of content. |
includes.polls | string | For referenced polls, this is a list of objects describing polls. |
includes.polls.id | string | Unique identifiers of the expanded poll. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers. |
includes.polls.options | array | Contains objects describing each choice in the referenced poll. |
includes.polls.options.position | integer | Position of this choice in the poll. |
includes.polls.options.label | string | Text of the poll choice. |
includes.polls.options.votes | integer | Number of votes this poll choice received. |
includes.polls.options.voting_status | enum (open , closed ) | Indicates if this poll is still active and can receive votes, or if the voting is now closed. |
includes.polls.end_datetime | date (ISO 8601) | Specifies the end date and time for this poll (ISO 8601). |
includes.polls.duration_minutes | integer | Specifies the total duration of this poll. |