Quickstart

This guide walks you through retrieving Posts from a List timeline. Reference for the X API v2 standard tier covering list tweets.

This guide walks you through retrieving Posts from a List timeline.

Prerequisites

Before you begin, you’ll need:

• A developer account with an approved App
• Your App’s Bearer Token

---

1. Find a List ID

   You can find a List ID in the URL when viewing a List on x.com:

   https://x.com/i/lists/84839422
                         └── This is the List ID
   
2. Request the List timeline

   cURL

   shellscript

   curl "https://api.x.com/2/lists/84839422/tweets?\
   tweet.fields=created_at,public_metrics,author_id&\
   expansions=author_id&\
   user.fields=username,verified&\
   max_results=10" \
     -H "Authorization: Bearer $BEARER_TOKEN"
   

   from xdk import Client
   
   client = Client(bearer_token="YOUR_BEARER_TOKEN")
   
   # Get Posts from a List with pagination
   for page in client.lists.get_tweets(
       "84839422",
       tweet_fields=["created_at", "public_metrics", "author_id"],
       expansions=["author_id"],
       user_fields=["username", "verified"],
       max_results=10
   ):
       for post in page.data:
           print(f"{post.text[:50]}... - Likes: {post.public_metrics.like_count}")
   

   import { Client } from "@xdevplatform/xdk";
   
   const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });
   
   // Get Posts from a List with pagination
   const paginator = client.lists.getTweets("84839422", {
     tweetFields: ["created_at", "public_metrics", "author_id"],
     expansions: ["author_id"],
     userFields: ["username", "verified"],
     maxResults: 10,
   });
   
   for await (const page of paginator) {
     page.data?.forEach((post) => {
       console.log(`${post.text?.slice(0, 50)}... - Likes: ${post.public_metrics?.like_count}`);
     });
   }
   
3. Review the response

   {
     "data": [
       {
         "id": "1458172421115101189",
         "text": "Check out our latest announcement...",
         "author_id": "4172587277",
         "created_at": "2024-01-15T10:30:00.000Z",
         "public_metrics": {
           "retweet_count": 42,
           "reply_count": 5,
           "like_count": 156,
           "quote_count": 3
         },
         "edit_history_tweet_ids": ["1458172421115101189"]
       }
     ],
     "includes": {
       "users": [
         {
           "id": "4172587277",
           "username": "TechNews",
           "verified": true
         }
       ]
     },
     "meta": {
       "result_count": 1,
       "next_token": "7140dibdnow9c7btw3z2vwioavpvutgzrzm9icis4ndix"
     }
   }
   
4. Paginate through results

   The SDKs handle pagination automatically. For cURL, use the next_token from the response to get more Posts:

   curl "https://api.x.com/2/lists/84839422/tweets?\
   max_results=10&\
   pagination_token=7140dibdnow9c7btw3z2vwioavpvutgzrzm9icis4ndix" \
     -H "Authorization: Bearer $BEARER_TOKEN"
   

This endpoint returns up to 800 of the most recent Posts from the List.

---

Next steps

List lookup

Get List details

List members

Get List members

Integration guide

Key concepts and best practices

API Reference

Full endpoint documentation