lookupTweets abstract method

Future<TwitterResponse<List<TweetData>, TweetMeta>> lookupTweets({
  1. required String userId,
  2. int? maxResults,
  3. String? paginationToken,
  4. DateTime? startTime,
  5. DateTime? endTime,
  6. String? sinceTweetId,
  7. String? untilTweetId,
  8. List<ExcludeTweetType>? excludes,
  9. List<TweetExpansion>? expansions,
  10. List<TweetField>? tweetFields,
  11. List<UserField>? userFields,
  12. List<PlaceField>? placeFields,
  13. List<PollField>? pollFields,
  14. List<MediaField>? mediaFields,
  15. Paging<List<TweetData>, TweetMeta>? paging,
})

Returns Tweets composed by a single user, specified by the requested user ID.

By default, the most recent ten Tweets are returned per request. Using pagination, the most recent 3,200 Tweets can be retrieved.

The Tweets returned by this endpoint count towards the Project-level Tweet cap.

The value returned when the paging callback is specified is the first object obtained that started the paging process. The value obtained in the paging process is passed to the paging callback function as a PagingEvent object.

Parameters

  • userId: Unique identifier of the Twitter account (user ID) for whom to return results. User ID can be referenced using the user/lookup endpoint. More information on Twitter IDs is here.

  • maxResults: Specifies the number of Tweets to try and retrieve, up to a maximum of 100 per distinct request. By default, 10 results are returned if this parameter is not supplied. The minimum permitted value is 5. It is possible to receive less than the max_results per request throughout the pagination process.

  • paginationToken: This parameter is used to move forwards or backwards through 'pages' of results, based on the value of the next_token or previous_token in the response. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.

  • startTime: YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The oldest UTC timestamp from which the Tweets will be provided. Timestamp is in second granularity and is inclusive (for example, 12:00:01 includes the first second of the minute). By default, a request will return Tweets from up to 30 days ago if you do not include this parameter.

  • endTime: YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). Used with startTime. The newest, most recent UTC timestamp to which the Tweets will be provided. Timestamp is in second granularity and is exclusive (for example, 12:00:01 excludes the first second of the minute). If used without startTime, Tweets from 30 days before endTime will be returned by default. If not specified, endTime will default to now - 30 seconds.

  • sinceTweetId: Returns results with a Tweet ID greater than (that is, more recent than) the specified 'since' Tweet ID. Only the 3200 most recent Tweets are available. The result will exclude the since_id. If the limit of Tweets has occurred since the sinceTweetId, the sinceTweetId will be forced to the oldest ID available.

  • untilTweetId: Returns results with a Tweet ID less than (that is, older than) the specified 'until' Tweet ID. Only the 3200 most recent Tweets are available. The result will exclude the until_id. If the limit of Tweets has occurred since the untilTweetId, the untilTweetId will be forced to the most recent ID available.

  • excludes: The list of the types of Tweets to exclude from the response. When exclude=retweets is used, the maximum historical Tweets returned is still 3200. When the exclude=replies parameter is used for any value, only the most recent 800 Tweets are available.

  • expansions: Expansions enable you to request additional data objects that relate to the originally returned Tweets. Submit a list of desired expansions in a comma-separated list without spaces. The ID that represents the expanded data object will be included directly in the Tweet data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original Tweet object.

  • tweetFields: This fields parameter enables you to select which specific Tweet fields will deliver in each returned Tweet object. You can also pass expansions to return the specified fields for both the original Tweet and any included referenced Tweets. The requested Tweet fields will display in both the original Tweet data object, as well as in the referenced Tweet expanded data object that will be located in the includes data object.

  • userFields: This fields parameter enables you to select which specific user fields will deliver in each returned Tweet. While the user ID will be located in the original Tweet object, you will find this ID and all additional user fields in the includes data object.

  • placeFields: This fields parameter enables you to select which specific place fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet will only return place fields if the Tweet contains a place and if you’ve also included the expansions=geo.place_id query parameter in your request. While the place ID will be located in the Tweet object, you will find this ID and all additional place fields in the includes data object.

  • pollFields: This fields parameter enables you to select which specific poll fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet will only return poll fields if the Tweet contains a poll and if you've also included the expansions=attachments.poll_ids query parameter in your request. While the poll ID will be located in the Tweet object, you will find this ID and all additional poll fields in the includes data object.

  • mediaFields: This fields parameter enables you to select which specific media fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet will only return media fields if the Tweet contains media and if you've also included the expansions=attachments.media_keys query parameter in your request. While the media ID will be located in the Tweet object, you will find this ID and all additional media fields in the includes data object.

  • paging: If this callback function is specified, paging is performed continuously until certain conditions are met. This paging function is bi-directional, both forward and backward, and allows for safe paging. The response and other metadata obtained when paging is performed is passed to the callback function as PagingEvent object. So you can get the result of paging from PagingEvent object. Also, the direction and continuity of paging can be controlled by returning PaginationControl object in the paging callback function. Please use PaginationControl.forward() to continue paging and move forward, or use PaginationControl.backward() to move backward. And be sure to return PaginationControl.stop() to terminate paging on arbitrary conditions, otherwise paging continues until the next page runs out.

Endpoint Url

Authentication Methods

  • OAuth 2.0 Authorization Code with PKCE
  • OAuth 2.0 App-only
  • OAuth 1.0a

Required Scopes

  • tweet.read
  • users.read

Rate Limits

  • App rate limit (OAuth 2.0 App Access Token): 1500 requests per 15-minute window shared among all users of your app

  • User rate limit (OAuth 2.0 user Access Token): 900 requests per 15-minute window per each authenticated user

  • User rate limit (OAuth 1.0a): 900 requests per 15-minute window per each authenticated user

Reference

Implementation

Future<TwitterResponse<List<TweetData>, TweetMeta>> lookupTweets({
  required String userId,
  int? maxResults,
  String? paginationToken,
  DateTime? startTime,
  DateTime? endTime,
  String? sinceTweetId,
  String? untilTweetId,
  List<ExcludeTweetType>? excludes,
  List<TweetExpansion>? expansions,
  List<TweetField>? tweetFields,
  List<UserField>? userFields,
  List<PlaceField>? placeFields,
  List<PollField>? pollFields,
  List<MediaField>? mediaFields,
  Paging<List<TweetData>, TweetMeta>? paging,
});