Tutorials / Explore a user’s Tweets and mentions with the X API v2
Explore a user’s Tweets and mentions with the X API v2
Relevant Endpoints
Introduction
The user Tweet timeline and user mention timeline endpoints allow developers to retrieve the public Tweets composed by, or mentioning a user. While the recent search endpoint allows you to only get Tweets published in the last 7 days, the user Tweet timeline and user mention timeline endpoints allow you to retrieve Tweets and mentions that are older than the last 7 days, for an authorized user (using the user ID). Developers can use these endpoints to study topics, entities and sentiment of Tweets from a user’s timeline or mentions. In this tutorial, we will show you how to explore a user’s Tweets and mentions using the user Tweet timeline and user mention timeline endpoints.
Prerequisites
- In order to use the user Tweet timeline and user mention timeline endpoints, you will need to have a valid developer account.
- You will also need a Project created.
- You must have signed up for a developer account, and have activated the new developer portal experience.
- Access is available with active keys and tokens for a developer App that is attached to a Project created in the developer portal.
- A Bearer Token from your App in the X developer portal.
- If you do not have an approved developer account, you can apply for one.
Approved developer account
If you do not have one yet, you can apply for one.
Create a Project and connect an App
In the developer portal, click create a new Project.
![](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/docs/projects.png.twimg.1920.png)
Give it a name, select the appropriate use-case, and provide a Project description. Next, you can either create a new App, or connect an existing App (an App is a container for your API keys that you need in order to make an HTTP request to the X API).
![this image displays adding your app](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/docs/add-your-app.png.twimg.1920.png)
![This image displays naming your app](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/docs/last-step-name-your-app.png.twimg.1920.png)
Once you click complete, you will get your API keys and the bearer token that you can then use to connect to the new endpoints in the X API v2.
![This image displays keys and tokens](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/docs/here-are-your-keys.png.twimg.1920.png)
Click the (+) next to API key, API secret key and Bearer token and copy these values to a safe place on your local machine. You will need these to make the API calls in the next step.
Note: The keys in the screenshot above are hidden, but in your own developer portal, you will be able to see the actual values for the API key, API secret key and Bearer token.
How to get the user ID for a user to use in the user Tweet timeline and user mention timeline endpoints
The user Tweet timeline and user mention timeline endpoints allow you to get Tweets using the user ID. 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 that you obtained above)
curl --request GET 'https://api.x.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"
}
}
Connecting to the user Tweet timeline and user mention timeline endpoints
In order to get the user Tweet timeline for 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 that you obtained above)
curl --request GET 'https://api.x.com/2/users/USER_ID/tweets' --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, additional Tweet fields such as context annotations etc.) then 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.
Exploring the user’s Tweets
Once you know how to get Tweets using the user Tweet timeline and user mention timeline endpoints, you can start to explore their Tweets. For example, if you wanted to identify common named entities present in a user’s mentions, you can do the following:
In the API request, specify that you want the context_annotations object returned in the Tweet responses:
curl --request GET 'https://api.x.com/2/users/USER_ID/mentions?tweet.fields=context_annotations' --header 'Authorization: Bearer XXXXXX'
In the response, you will see if any named entities are present in the mentions. Here is an example:
{
"domain": {
"id": "47",
"name": "Brand",
"description": "Brands and Companies"
},
"entity": {
"id": "10045225402",
"name": "Twitter"
}
}
If you wanted to see which popular entities appear in your mentions, you could keep a count of popular entities by parsing each Tweet in the mentions.
If you wanted to explore the preview image URL for all Tweets in your timeline that contain media, you can do the following:
In the API request, specify that you want the preview_image_url in the tweet.media fields, and the attachments.media_keys expansions
curl --request GET 'https://api.x.com/2/users/2244994945/mentions?max_results=100&media.fields=preview_image_url&expansions=attachments.media_keys' --header 'Authorization: Bearer XXXXXX'
In the response, you will see the preview_image_url in the includes object as shown below:
{
"includes": {
"media": [
{
"media_key": "16_1334657439640121344",
"preview_image_url": "https://pbs.twimg.com/tweet_video_thumb/EoWn3rqU8AAtFWL.jpg",
"type": "animated_gif"
}
]
}
}
Once you have an understanding of how to navigate a user’s Tweets, you can also use other APIs and services to do more with the Tweets. Check out this tutorial that shows you how to analyze the sentiments of your Tweets. Below are some resources to keep handy when using the user Tweet timeline and user mention timeline endpoints.
Resources
- Learn more about the user Tweet timeline and the user mention timeline endpoints.
- Check out the API reference for the user Tweet timeline endpoint to learn more about what’s available.
- Check out the API reference for the user mention timeline endpoint to learn more about what’s available.
- Get inspired by reading our other tutorials.
Ready to build your solution?