GET /labs/1/tweets/search

The Labs recent search endpoint returns Tweets from the last 7 days that match a search query.

 

Authentication and rate limits

Authentication methods
supported by this endpoint

OAuth 2.0 Bearer token

OAuth 1.0a

Rate limit 225 requests per 15-minute window
Tweet limit 500,000 per month

Learn more about rate limits.

 

Request parameters

Name Type Description
query
 Required 
string One query/rule/filter for matching Tweets. Up to 512 characters.
start_time
 Optional 
date (ISO 8601/RFC 3339) YYYY-MM-DDTHH:mm:ssZ. 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).
end_time
 Optional 
date (ISO 8601/RFC 3339) YYYY-MM-DDTHH:mm:ssZ. 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).
since_id
 Optional 
long integer Returns results with a Tweet ID greater than (that is, more recent than) the specified ID.
until_id
 Optional 
long integer Returns results with a Tweet ID less than (that is, older than) the specified ID.
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.
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.
format
 Optional 
enum (compact, default, detailed) Format for all the objects returned as part of the response, including those returned in expansions.
tweet.format
 Optional 
enum (compact, default, detailed) Format for all Tweet objects returned in response. Can be used together with other format parameters to expand or reduce Tweet objects only.
user.format
 Optional 
enum (compact, default, detailed) Format for all User objects returned in response. Can be used together with other format parameters to expand or reduce User objects only.
place.format
 Optional 
enum (compact, default, detailed) Format for all Place objects returned in response. Can be used together with other format parameters to expand or reduce Place objects only.
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.



Examples

  • cURL
curl -X GET -H "Authorization: Bearer $BEARER_TOKEN" "https://api.twitter.com/labs/1/tweets/search?query=snow"

Response

The Labs recent search endpoint returns a JSON response "payload" with two root/top-level sections: data and meta.  The data section is an array of matching Tweets. The meta section provides pagination information and then Tweet ID range contained in the response. Both sections are described below. 

As described above, the format request parameter sets the level of Tweet detail to return. This parameter can be set to compact, default, and detailed:

 

  • Default format
  • Compact format
  • Detailed format
{
  "data": [
    {
      "author_id": "2244994945",
      "created_at": "2019-10-29T19:37:16.000Z",
      "entities": {
        "urls": [
          {
            "start": 154,
            "end": 177,
            "url": "https://t.co/4jFQf5JVi0",
            "expanded_url": "https://developer.twitter.com/en/labs",
            "display_url": "developer.twitter.com/en/labs"
          }
        ]
      },
      "id": "1189264960884482049",
      "in_reply_to_user_id": "2244994945",
      "possibly_sensitive": false,
      "referenced_tweets": [
        {
          "type": "replied_to",
          "id": "1189264959701733376"
        }
      ],
      "source": "<a href=\"https://mobile.twitter.com\" rel=\"nofollow\">Twitter Web App</a>",
      "stats": {
        "retweet_count": 2,
        "reply_count": 0,
        "like_count": 9,
        "quote_count": 0
      },
      "text": "If you’re not already part of Twitter Developer Labs, join us! Through Labs, you can share your feedback on what we’re building and test things as we go. https://t.co/4jFQf5JVi0",
      "format": "default"
    }
  ],
  "meta": {
    "newest_id": "1189264960884482049",
    "oldest_id": "1189264960884482049",
    "result_count": 1
  }
}
{
  "data": [
    {
      "author_id": "2244994945",
      "created_at": "2019-10-29T19:37:16.000Z",
      "id": "1189264960884482049",
      "referenced_tweets": [
        {
          "type": "replied_to",
          "id": "1189264959701733376"
        }
      ],
      "text": "If you’re not already part of Twitter Developer Labs, join us! Through Labs, you can share your feedback on what we’re building and test things as we go. https://t.co/4jFQf5JVi0",
      "format": "compact"
    }
  ],
  "meta": {
    "newest_id": "1189264960884482049",
    "oldest_id": "1189264960884482049",
    "result_count": 1
  }
}
{
  "data": [
    {
      "author_id": "2244994945",
      "created_at": "2019-10-29T19:37:16.000Z",
      "entities": {
        "urls": [
          {
            "start": 154,
            "end": 177,
            "url": "https://t.co/4jFQf5JVi0",
            "expanded_url": "https://developer.twitter.com/en/labs",
            "display_url": "developer.twitter.com/en/labs"
          }
        ]
      },
      "id": "1189264960884482049",
      "in_reply_to_user_id": "2244994945",
      "lang": "en",
      "possibly_sensitive": false,
      "referenced_tweets": [
        {
          "type": "replied_to",
          "id": "1189264959701733376"
        }
      ],
      "source": "<a href=\"https://mobile.twitter.com\" rel=\"nofollow\">Twitter Web App</a>",
      "stats": {
        "retweet_count": 2,
        "reply_count": 0,
        "like_count": 9,
        "quote_count": 0
      },
      "text": "If you’re not already part of Twitter Developer Labs, join us! Through Labs, you can share your feedback on what we’re building and test things as we go. https://t.co/4jFQf5JVi0",
      "format": "detailed"
    }
  ],
  "meta": {
    "newest_id": "1189264960884482049",
    "oldest_id": "1189264960884482049",
    "result_count": 1
  }
}

