Sampled stream v1

API reference contents

Interested in exploring Labs?
The endpoints we release in Labs are previews of tools that may be released more broadly in the future, but will likely undergo changes before then. We encourage you to take that into consideration as you explore. Before getting started, please read more about Twitter Developer Labs.
 

GET /labs/1/tweets/stream/sample

Streams about 1% of all Tweets in real-time.



Authentication and rate limits

Authentication methods
supported by this endpoint

OAuth 2.0 Bearer token

Rate limit 50 requests per 15-minute window

Learn more about rate limits.



Query parameters

Name Type Description
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/stream/sample"

Response

  • Default format
  • Compact format
  • Detailed format
{
  "data": {
    "id": "1189226081406083073",
    "created_at": "2019-10-29T17:02:47.000Z",
    "text": "Sharing Tweets in DMs is our love language. Today, for Android users, we’re making that easier.",
    "author_id": "783214",
    "in_reply_to_user_id": "783214",
    "referenced_tweets": [
      {
        "type": "replied_to",
        "id": "1151997885455581185"
      }
    ],
    "format": "default"
  }
}
{
  "data": {
    "id": "1189226081406083073",
    "created_at": "2019-10-29T17:02:47.000Z",
    "text": "Sharing Tweets in DMs is our love language. Today, for Android users, we’re making that easier.",
    "author_id": "783214",
    "in_reply_to_user_id": "783214",
    "referenced_tweets": [
      {
        "type": "replied_to",
        "id": "1151997885455581185"
      }
    ],
    "format": "compact"
  }
}
{
  "data": {
    "id": "1189226081406083073",
    "created_at": "2019-10-29T17:02:47.000Z",
    "text": "Sharing Tweets in DMs is our love language. Today, for Android users, we’re making that easier. See more details: https://t.co/eu1upmY4yo",
    "author_id": "783214",
    "in_reply_to_user_id": "783214",
    "referenced_tweets": [
      {
        "type": "replied_to",
        "id": "1151997885455581185"
      }
    ],
    "entities": {
      "urls": [
        {
          "start": 113,
          "end": 137,
          "url": "https://t.co/eu1upmY4yo",
          "expanded_url": "http://developer.twitter.com",
          "display_url": "developer.twitter.com",
          "status": 200,
          "title": "Developers Tap into What’s Happening",
          "description": "Discover the power of Twitter APIs"
        }
      ],
      "annotations": [
        {
          "start": 55,
          "end": 61,
          "probability": 0.9596,
          "type": "Product",
          "normalized_text": "Android"
        }
      ]
    },
    "stats": {
      "retweet_count": 341,
      "reply_count": 372,
      "like_count": 2773,
      "quote_count": 70
    },
    "possibly_sensitive": false,
    "lang": "en",
    "source": "<a href=\"https://mobile.twitter.com\" rel=\"nofollow\">Twitter Web App</a>",
    "context_annotations": [
      {
        "domain": {
          "id": "45",
          "name": "Brand Vertical",
          "description": "Top level entities that describe a Brands industry"
        },
        "entity": {
          "id": 781974596165640193,
          "name": "Technology",
          "description": "This entity includes conversation about Information Technology"
        }
      },
      {
        "domain": {
          "id": "46",
          "name": "Brand Category",
          "description": "Categories within Brand Verticals that narrow down the scope of Brands"
        },
        "entity": {
          "id": 10026820777,
          "name": "Android",
          "description": "Mobile operating system based on the Linux kernel."
        }
      }
    ],
    "format": "detailed"
  }
}

Response fields

NameTypeDescription
idstringUnique 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_atdate (ISO 8601)Creation time of the Tweet.

 default   compact   detailed 
textstringThe content of the Tweet.

 default   compact   detailed 
