#1

Today we are launching new endpoints as part of Early Access to the Twitter API v2 - user Tweet timeline and user mention timeline. With these new endpoints, you can request a Twitter user’s Tweets or mentions using their user ID. These endpoints will replace v1.1 statuses/user_timeline and statuses/mentions_timeline.

How might I use these endpoints?

The v1.1 versions of these timeline endpoints are some of the most used across the Twitter API. These endpoints can be used to study, analyze, or display a user’s Tweets or mentions. Businesses could use the endpoints to build customer support tools or brand analysis tools. Academic researchers might use these endpoints to analyze how a someone’s Tweet sentiment changes over time. The possibilities with these endpoints are abundant, and we look forward to seeing what you build.

What’s new in these v2 endpoints? ?

  • The user Tweet timeline and user mention timeline endpoints support the v2 response format, which allows developers to specify the exact fields that they want returned in a Tweet payload (using expansions and fields). The new format also includes context annotations, which provide contextual information about a Tweet and named entity recognition.
  • These endpoints also allow to programmatically retrieve data on Twitter polls and also support public and private (non-public, organic) metrics to understand Tweet performance. Note, private metrics are available for Tweets within the last 30 days for authenticated users only.
  • The new user mention timeline endpoint now allows you to retrieve the Tweets mentioning a specified user using application-only authentication, which is not possible with the v1.1 endpoint, statuses/mentions_timeline endpoint (user context auth only).
  • The new user Tweet timeline and user mention timeline endpoints support start_time and end_time parameters, that you can use in your requests to bound results to a specified time period. This allows you to easily get historical Tweets and mentions for a user.
  • These endpoints now support pagination tokens to help you obtain all of the results for your request if they are too large to fit in a single response.

Tweet caps and rate limits

With these endpoints, you can request up to 100 Tweets per request. The user Tweet timeline endpoint has a limit of the 3200 most recent Tweets and the user mention timeline endpoint has a limit of the 800 most recent Tweets.

Auth method User Tweet timeline User mention timeline
User auth 900 requests per 15-minute window 180 requests per 15-minute window
App auth 1500 requests per 15-minute window 450 requests per 15-minute window

Note: The user Tweet timeline and user mention timeline endpoints count towards the monthly Tweet cap for Standard Basic access (applied at project-level), which is 500,000 (The other endpoints that this cap applies to in standard basic access are the recent search and filtered stream endpoints). You can view your monthly Tweet cap usage in the developer portal dashboard.

How do I get started?

In order to use the user Tweet timeline and user mention timeline endpoints, you will need to have an approved developer account. You must also have a Project created.

You will need the user ID for a specified Twitter account to use in your request to these endpoints.

Getting the user ID for a user

In order to get the user ID from a username, you can use the new user lookup endpoint v2. Replace the USER_NAME with the username of your choice and XXXX with your own bearer token from your developer portal).

curl --request GET 'https://api.twitter.com/2/users/by/username/USER_NAME --header 'Authorization: Bearer XXXXXX'

You will see the user ID in response as shown below:

{
    "data": {
        "id": "2244994945",
        "name": "Twitter Dev",
        "username": "TwitterDev"
    }
}

Calling the user Tweet timeline endpoint

In order to get the specified user’s Tweets, run the following curl command in your terminal (make sure to replace the USER_ID with the user ID of your choice and XXXX with your own bearer token from your developer portal).

curl --request GET 'https://api.twitter.com/2/users/USER_ID/tweets' --header 'Authorization: Bearer XXXXXX'

Calling the user mentions timeline endpoint

To get mentions of a user, run the following curl command in your terminal (make sure to replace the USER_ID with the user ID of your choice and XXXX with your own bearer token from your developer portal).

curl --request GET 'https://api.twitter.com/2/users/USER_ID/mentions --header 'Authorization: Bearer XXXXXX'

You will see that the JSON response for these requests contains the ID and text for the Tweets by default (example below).

{
    "id": "1334200897081987072",
    "text": "👀 If you are new to the Twitter API v2, check out this step-by-step guide to making your first request https://t.co/4rZqThpSbp"
}

If you want additional fields returned as part of the response (such as user information, or additional Tweet fields such as context annotations, etc.), you will need to specify those fields explicitly in your response. Learn how to do this from the guide on using fields and expansions.

You can also get these Tweets using programming languages of your choice. Check out our sample code in Python, Node (JavaScript), Java and Ruby for the user Tweet timeline and user mention timeline endpoints on our GitHub repository.

Lastly, check out this tutorial that shows how you can explore a user’s Tweets and mentions.

Feedback and Questions

As is the case with all Early Access v2 endpoints, we are listening closely to your feedback to inform what improvements we make on the path towards a complete v2 API. We’d love to hear what you think of these new endpoints. If you have feedback for us, please send it via our feedback page. If you have questions about these endpoints, please ask us via the Twitter API v2 category here in the forums.

6 Likes
#2