Skip to main content

X API & Twitter API Python SDK by Xquik

Framer builds a tweet ticker with Xquik
Watch Framer build a tweet ticker with Xquik, from 6:07. This Python SDK calls the Xquik API.

Use this Twitter API Python SDK by Xquik to read tweets as Pydantic models. Sync & async clients share every method. Public reads need no X developer account.

Xquik is the world's fastest and cheapest X (Twitter) scraper service with the most complete X (Twitter) data. Most other Apify Actors charge before filtering or deduplication. Xquik charges only for delivered, unique, filter-matching results and never pads rows. Xquik is independent and not affiliated with X Corp.

The Xquik REST API read 45 tweets per second on 2026-10-15. That cost $0.15 per 1,000. The fastest of 4 rival Actors read 12.5 per second. The cheapest cost $0.173 per 1,000. Compare each run. Most rival Actors charge before they filter or dedup. Xquik charges only for delivered, unique, filter-matching results.

Install the Twitter API for Python

The SDK requires Python 3.10 or later.

pip install x_twitter_scraper

Search tweets with the Python Twitter API

Set X_TWITTER_SCRAPER_API_KEY, then run this search.

import os
from x_twitter_scraper import XTwitterScraper

client = XTwitterScraper(
    api_key=os.environ.get("X_TWITTER_SCRAPER_API_KEY"),  # Optional. The client reads this variable.
)

response = client.x.tweets.search(
    q="from:elonmusk",
    limit=10,
)
for tweet in response.tweets:
    print(tweet.id, tweet.text)

Next, read the Python SDK guide, API map or REST reference.

Benchmarks & usage

x-twitter-scraper downloads on PyPI X (Twitter) API p99 server read time OpenSSF Best Practices

  • 4,500+ downloads of x-twitter-scraper on PyPI (source)
  • 8.6 s p99 REST server read time over 7 days, failures included (source)
  • This repo meets the OpenSSF Best Practices passing criteria (source)

Checked on 2026-11-13. See each number with its date & source on xquik.com/benchmarks or as JSON.

Move from Tweepy

Tweepy calls the official X API, which needs a developer account & bearer token. This SDK reads public X data with an Xquik API key. This call replaces a Tweepy search_recent_tweets call.

# Tweepy: client.search_recent_tweets(query="from:NASA", max_results=10)
response = client.x.tweets.search(q="from:NASA", limit=10)

Code built on snscrape's TwitterSearchScraper maps to 1 SDK call. The SDK takes the same X search operators & returns typed tweets.

# snscrape: TwitterSearchScraper("from:NASA since:2026-10-01").get_items()
response = client.x.tweets.search(q="from:NASA since:2026-10-01", limit=25)
for tweet in response.tweets:
    print(tweet.id, tweet.text)

Common Twitter & X tasks

