X-Timeline Scraper

A Python client to scrape tweets from X (formerly Twitter) timelines using a cURL command.

Introduction

This project provides a Python client to scrape tweets from X (formerly Twitter) timelines using a cURL command. It leverages asynchronous programming for efficient data retrieval and includes features for parsing tweet data.

Table of Contents 🗂

• Installation
• Usage
• Citation
• Contributing
• License

Installation ⚙️

To install the X-Timeline Scraper, you can use pip:

pip install xtimeline

Usage ⌨️

The client polls your Following timeline as your own logged-in X session. It needs two cookies from that session:

1. Log into x.com in your browser.
2. Open DevTools (F12) → Application (Chrome/Edge) or Storage (Firefox) → Cookies → https://x.com.
3. Copy the values of auth_token and ct0.

Treat these like a password: they grant full access to your account. They stay valid until you log out of that browser session; client.last_status becomes 401/403 once they expire.

import asyncio
import os
from xclient import XTimelineClient

async def main():
    async with XTimelineClient.from_cookies(
        os.environ["X_AUTH_TOKEN"], os.environ["X_CT0"]
    ) as xc:
        for t in await xc.fetch_tweets():
            print(t.to_markdown())

asyncio.run(main())

If X rotates the timeline's GraphQL query id before a new release ships, pass the current one (from the HomeLatestTimeline request URL in DevTools → Network) via from_cookies(..., query_id="...").

Alternative: a captured cURL command

Instead of cookies you can pass a full captured request, which also picks up any header or feature flag changes X makes. The capture steps are in curl_example.txt; the examples below use this form.

Fetching tweets once

import asyncio
from xclient import XTimelineClient

async def main():
    async with XTimelineClient("curl.txt") as xc:
        tweets = await xc.fetch_tweets()
        for t in tweets:
            print(t.to_markdown())

asyncio.run(main())

Streaming new tweets

import asyncio
from xclient import XTimelineClient

async def main():
    async with XTimelineClient(
        "curl.txt", persist_last_id_path="state/last_id.txt"
    ) as xc:
        async for t in xc.stream():
            print(t.to_markdown())

asyncio.run(main())

By default, stream() now polls every ~30 seconds with built-in jitter (fuzzy interval) so requests do not follow an identical cadence.

# 30s base with +-20% jitter (default)
async for t in xc.stream():
    process(t)

# Custom base interval and jitter
async for t in xc.stream(interval_s=45.0, jitter_ratio=0.15):
    process(t)

# Disable jitter if you need a fixed cadence
async for t in xc.stream(interval_s=30.0, jitter_ratio=0.0):
    process(t)

Fetch modes

Both fetch_tweets() and stream() accept a mode parameter that controls which tweets are returned:

# Hand all deduplication to your own store
async for t in xc.stream(mode="all"):
    upsert_to_db(t)

# Only new tweets, cursor persisted across restarts
async with XTimelineClient(
    "curl.txt", persist_last_id_path="state/last_id.txt"
) as xc:
    async for t in xc.stream(mode="new_only"):
        process(t)

# New tweets + engagement updates
async for t in xc.stream(mode="with_updates"):
    if t.is_update:
        update_metrics_in_db(t)
    else:
        insert_new_tweet(t)

X gives every edit of a post a new id, so an edited post arrives as a new tweet (is_update=False). Check is_edit to replace the earlier version instead of storing it twice:

async for t in xc.stream(mode="with_updates"):
    if t.is_edit:
        replace_stored_version(t, version_ids=t.edit_tweet_ids)

Tweet fields

Each Tweet object contains:

Citation ✍️

If you use this project in your research, please cite as follows:

@misc{project_name,
  author  = {Stephan Akkerman},
  title   = {X-Timeline Scraper},
  year    = {2025},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/StephanAkkerman/x-timeline-scraper}}
}

Contributing 🛠

Contributions are welcome! If you have a feature request, bug report, or proposal for code refactoring, please feel free to open an issue on GitHub. We appreciate your help in improving this project.

License 📜

This project is licensed under the MIT License. See the LICENSE file for details.