The user Tweet timeline and user mention timeline are the Twitter API v2 versions of the v1.1 statuses/user_timeline and v1.1 statuses/user_mentions endpoints. If you are currently using these v1.1 endpoints, you can use our migration materials to start working with this new endpoint.
Learn more about the new Twitter API v2: Early Access.
Introduction to timelines
User Tweet timeline
The user Tweet timeline endpoints provides access to Tweets published by a specific Twitter account. Retrieving a user's Tweets allows you to build experiences such as showcasing a timeline in a user interface, analyzing a user's Tweets to better understand their content, or create engagement workflows with their Tweets programmatically. This endpoint gives you access to a single Twitter account's most recent Tweets, Retweets, replies, and Quote Tweets, similar to what may be seen on a user's profile timeline.
Here is a user timeline for @TwitterDev:
The user Tweet timeline endpoint is a REST endpoint that receives a single path parameter to indicate the desired user (by user ID). The endpoint can return the 3,200 most recent Tweets, Retweets, replies and Quote Tweets posted by the user.
Tweets are delivered in reverse-chronological order, starting with the most recent. Results are paginated up to 100 Tweets per page. Pagination tokens are provided for paging through large sets of Tweets. The Tweet IDs of the newest and the oldest Tweets included in the given page are also provided as metadata, which can also be used for polling timelines for recent Tweets, or for navigating through the timeline similar to the v1.1 user_timeline endpoints. The user Tweet timeline also supports the ability to specify start_time and end_time parameters to receive Tweets that were created within a certain window of time.
The user Tweet timeline endpoint supports fields and expansions parameters, and returns the new JSON data format.
User Tweet timeline supports both OAuth 2.0 Bearer Token authentication, and OAuth 1.0a User Context authentication for authorized requests. You must use OAuth 1.0a User Context when requesting non public metrics, promoted metrics or a protected user's timeline. For these cases, you will need to use the OAuth 1.0a User Context authentication tokens of the user ID that is requested in the path parameter.
The user Tweet timeline endpoint is designed to support two common usage patterns:
"Get a user’s historical Tweets": Requests made to user Tweet timeline in order to receive Tweets authored by the user of interest in chronological order over a specific recent timeframe. The timeframe can be set using the start_time and end_time and paginating through the full results. In some cases, a user’s entire history of Tweets can be retrieved if the user has only authored up to 3,200 Tweets in their account. Tweets included will depend on the public availability and the authentication that is used for the requests.
"Polling for new Tweets": Requests made to user Tweet timeline on a continual basis, to retrieve new Tweets authored by a specific user. The last Tweet ID receieved can be set as a parameter for any new requests since the last Tweet.
User mention timeline
The user mention timeline endpoint allows you to request Tweets mentioning a specific Twitter user, for example, if a Twitter account mentioned @TwitterDev within a Tweet. This will also include replies to Tweets by the user requested. Retrieving a user's mentions allows you to build experiences such as quickly discovering who is replying to a users' Tweets, mentioning or to create engagement workflows with their Tweets programmatically. The endpoint allows you to request to a single user's most recent mentions and replies, similar to what may be seen in a user's notifications for mentions on Twitter.
The user mention timeline is a REST endpoint that receives a single path parameter to indicate the desired user (by user ID). The endpoint can return the 800 most recent mentions for that user.
Tweets are delivered in reverse-chronological order, starting with the most recent. Results are paginated in up to 100 Tweets per page. Pagination tokens are provided for paging through large sets of Tweets. The Tweet IDs of the newest and the oldest Tweets included in the given page are also provided as metadata, which can also be used for polling timelines for recent Tweets, or for navigating through the timeline similar to the v1.1 mentions_timeline endpoint. The endpoint also supports the ability to specify start_time and end_time parameters to receive Tweets that were created within a certain window of time.
User mention timeline supports both OAuth 2.0 Bearer Token authentication, and OAuth 1.0a User Context authentication for authorized requests. You must use OAuth 1.0a User Context when requesting mentions for a protected user. For this case, you will need to use the OAuth 1.0a User Context authentication tokens of the user ID that is requested in the path parameter.
The user mention timeline endpoint supports fields and expansions parameters, and returns the new JSON data format.
Tutorials
