Skip to main content

Distinct Python fit

Choose Python for typed synchronous or asynchronous clients. It fits scripts, notebooks, workers, pandas pipelines, and agent tools. Use TypeScript when the runtime and downstream models are Node.js-based. Use the Python SDK for typed sync or async access to Xquik. It works from scripts, notebooks, workers, agent tools, and backend services. Use this page when Python must search tweets. Use it too for tweet exports to CSV, JSON Lines, or XLSX. Python can export followers, post tweets, upload media, or send DMs. It can also monitor tweets. It can load records into pandas, a warehouse, a queue, CRM, or an agent.

Install

Authenticate

Basic example

Search tweets and write durable JSON Lines handoff rows.
Async clients use the same generated method names.

Python SDK workflows

Tweet replies workflow to CSV, JSON, or XLSX

Use this workflow when Python code needs every reply under one tweet. It fits a script, notebook, worker, or agent tool. The replies come as a saved extraction or a JSON Lines handoff. They can also come as a CSV, JSON, or XLSX file export. It uses client.extractions.estimate_cost, run, retrieve, and export_results. Reuse the polling, row pagination, and export structure from the follower workflow. Only the tool type, target field, and output filenames change.
reply_extractor requires target_tweet_id. client.extractions.retrieve returns results, has_more, and next_cursor. The shared pagination loop passes next_cursor back as cursor. Use xquik-replies.jsonl for queue replay or warehouse loads, and xquik-replies.json for app ingestion. Use xquik-replies.csv for CRM import and xquik-replies.xlsx for analyst handoff. client.extractions.export_results supports csv, json, and xlsx for file handoff. The cost is 1 credit per reply extracted or returned.

Cost, limits & retries

Tweet search costs 1 credit per tweet returned. If credits cannot cover a bounded limit request, the API can return fewer tweets. If credits cover no results, it returns 402 insufficient_credits. Xquik rate-limits read calls. 429 responses include Retry-After. The client retries connection errors, 408, 409, 429, and 5xx responses by default. Handle RateLimitError with backoff. Fix 400, 401, 403, 404, or 422 responses before retrying.

Error handling

All SDK exceptions inherit from x_twitter_scraper.APIError.

400 Bad request

Raises BadRequestError.

401 Unauthenticated

Raises AuthenticationError.

403 Permission denied

Raises PermissionDeniedError.

404 Not found

Raises NotFoundError.

422 Unprocessable entity

Raises UnprocessableEntityError.

429 Rate limited

Raises RateLimitError.

5xx server error

Raises InternalServerError.
The client retries connection errors, 408, 409, 429, and 5xx responses by default. Pass max_retries when constructing the client to change retry behavior.

Pagination

List endpoints return page models with has_next_page and cursor fields.

Webhooks & references