Skip to main content

Distinct Kotlin fit

Use Kotlin for nullable models, builders, sync and async calls, and JVM workers. Use Java for Java services or C# for .NET. Use the Kotlin SDK for generated JVM models, nullable values, and builders. Use it for sync calls, async calls, typed exceptions, retries, and file upload helpers. It fits Ktor workers, Spring jobs, queue consumers, and scheduled tasks. Search tweets, export followers, monitor tweets, post media, upload files, or send direct messages. Hand tweet, follower, reply, and profile rows to downstream 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.

Kotlin SDK workflows

Tweet replies workflow to CSV, JSON, or XLSX

Use this workflow when a Kotlin 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. The cost is 1 credit per reply extracted or returned.

Error handling

The Kotlin SDK uses the same generated exception hierarchy as the Java SDK.
  • 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 endpoint cursor parameters from the API reference for later requests.

Webhooks & references