"meta" response fields

When Recent search queries match one or more Tweets, the response will include a "meta" section. Metadata provided here include the Tweet ID range in the response, from oldest_id to newest_id. When there are more "pages" of Tweets available, a next_token will be provided. This token is added with the next_token request parameter to the request for the next page of data. 

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_counts integer Indicates the number of Tweets in the response.


"data" response array with Tweet objects

Recent search will respond with a data array, containing matching Tweets. If no Tweet match, that array will be empty. If there are matching Tweets, individual Tweets in the array can have the following attributes. 

Name Type Description
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.

 default   compact   detailed 
created_at date (ISO 8601) Creation time of the Tweet.

 default   compact   detailed 
text string The content of the Tweet.

 default   compact   detailed 
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.

 default   compact   detailed 
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.

 default   compact   detailed 
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.

 default   compact   detailed 
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).

 default   compact   detailed 
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.

 default   compact   detailed 
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.

 default   compact   detailed 
attachments.media_keys array (string) 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.

 default   compact   detailed 
attachments.poll_ids array (string) 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.polls_ids in the request's query parameter.

 default   compact   detailed 
geo object Contains details about the location tagged by the user in this Tweet, if they specified one.

 default   detailed 
geo.coordinates.type string Describes the type of coordinate. The only value supported at present is Point.

 default   detailed 
geo.coordinates.coordinates array (latitude, longitude) A pair of decimal values representing the precise location of the user. This value be null unless the user explicitly shared their precise location.

 default   detailed 
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.

 default   detailed 
entities object Contains details about text that has a special meaning in a Tweet.

 default   detailed 
entities.url array Contains details about text recognized as a URL.

 default   detailed 
entities.url.start integer The start position (zero-based) of the recognized URL within the Tweet.

 default   detailed 
entities.url.end integer The end position (zero-based) of the recognized URL within the Tweet.

 default   detailed 
entities.url.url string The URL in the format Tweeted by the user.

 default   detailed 
entities.url.expanded_url string The fully resolved URL.

 default   detailed 
entities.url.display_url string The URL as displayed in the Twitter client.

 default   detailed 
entities.hashtags array Contains details about text recognized as a hashtag.

 default   detailed 
entities.hashtags.start integer The start position (zero-based) of the recognized hashtag within the Tweet.

 default   detailed 
entities.hashtags.end integer The end position (zero-based) of the recognized hashtag within the Tweet.

 default   detailed 
entities.hashtags.hashtag string The text of the hashtag.

 default   detailed 
entities.mentions array Contains details about text recognized as a user mention.

 default   detailed 
entities.mentions.start integer The start position (zero-based) of the recognized user mention within the Tweet.

 default   detailed 
entities.mentions.end integer The end position (zero-based) of the recognized user mention within the Tweet.

 default   detailed 
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.

 default   detailed 
entities.cashtags array Contains details about text recognized as a cashtag.

 default   detailed 
entities.cashtags.start integer The start position (zero-based) of the recognized cashtag within the Tweet.

 default   detailed 
entities.hashtags.end integer The end position (zero-based) of the recognized cashtag within the Tweet.

 default   detailed 
entities.cashtags.cashtag string The text of the cashtag.

 default   detailed 
withheld object Contains withholding details for withheld content.

 default   compact   detailed 
