Quickstart

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

PrerequisitesBefore you begin, you’ll need:

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

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

Request the List timeline

cURL

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}`);
  });
}

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"
  }
}

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

​Next steps

List lookup

List members

Integration guide

API Reference

Next steps