author_idstringUnique 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_idstringIf 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_tweetsarrayA 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.typeenum (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.idstringThe 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_idstringThe 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.
attachmentsobjectSpecifies the type of attachments (if any) present in this Tweet.

 default   compact   detailed 
attachments.media_keysarrayList 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_idsarrayList 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 
geoobjectContains details about the location tagged by the user in this Tweet, if they specified one.

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

 default   detailed 
geo.coordinates.coordinatesarrayA 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.

 default   detailed 
geo.place_idstringThe 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 
entitiesobjectContains details about text that has a special meaning in a Tweet.

 default   detailed 
entities.urlarrayContains details about text recognized as a URL.
entities.url.startintegerThe start position (zero-based) of the recognized URL within the Tweet.
entities.url.endintegerThe end position (zero-based) of the recognized URL within the Tweet.
entities.url.urlstringThe URL in the format Tweeted by the user.
entities.url.expanded_urlstringThe fully resolved URL.
entities.url.display_urlstringThe URL as displayed in the Twitter client.
entities.urls.display_urlstringThe URL as displayed in the Twitter client.
entities.urls.statusstringThe status code of the URL.
entities.urls.titlestringThe title of the web page.
entities.urls.descriptionstringThe description of the document.
entities.annotationsarrayContains details about annotations relative to the text within a Tweet.
entities.annotations.startintegerThe start position (zero based) of the text used to annotate the Tweet.
entities.annotations.endintegerThe end position (zero based) of the text used to annotate the Tweet.
entities.annotations.probabilitynumberThe confidence score for the annotation as it correlates to the Tweet text.
entities.annotations.typestringThe description of the type of entity identified when the Tweet text was interpreted.
entities.annotations.normalized_textstringThe text used to determine the annotation type.
entities.hashtagsarrayContains details about text recognized as a hashtag.
entities.hashtags.startintegerThe start position (zero-based) of the recognized hashtag within the Tweet.
entities.hashtags.endintegerThe end position (zero-based) of the recognized hashtag within the Tweet.
entities.hashtags.hashtagstringThe text of the hashtag.
entities.mentionsarrayContains details about text recognized as a user mention.
entities.mentions.startintegerThe start position (zero-based) of the recognized user mention within the Tweet.
entities.mentions.endintegerThe end position (zero-based) of the recognized user mention within the Tweet.
entities.mentions.usernamestringThe 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.cashtagsarrayContains details about text recognized as a cashtag.
entities.cashtags.startintegerThe start position (zero-based) of the recognized cashtag within the Tweet.
entities.hashtags.endintegerThe end position (zero-based) of the recognized cashtag within the Tweet.
entities.cashtags.cashtagstringThe text of the cashtag.
withheldobjectContains withholding details for withheld content.

 default   compact   detailed 
withheld.copyrightbooleanIndicates if the content is being withheld for on the basis of copyright infringement.
withheld.country_codesarrayProvides a list of countries where this content is not available.
withheld.scopeenum (tweet, user)Indicates whether the content being withheld is a Tweet or a user.
statsobjectEngagement metrics for the Tweet at the time of the request.

 detailed 
stats.retweet_countintegerNumber of times this Tweet has been Retweeted.
stats.reply_countintegerNumber of replies of this Tweet.
stats.like_countintegerNumber of Likes of this Tweet.
stats.quote_countintegerNumber of times this Tweet has been Retweeted with a comment (also known as Quote).
possibly_sensitivebooleanIndicates if this Tweet contains URLs marked as sensitive, for example content suitable for mature audiences.

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

 detailed 
sourcestringThe name of the app the user Tweeted from.

 detailed 
context_annotationsobjectContains context annotations for the Tweet.

 detailed 
context_annotations.domainarrayContains elements which identify detailed information regarding the domain classification based on Tweet text.

 detailed 
context_annotations.domain.idintegerContains the numeric value of the domain.

 detailed 
context_annotations.domain.namestringDomain name based on the Tweet text.

 detailed 
context_annotations.domain.descriptionstringLong form description of domain classification.

 detailed 
context_annotations.entityarrayContains elements which identify detailed information regarding the domain classification bases on Tweet text.

 detailed 
context_annotations.entity.idintegerUnique value which correlates to an explicitly mentioned Person, Place, Product or Organization

 detailed 
context_annotations.entity.namestringName or reference of entity referenced in the Tweet.

 detailed 
context_annotations.entity.descriptionstringAdditional information regarding referenced entity.

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

 default   compact   detailed 
includesobjectReturns the requested expansions, if available.

 default   compact   detailed 
includes.tweetsarrayFor referenced Tweets, this is a list of objects with the same structure as the one described in this page.
includes.usersarrayFor referenced users, this is a list of objects with the same structure as the one described by GET /users.
includes.places.idstringThe unique identifier of the place, if this is a point of interest tagged in the Tweet.

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

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

 default   detailed 
includes.places.place_typeenum (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_codestringThe ISO Alpha-2 country code this place belongs to.

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

 default   detailed 
includes.places.contained_withinarrayReturns the identifiers of known places that contain the referenced place.

 default   detailed 
includes.places.geoobjectContains place details in GeoJSON format.

 detailed 
includes.places.geo.typestringThe type of place described by this object. At present, this API only returns objects of type Feature.
includes.places.geo.bboxarrayThe bounding box coordinates for this place (latitude_start, longitude_start, latitude_end, longitude_end).
includes.places.geo.geometryobjectContains GeoJSON point information for this place, if available.
includes.places.geo.coordinates.typestringDescribes the type of coordinate. The only value supported at present is Point.
includes.places.geo.coordinates.coordinatesarrayA 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.propertiesobjectA dictionary containing additional properties, as defined by the GeoJSON specification. Can be empty.
includes.mediastringFor referenced media attachments, this is a list of objects describing media content.
includes.media.media_keystringUnique identifiers for this expanded media content. This is returned using the same media key format as returned by the Media Library.
includes.media.heightintegerHeight of this content in pixels.
includes.media.widthintegerWidth of this content in pixels.
includes.media.preview_image_urlstringURL to the static placeholder preview of this content.
includes.media.duration_msintegerAvailable when `includes.media.type` is `video`. Duration in milliseconds of the video.
includes.media.typeenum (animated_gif, photo, video)Type of content.
includes.pollsstringFor referenced polls, this is a list of objects describing polls.
includes.polls.idstringUnique 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.optionsarrayContains objects describing each choice in the referenced poll.
includes.polls.options.positionintegerPosition of this choice in the poll.
includes.polls.options.labelstringText of the poll choice.
includes.polls.options.votesintegerNumber of votes this poll choice received.
includes.polls.options.voting_statusenum (open, closed)Indicates if this poll is still active and can receive votes, or if the voting is now closed.
includes.polls.end_datetimenumberSpecifies the end date and time for this poll.
includes.polls.duration_minutesintegerSpecifies the total duration of this poll.