withheld.copyright boolean Indicates if the content is being withheld for on the basis of copyright infringement.

 default   compact   detailed 
withheld.country_codes array Provides a list of countries where this content is not available.

 default   compact   detailed 
withheld.scope enum (tweet, user) Indicates whether the content being withheld is a Tweet or a user.

 default   compact   detailed 
stats object Engagement metrics for the Tweet at the time of the request.

 default   detailed 
stats.retweet_count integer Number of times this Tweet has been Retweeted.

 default   detailed 
stats.reply_count integer Number of replies of this Tweet.

 default   detailed 
stats.like_count integer Number of Likes of this Tweet.

 default   detailed 
stats.quote_count integer Number of times this Tweet has been Retweeted with a comment (also known as Quote).

 default   detailed 
possibly_sensitive boolean Indicates if this Tweet contains URLs marked as sensitive, for example content suitable for mature audiences.

 detailed 
lang string Language of the Tweet, if detected by Twitter. Returned as a BCP47 language tag.

 detailed 
source string The name of the app the user Tweeted from.

 detailed 
format enum (default, compact, detailed) Indicates the format returned for this object, as requested in the format or tweet.format query parameters.

 default   compact   detailed 
includes object Returns the requested expansions, if available.

 default   compact   detailed 
includes.tweets array For referenced Tweets, this is a list of objects with the same structure as the one described in this page.

 default   compact   detailed 
includes.users array For referenced users, this is a list of objects with the same structure as the one described by GET /users.

 default   compact   detailed 
includes.places.id string The unique identifier of the place, if this is a point of interest tagged in the Tweet.

 default   compact   detailed 
includes.places.name string The short name of this place, for example San Francisco.

 default   compact   detailed 
includes.places.full_name string A longer-form detailed place name, for example San Francisco, CA.

 default   detailed 
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.

 default   detailed 
includes.places.country_code string The ISO Alpha-2 country code this place belongs to.

 default   compact   detailed 
includes.places.country string The full-length name of the country this place belongs to.

 default   detailed 
includes.places.contained_within array Returns the identifiers of known places that contain the referenced place.

 default   detailed 
includes.places.geo object Contains place details in GeoJSON format.

 detailed 
includes.places.geo.type string The type of place described by this object. At present, this API only returns objects of type Feature.

 detailed 
includes.places.geo.bbox array (latitude_start, longitude_start, latitude_end, longitude_end) The bounding box coordinates for this place.

 detailed 
includes.places.geo.geometry object Contains GeoJSON point information for this place, if available.

 detailed 
includes.places.geo.coordinates.type string Describes the type of coordinate. The only value supported at present is Point.

 detailed 
includes.places.geo.coordinates.coordinates array (latitude, longitude) A pair of decimal values representing the precise location of the user. This value be null unless the user explicitly shared their precise location.

 detailed 
includes.places.geo.coordinates.properties object A dictionary containing additional properties, as defined by the GeoJSON specification. Can be empty.

 detailed 
includes.media string For referenced media attachments, this is a list of objects describing media content.

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

 detailed 
includes.media.height integer Height of this content in pixels.

 detailed 
includes.media.width integer Width of this content in pixels.

 detailed 
includes.media.preview_image_url string URL to the static placeholder preview of this content.

 detailed 
includes.media.duration_ms integer Available when `includes.media.type` is `video`. Duration in milliseconds of the video.

 detailed 
includes.media.type enum (animated_gif, photo, video) Type of content.

 detailed 
includes.polls string For referenced polls, this is a list of objects describing polls.

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

 detailed 
includes.polls.options array Contains objects describing each choice in the referenced poll.

 detailed 
includes.polls.options.position integer Position of this choice in the poll.

 detailed 
includes.polls.options.label string Text of the poll choice.

 detailed 
includes.polls.options.votes integer Number of votes this poll choice received.

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

 detailed 
includes.polls.end_datetime date (ISO 8601) Specifies the end date and time for this poll.

 detailed 
includes.polls.duration_minutes integer Specifies the total duration of this poll.

 detailed 
matching_rules array Contains the list of filters that matched against the Tweet delivered.

 compact   default   detailed 
matching_rules.id string ID of the filter rule that matched against the Tweet delivered.

 compact   default   detailed 
matching_rules.tag string The tag label of the filter rule that matched against the Tweet delivered.

 compact   default   detailed