Task REST route Usage
Search tweets without the X API GET /x/tweets/search Use keyword or advanced operator queries.
Read an X profile timeline GET /x/users/{id}/tweets Pass the cursor to read the next page.
Scrape Twitter followers GET /x/users/{id}/followers Use an extraction for complete datasets.
Scrape following accounts GET /x/users/{id}/following Use an extraction for complete datasets.
Read a home timeline GET /x/timeline Connect an X account first.
Export large X datasets POST /extractions Poll status, then download results.
Run giveaway draws POST /draws Pick winners from post replies.
Download or upload media /x/media/* Use typed file helpers.
Monitor an account POST /monitors Deliver events through HMAC webhooks.
Post or reply POST /x/tweets Confirm the account and payload.

AI agent workflows with MCP

Use the typed REST SDK in application code. Add https://xquik.com/mcp to MCP clients. Follow the MCP guide for current authentication support.

Async usage

Import AsyncXTwitterScraper and await each API call.

import os
import asyncio
from x_twitter_scraper import AsyncXTwitterScraper

client = AsyncXTwitterScraper(
    api_key=os.environ.get("X_TWITTER_SCRAPER_API_KEY"),  # Optional. The client reads this variable.
)


async def main() -> None:
    response = await client.x.tweets.search(
        q="from:elonmusk",
        limit=10,
    )


asyncio.run(main())

Both clients expose the same resources and methods.

With aiohttp

The async client uses httpx. Install aiohttp for an alternative backend.

pip install x_twitter_scraper[aiohttp]

Select it with http_client=DefaultAioHttpClient().

import os
import asyncio
from x_twitter_scraper import DefaultAioHttpClient
from x_twitter_scraper import AsyncXTwitterScraper


async def main() -> None:
    async with AsyncXTwitterScraper(
        api_key=os.environ.get("X_TWITTER_SCRAPER_API_KEY"),  # Optional. The client reads this variable.
        http_client=DefaultAioHttpClient(),
    ) as client:
        response = await client.x.tweets.search(
            q="from:elonmusk",
            limit=10,
        )


asyncio.run(main())

Using types

Nested request parameters use TypedDicts. Responses use Pydantic models with these helpers.

  • Serialize to JSON with model.to_json().
  • Convert to a dictionary with model.to_dict().

Set python.analysis.typeCheckingMode to basic in VS Code to catch type errors.

File uploads

Pass uploads as bytes, a PathLike, or (filename, contents, media_type).

import httpx
from x_twitter_scraper import XTwitterScraper

client = XTwitterScraper()

image = httpx.get("https://xquik.com/logo.png").content

client.x.media.upload(
    account="@elonmusk",
    file=("logo.png", image, "image/png"),
    idempotency_key="upload-2026-10-15",
)

The async client uses the same interface and reads PathLike content asynchronously.

Handling errors

Connection failures raise an APIConnectionError subclass. Non-2xx responses raise an APIStatusError subclass with status_code and response. Every SDK error inherits from APIError.

import x_twitter_scraper
from x_twitter_scraper import XTwitterScraper

client = XTwitterScraper()

try:
    client.x.tweets.search(
        q="from:elonmusk",
        limit=10,
    )
except x_twitter_scraper.APIConnectionError as e:
    print("Could not reach the server. Check the connection.")
    print(e.__cause__)  # Underlying httpx exception.
except x_twitter_scraper.RateLimitError as e:
    print("Rate limited. Retry later.")
except x_twitter_scraper.APIStatusError as e:
    print("Server returned a non-2xx status.")
    print(e.status_code)
    print(e.response)

The SDK uses these error classes.

Status code Error type
400 BadRequestError
401 AuthenticationError
403 PermissionDeniedError
404 NotFoundError
409 ConflictError
422 UnprocessableEntityError
429 RateLimitError
>=500 InternalServerError
N/A APIConnectionError

Retries

The SDK retries connection errors and HTTP 408, 409, 429, and 5xx responses. It uses exponential backoff and attempts 2 retries by default.

Set max_retries to change or disable retries. Set it on the client, or on 1 request through with_options.

from x_twitter_scraper import XTwitterScraper

client = XTwitterScraper(
    max_retries=0,
)

client.with_options(max_retries=5).x.tweets.search(
    q="from:elonmusk",
    limit=10,
)

Timeouts

Requests time out after 1 minute, and connections after 5 seconds. Set a float or httpx.Timeout through timeout. Set it on the client, or on 1 request through with_options.

import httpx
from x_twitter_scraper import XTwitterScraper

client = XTwitterScraper(
    timeout=20.0,
)

client = XTwitterScraper(
    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
)

client.with_options(timeout=5.0).x.tweets.search(
    q="from:elonmusk",
    limit=10,
)

Timeouts raise APITimeoutError.

Timed-out requests follow the default retry policy.

Advanced

Logging

The SDK uses Python's logging module. Set X_TWITTER_SCRAPER_LOG to info to enable logs.

export X_TWITTER_SCRAPER_LOG=info

Use debug for request and response details.

Distinguishing None, null & missing fields

Both missing and explicit null response fields map to None. Check .model_fields_set to distinguish them.

response = client.x.tweets.search(q="from:NASA", limit=1)
tweet = response.tweets[0]

if tweet.community_note is None:
    if "community_note" not in tweet.model_fields_set:
        print('The response omitted "community_note".')
    else:
        print('The response set "community_note" to null.')

Accessing raw response data

Prefix a method with .with_raw_response. to access the raw response.

from x_twitter_scraper import XTwitterScraper

client = XTwitterScraper()
response = client.x.tweets.with_raw_response.search(
    q="from:elonmusk",
    limit=10,
)
print(response.headers.get("X-My-Header"))

tweet = response.parse()  # Parse the regular x.tweets.search() result.
print(tweet.has_next_page)

Sync methods return APIResponse. Async methods return AsyncAPIResponse with awaitable content readers.

.with_streaming_response

The raw-response interface reads the complete body when you make the request. Use .with_streaming_response and a context manager to read it on demand. Call .read(), .text(), .json(), an iterator, or .parse(). The async client provides async versions of these methods.

with client.x.tweets.with_streaming_response.search(
    q="from:elonmusk",
    limit=10,
) as response:
    print(response.headers.get("X-My-Header"))

    for line in response.iter_lines():
        print(line)

The context manager always closes the response.

Making custom or undocumented requests

The SDK types every documented endpoint, parameter, and response property. Use its lower-level methods for undocumented API features.

Undocumented endpoints

Use client.get, client.post, or another HTTP method for undocumented endpoints. Client options, including retries, apply to these requests.

import httpx

response = client.get(
    "/x/tweets/search",
    cast_to=httpx.Response,
    options={"params": {"q": "from:NASA", "limit": 1}},
)

print(response.headers.get("content-type"))

Undocumented request parameters

Pass extra values through extra_query, extra_body, or extra_headers.

Undocumented response properties

Read an extra field through response.unknown_prop. Use response.model_extra to get every extra field as a dictionary.

Configuring the HTTP client

Replace the httpx client to configure these options.

import httpx
from x_twitter_scraper import XTwitterScraper, DefaultHttpxClient

client = XTwitterScraper(
    # Or use the `X_TWITTER_SCRAPER_BASE_URL` env var
    base_url="http://my.test.server.example.com:8083",
    http_client=DefaultHttpxClient(
        proxy="http://my.test.proxy.example.com",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

Use with_options() to replace it for one request.

from x_twitter_scraper import DefaultHttpxClient

client.with_options(http_client=DefaultHttpxClient(timeout=30.0)).x.tweets.search(
    q="from:NASA",
    limit=10,
)

Managing HTTP resources

Garbage collection closes the client's HTTP connections. Call .close() or use a context manager to close them earlier.

from x_twitter_scraper import XTwitterScraper

with XTwitterScraper() as client:
    # Make requests here.
    ...

# The HTTP client is closed.

Versioning

This package follows SemVer with these exceptions.

  1. Static type changes that preserve runtime behavior.
  2. Changes to undocumented internals that stay public.
  3. Changes unlikely to affect normal use.

Open an issue with questions, bugs or suggestions.

Determining the installed version

If new features are missing, Python may still load an older package. Check the runtime version.

import x_twitter_scraper

print(x_twitter_scraper.__version__)

Questions

Do I need an X developer account?

No. Public reads need only an Xquik API key. Private reads & X account actions need a connected X account.

Is this the official X API?

No. Xquik runs its own REST API. This SDK calls that API, not the official X API.

More Xquik tools

Help & contributing

Xquik is an independent third-party service. Not affiliated with X Corp. "Twitter" and "X" are trademarks of X Corp.

Metadata

Release files for x_twitter_scraper 0.21.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for x_twitter_scraper 0.21.0
File Size Uploaded Provenance Actions
x_twitter_scraper-0.21.0.tar.gz 557.0 kB Without provenance Details for x_twitter_scraper-0.21.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for x_twitter_scraper 0.21.0
File Interpreter ABI Platform Actions
x_twitter_scraper-0.21.0-py3-none-any.whl Python 3 none any Details for x_twitter_scraper-0.21.0-py3-none-any.whl

Total release size: 1.3 MB

Release files / x_twitter_scraper-0.21.0.tar.gz

Download URL x_twitter_scraper-0.21.0.tar.gz
Size 557.0 kB
Tags Source
SHA-256 checksum
How to use checksums
c3bd7570b11c5b904fa7bdf58b5c8ab0b66f00f6f434438d4b38fef193fdb78a
BLAKE2b-256 checksum
How to use checksums
ae48f6686f41e75330868e375cbf01de0f1044ef04e16c09558d2ebb16129563
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / x_twitter_scraper-0.21.0-py3-none-any.whl

Download URL x_twitter_scraper-0.21.0-py3-none-any.whl
Size 770.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e6a15da0932d129f71c3b3856ff77bffffa3d7570801a1479d84b1aa21de8bfa
BLAKE2b-256 checksum
How to use checksums
802c901a3a8379828bb70c78810c728b66c4b7fd94bcfe64befe59431f6da1f0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for x_twitter_scraper 0.21.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.21.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page