Skip to main content
Use the Java X (Twitter) API SDK in Java 8+ applications. It provides generated JVM models, builders, sync calls, async calls, and typed exceptions. It also provides retries and file upload helpers. It fits JVM services, Spring workers, queue consumers, and cron jobs. Search tweets, export followers, monitor tweets, post media, upload files, or send direct messages. Hand tweet, follower, reply, and profile rows to analytics or CRM systems.

Install

Add the Gradle dependency from Maven Central.
Or add the Maven dependency.

Authenticate

Build the client from the environment.
It reads X_TWITTER_SCRAPER_API_KEY, X_TWITTER_SCRAPER_BEARER_TOKEN, and X_TWITTER_SCRAPER_BASE_URL.

Basic example

Search tweets and write durable JSON Lines handoff rows.

Java SDK workflows

Tweet replies workflow to CSV, JSON, or XLSX

Use this workflow when a Java worker needs every reply as a durable file. The parent can be a campaign, support thread, launch post, or incident update. reply_extractor requires targetTweetId. Estimate first, run the job, and poll retrieve. Then export the completed job as CSV, JSON, or XLSX. Reuse the follower export loop above. Change only the required target, tool type, and output names.
Store job.id() before polling. A queue retry uses it to resume the read. After completion, it can repeat the export.
Stream page.results() to Paths.get("xquik-replies.jsonl"). Keep page.nextCursor() as the checkpoint while streaming replies to JSON Lines. Pass it back as cursor on the next page request. The code above builds that request with the ExtractionRetrieveParams builder. Keep the same estimate.allowed() credit branch from the follower export workflow before calling run. Export the completed job with the same helper used above.
Repeat the export with each format to write Paths.get("xquik-replies.json") and Paths.get("xquik-replies.xlsx").
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.

Error handling

The Java SDK throws unchecked exceptions.
  • 400 Bad request. Throws BadRequestException.
  • 401 Unauthorized. Throws UnauthorizedException.
  • 403 Permission denied. Throws PermissionDeniedException.
  • 404 Not found. Throws NotFoundException.
  • 422 Validation error. Throws UnprocessableEntityException.
  • 429 Rate limited. Throws RateLimitException.
  • 5xx server error. Throws InternalServerException.
Connection and I/O failures use XTwitterScraperIoException. All SDK exceptions inherit from XTwitterScraperException.

Pagination

Paginated responses expose generated fields such as hasNextPage. Use the endpoint cursor fields documented in the API reference when requesting more pages.

Webhooks & references