X Twitter Scraper Kotlin

https://github.com/xquik-dev/x-twitter-scraper-kotlin
Admin
X Twitter Scraper Kotlin is a Kotlin SDK that provides convenient access to the X Twitter Scraper...
Tokens:36,102
Snippets:449
Trust Score:5.5
License:Apache-2.0
Update:2 months ago
Show doc for...
Tokens:
Raw
### Complete Monitor and Webhook Workflow

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/monitors.md

End-to-end example demonstrating webhook creation, monitor setup, event polling, and resource cleanup.

```kotlin
// 1. Create a webhook
val webhookParams = WebhookCreateParams.builder()
    .url("https://example.com/webhooks/monitor-events")
    .events(listOf("tweet_created", "retweet", "follow"))
    .build()
val webhook = client.webhooks().create(webhookParams)

// 2. Create account monitor
val monitorParams = MonitorCreateParams.builder()
    .monitorType("account")
    .accountId("123456789")
    .webhookId(webhook.webhookId())
    .build()
val monitor = client.monitors().create(monitorParams)

// 3. Poll for events (or handle via webhook)
val eventParams = EventListParams.builder()
    .monitorId(monitor.monitorId())
    .limit(100L)
    .build()
val events = client.events().list(eventParams)

for (event in events.events()) {
    println("${event.eventType()} at ${event.createdAt()}")
}

// 4. Clean up
client.monitors().delete(monitor.monitorId())
client.webhooks().delete(webhook.webhookId())
```

--------------------------------

### Create Account and Keyword Monitors

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/monitors.md

Examples for initializing account-based and keyword-based monitors.

```kotlin
val params = MonitorCreateParams.builder()
    .monitorType("account")
    .accountId("123456789")
    .webhookId("webhook-id")
    .build()

val response = client.monitors().create(params)
println("Created monitor: ${response.monitorId()}")
```

```kotlin
val params = MonitorCreateParams.builder()
    .monitorType("keyword")
    .keyword("bitcoin")
    .webhookId("webhook-id")
    .build()

val response = client.monitors().create(params)
```

--------------------------------

### Full Client Configuration

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/configuration.md

Comprehensive example demonstrating authentication, timeouts, retries, logging, and proxy settings.

```kotlin
import com.x_twitter_scraper.api.client.okhttp.XTwitterScraperOkHttpClient
import com.x_twitter_scraper.api.core.LogLevel
import java.time.Duration

val client = XTwitterScraperOkHttpClient.builder()
    // Authentication
    .apiKey("your-api-key")
    
    // Or from environment
    .fromEnv()
    
    // Timeouts
    .timeout(Duration.ofSeconds(30))
    
    // Retries
    .maxRetries(4)
    
    // Logging
    .logLevel(LogLevel.INFO)
    
    // Headers
    .putHeader("X-Custom-Header", "value")
    
    // Proxy (optional)
    .proxy(proxy)
    
    // Build
    .build()
```

--------------------------------

### Handle NotFoundException

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/errors.md

Example of catching a 404 Not Found error.

```kotlin
try {
    client.x().tweets().retrieve("9999999999999999")
} catch (e: NotFoundException) {
    println("Tweet not found")
}
```

--------------------------------

### GET /monitors

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/endpoints.md

Retrieves a list of all configured monitors.

```APIDOC
## GET /monitors

### Description
Lists all monitors currently configured in the system.

### Method
GET

### Endpoint
/monitors
```

--------------------------------

### Set Custom Headers

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/configuration.md

Example of adding custom headers to the client builder.

```kotlin
val client = XTwitterScraperOkHttpClient.builder()
    .putHeader("X-Custom-Header", "value")
    .putHeader("X-Request-ID", UUID.randomUUID().toString())
    .build()
```

--------------------------------

### List Monitors Method Signature and Usage

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/monitors.md

Signature and example for listing all monitors associated with the authenticated account.

```kotlin
fun list(
    params: MonitorListParams = MonitorListParams.none(),
    requestOptions: RequestOptions = RequestOptions.none()
): MonitorListResponse
```

```kotlin
val response = client.monitors().list()
for (monitor in response.monitors()) {
    println("Monitor: ${monitor.monitorId()}")
}
```

--------------------------------

### Install x-twitter-scraper-kotlin

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/README.md

Add the library dependency to your project build configuration.

```kotlin
implementation("com.xquik.api:x-twitter-scraper-kotlin:0.9.0")
```

```xml
<dependency>
  <groupId>com.xquik.api</groupId>
  <artifactId>x-twitter-scraper-kotlin</artifactId>
  <version>0.9.0</version>
</dependency>
```

--------------------------------

### GET /x/accounts

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/endpoints.md

Lists all connected accounts.

```APIDOC
## GET /x/accounts

### Description
Lists all connected accounts.

### Method
GET

### Endpoint
/x/accounts
```

--------------------------------

### Handle RateLimitException

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/errors.md

Example of catching a RateLimitException and accessing reset headers.

```kotlin
try {
    for (i in 1..1000) {
        client.x().tweets().search(params)
    }
} catch (e: RateLimitException) {
    println("Rate limited. Reset at: ${e.headers().get("X-RateLimit-Reset")}")
    // Implement exponential backoff
}
```

--------------------------------

### GET /webhooks

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/endpoints.md

Lists all registered webhooks.

```APIDOC
## GET /webhooks

### Description
Retrieves a list of all registered webhooks.

### Method
GET

### Endpoint
/webhooks
```

--------------------------------

### ExtractionService.create(params)

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/additional-services.md

Starts a new bulk data extraction job.

```APIDOC
## create(params)

### Description
Initiates a new bulk data export job for various data types like tweets or followers.

### Method
SDK Method

### Parameters
- **params** (ExtractionCreateParams) - Required - Configuration for the extraction job, including export type and target IDs.
```

--------------------------------

### Handle XTwitterScraperIoException

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/errors.md

Example of catching network-related I/O exceptions.

```kotlin
try {
    client.x().tweets().search(params)
} catch (e: XTwitterScraperIoException) {
    println("Network error: ${e.cause}")
}
```

--------------------------------

### Handle UnauthorizedException

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/errors.md

Example of catching a 401 Unauthorized error due to invalid credentials.

```kotlin
try {
    val client = XTwitterScraperOkHttpClient.builder()
        .apiKey("")  // Invalid/missing key
        .build()
    client.x().tweets().search(params)
} catch (e: UnauthorizedException) {
    println("Authentication failed: ${e.message}")
}
```

--------------------------------

### GET /account

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/endpoints.md

Retrieves information about the authenticated account.

```APIDOC
## GET /account

### Description
Retrieves information about the authenticated account.

### Method
GET

### Endpoint
/account
```

--------------------------------

### Handle PermissionDeniedException

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/errors.md

Example of catching a 403 Permission Denied error.

```kotlin
try {
    client.x().tweets().delete("someone_elses_tweet_id", params)
} catch (e: PermissionDeniedException) {
    println("You don't have permission to delete this tweet")
}
```

--------------------------------

### Configure compatibility test environment

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/CONTRIBUTING.md

Set the environment variable to point to the JDK 25 installation for compatibility testing.

```sh
export SHRINKER_JAVA_HOME="/path/to/jdk-25"
```

--------------------------------

### Initialize TweetSearchParams with builder

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/types.md

Example of constructing a search parameter object using the builder pattern.

```kotlin
val params = TweetSearchParams.builder()
    .q("from:elonmusk")
    .limit(100L)
    .minFaves(1000L)
    .mode(TweetSearchParams.Mode.LATEST)
    .build()
```

--------------------------------

### Get Multiple Tweets Response Schema

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/endpoints.md

JSON schema for the response returned by the GET /x/tweets endpoint.

```json
{
  "has_next_page": false,
  "next_cursor": null,
  "tweets": [ ... ]
}
```

--------------------------------

### Get Tweet Response Schema

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/endpoints.md

JSON schema for the response returned by the GET /x/tweets/{id} endpoint.

```json
{
  "id": "string",
  "text": "string",
  "author": { ... },
  "created_at": "string",
  "favorite_count": 100,
  "retweet_count": 50,
  "reply_count": 10,
  "quote_count": 5,
  "view_count": 1000,
  "media": [ ... ],
  "urls": [ ... ]
}
```

--------------------------------

### Handle BadRequestException

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/errors.md

Example of catching a 400 Bad Request error caused by invalid parameters.

```kotlin
try {
    val params = TweetSearchParams.builder()
        .q("")  // Empty query
        .build()
    client.x().tweets().search(params)
} catch (e: BadRequestException) {
    println("Invalid request: ${e.message}")
}
```

--------------------------------

### Get Tweet Favoriters Response Schema

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/endpoints.md

JSON schema for the response returned by the GET /x/tweets/{id}/favoriters endpoint.

```json
{
  "has_next_page": true,
  "next_cursor": "string",
  "users": [ ... ]
}
```

--------------------------------

### Initialize Client from Environment Variables

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/client.md

Creates a client instance using credentials and settings defined in environment variables.

```kotlin
import com.x_twitter_scraper.api.client.okhttp.XTwitterScraperOkHttpClient

val client: XTwitterScraperClient = XTwitterScraperOkHttpClient.fromEnv()
```

--------------------------------

### GET /extractions

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/endpoints.md

Lists all extraction jobs.

```APIDOC
## GET /extractions

### Description
Retrieves a list of all extraction jobs.

### Method
GET

### Endpoint
/extractions
```

--------------------------------

### Accessing Client Services in Kotlin

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/client.md

Demonstrates the entry points for various service modules available through the client instance.

```kotlin
// Core X/Twitter data and actions
client.x()                    // Tweet search, user profiles, timelines
client.x().tweets()          // Tweet operations
client.x().users()           // User profiles and relationships
client.x().followers()       // Follower analysis
client.x().dm()              // Direct messages
client.x().media()           // Media upload
client.x().profile()         // Profile management
client.x().communities()     // Community operations
client.x().accounts()        // Connected account management
client.x().bookmarks()       // Bookmarks
client.x().lists()           // X Lists

// Account management
client.account()             // Account info and settings

// Composition and AI
client.compose()             // AI tweet composition
client.drafts()              // Draft management
client.styles()              // Writing styles
client.radar()               // Radar analysis

// Billing and subscriptions
client.subscribe()           // Subscription management
client.credits()             // Credit information

// Monitoring and events
client.monitors()            // Account/keyword monitoring
client.events()              // Activity events

// Data extraction and webhooks
client.extractions()         // Bulk data extraction
client.webhooks()            // Webhook management
client.draws()               // Giveaway draw management

// Trends and support
client.trends()              // Trending topics by region
client.support()             // Support tickets and attachments

// Guest wallets
client.guestWallets()        // Accountless prepaid access
```

--------------------------------

### Initialize Client from Environment Variables

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/configuration.md

Demonstrates the priority order where System Properties override Environment Variables.

```kotlin
// If BOTH are set:
// System property: -Dxtwitterscraper.apiKey=sys_key
// Environment variable: X_TWITTER_SCRAPER_API_KEY=env_key
// Result: Uses sys_key

val client = XTwitterScraperOkHttpClient.fromEnv()
```

--------------------------------

### Load Configuration from Environment

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/configuration.md

Initialize the client using environment variables or combine environment settings with builder overrides.

```kotlin
val client = XTwitterScraperOkHttpClient.fromEnv()
```

```kotlin
val client = XTwitterScraperOkHttpClient.builder()
    .fromEnv()
    .maxRetries(5)  // Override specific settings
    .build()
```

--------------------------------

### Initialize Async Client

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/async-usage.md

Create an asynchronous client instance either from an existing sync client or directly from environment variables.

```kotlin
val client = XTwitterScraperOkHttpClient.fromEnv()
val asyncClient = client.async()  // Shares resources with sync client
```

```kotlin
val asyncClient = XTwitterScraperOkHttpClientAsync.fromEnv()
```

--------------------------------

### retrieveMentions

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/users.md

Get tweets mentioning a user.

```APIDOC
## retrieveMentions(id: String, params: UserRetrieveMentionsParams, requestOptions: RequestOptions)

### Description
Get tweets mentioning a user.

### Parameters
- **id** (String) - Required - User ID
- **params** (UserRetrieveMentionsParams) - Optional - Pagination options
- **requestOptions** (RequestOptions) - Optional - Request-level overrides

### Return Type
PaginatedTweets
```

--------------------------------

### retrieveLikes

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/users.md

Get tweets liked by a user.

```APIDOC
## retrieveLikes(id: String, params: UserRetrieveLikesParams, requestOptions: RequestOptions)

### Description
Get tweets liked by a user.

### Parameters
- **id** (String) - Required - User ID
- **params** (UserRetrieveLikesParams) - Optional - Pagination options
- **requestOptions** (RequestOptions) - Optional - Request-level overrides

### Return Type
PaginatedTweets
```

--------------------------------

### retrieveVerifiedFollowers

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/users.md

Get verified followers of a user.

```APIDOC
## retrieveVerifiedFollowers(id: String, params: UserRetrieveVerifiedFollowersParams, requestOptions: RequestOptions)

### Description
Get verified followers of a user.

### Parameters
- **id** (String) - Required - User ID
- **params** (UserRetrieveVerifiedFollowersParams) - Optional - Pagination options
- **requestOptions** (RequestOptions) - Optional - Request-level overrides

### Return Type
UserRetrieveVerifiedFollowersResponse
```

--------------------------------

### Combining Sync and Async Clients in Kotlin

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/async-usage.md

Demonstrates how to initialize a client and perform both blocking and non-blocking operations within the same application.

```kotlin
val client = XTwitterScraperOkHttpClient.fromEnv()

// Blocking context
val syncTweets = client.x().tweets().search(params)

// Async context
runBlocking {
    val asyncTweets = client.async().x().tweets().search(params)
    println("Got ${asyncTweets.tweets().size} tweets")
}
```

--------------------------------

### Initialize Client with Direct Credentials

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/client.md

Configures a client instance manually using the builder pattern for specific API keys, base URLs, and timeouts.

```kotlin
val client: XTwitterScraperClient = XTwitterScraperOkHttpClient.builder()
    .apiKey("your-api-key")
    .baseUrl("https://xquik.com/api/v1")
    .maxRetries(4)
    .timeout(Duration.ofSeconds(30))
    .build()
```

--------------------------------

### Initialize and Use XTwitterScraperClient

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/README.md

Demonstrates client initialization using environment variables and a basic synchronous search operation.

```kotlin
val client = XTwitterScraperOkHttpClient.fromEnv()  // Uses env vars for auth
val tweets = client.x().tweets().search(params)
client.close()
```

--------------------------------

### retrieveMedia

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/users.md

Get media tweets posted by a user.

```APIDOC
## retrieveMedia(id: String, params: UserRetrieveMediaParams, requestOptions: RequestOptions)

### Description
Get media tweets posted by a user.

### Parameters
- **id** (String) - Required - User ID
- **params** (UserRetrieveMediaParams) - Optional - Pagination options
- **requestOptions** (RequestOptions) - Optional - Request-level overrides

### Return Type
PaginatedTweets
```

--------------------------------

### AccountService.create

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/account-and-profile.md

Connects a new X account to the service.

```APIDOC
## AccountService.create(params: AccountCreateParams, requestOptions: RequestOptions)

### Description
Connect a new X account.

### Parameters
- **params** (AccountCreateParams) - Required - Contains accountId, authToken, and optional authTokenSecret.
- **requestOptions** (RequestOptions) - Optional - Request-level overrides.
```

--------------------------------

### GET /x/users/search

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/endpoints.md

Searches for users based on a query string.

```APIDOC
## GET /x/users/search

### Description
Searches for users based on a query string.

### Method
GET

### Endpoint
/x/users/search

### Parameters
#### Query Parameters
- **q** (String) - Required - Search query
- **limit** (Number) - Optional - Result limit
- **cursor** (String) - Optional - Pagination cursor
```

--------------------------------

### Perform Complete Account Management in Kotlin

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/account-and-profile.md

Demonstrates retrieving account info, updating profile details, and listing or retrieving connected accounts.

```kotlin
// 1. Get current account info
val account = client.account().retrieve()
println("Current account: ${account.username()}")

// 2. Update account profile
val updateParams = ProfileUpdateParams.builder()
    .name("New Name")
    .description("Updated bio")
    .build()
client.x().profile().update(updateParams)

// 3. List connected accounts
val connectedAccounts = client.x().accounts().list()
for (connected in connectedAccounts.accounts()) {
    println("Connected: ${connected.username()}")
}

// 4. Get specific connected account details
val connectedDetail = client.x().accounts()
    .retrieve("connected-account-id")
```

--------------------------------

### retrieveReplies

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/users.md

Get tweets authored by the user including replies.

```APIDOC
## retrieveReplies(id: String, params: UserRetrieveRepliesParams, requestOptions: RequestOptions)

### Description
Get tweets authored by the user including replies. Omit mode for automatic maximum coverage. Excludes context from other authors.

### Parameters
- **id** (String) - Required - User ID
- **params** (UserRetrieveRepliesParams) - Optional - Pagination options
- **requestOptions** (RequestOptions) - Optional - Request-level overrides

### Return Type
PaginatedTweets
```

--------------------------------

### Initialize XTwitterScraperClient

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/README.md

Create a client instance using environment variables or direct credential configuration.

```kotlin
import com.x_twitter_scraper.api.client.XTwitterScraperClient
import com.x_twitter_scraper.api.client.okhttp.XTwitterScraperOkHttpClient

val client: XTwitterScraperClient = XTwitterScraperOkHttpClient.fromEnv()
```

```kotlin
val client: XTwitterScraperClient = XTwitterScraperOkHttpClient.builder()
    .apiKey("your-api-key")
    .build()
```

--------------------------------

### Initialize Async Client

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/configuration.md

Creates an asynchronous client that shares the connection pool with the synchronous client.

```kotlin
val client = XTwitterScraperOkHttpClient.fromEnv()
val asyncClient = client.async()  // Shares connection pool

// Use in coroutine scope
val tweets = asyncClient.x().tweets().search(params)
```

--------------------------------

### GET /extractions/{id}

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/endpoints.md

Retrieves the status of a specific extraction job.

```APIDOC
## GET /extractions/{id}

### Description
Checks the status of an extraction job.

### Method
GET

### Endpoint
/extractions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the extraction
```

--------------------------------

### Configure HTTP Client Settings

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/configuration.md

Advanced configuration for thread pools, proxies, and SSL/TLS settings.

```kotlin
builder.dispatcherExecutorService(ExecutorService?)
                                         // Thread pool for requests
                                         // Default: OkHttp default

builder.proxy(Proxy?)                    // HTTP proxy
builder.proxyAuthenticator(ProxyAuthenticator?)
                                         // Proxy authentication

builder.maxIdleConnections(Int?)         // Max idle connections
builder.keepAliveDuration(Duration?)     // Keep-alive timeout

builder.sslSocketFactory(SSLSocketFactory?)
                                         // SSL socket factory
builder.trustManager(X509TrustManager?)  // Certificate trust manager
builder.hostnameVerifier(HostnameVerifier?)  // Hostname verification
```

```kotlin
import java.net.Proxy
import java.net.InetSocketAddress

val proxy = Proxy(
    Proxy.Type.HTTP,
    InetSocketAddress("proxy.example.com", 8080)
)

val client = XTwitterScraperOkHttpClient.builder()
    .proxy(proxy)
    .proxyAuthenticator { request ->
        request.header("Proxy-Authorization", "Basic ...")
    }
    .build()
```

--------------------------------

### GET /events

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/endpoints.md

Retrieves a list of events, optionally filtered by monitor.

```APIDOC
## GET /events

### Description
Fetches events generated by monitors.

### Method
GET

### Endpoint
/events

### Parameters
#### Query Parameters
- **monitor_id** (string) - Optional - Filter by monitor ID
- **limit** (number) - Optional - Results per page
- **cursor** (string) - Optional - Pagination cursor
```

--------------------------------

### GET /x/tweets/{id}

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/endpoints.md

Retrieve the details of a specific tweet by its ID.

```APIDOC
## GET /x/tweets/{id}

### Description
Retrieve the details of a specific tweet by its ID.

### Method
GET

### Endpoint
/x/tweets/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Tweet ID
```

--------------------------------

### Configure Authentication

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/README.md

Set the API key or bearer token via environment variables.

```bash
export X_TWITTER_SCRAPER_API_KEY="your-api-key"
```

--------------------------------

### retrieveFollowersYouKnow

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/users.md

Get mutual followers between the authenticated user and a target user.

```APIDOC
## retrieveFollowersYouKnow(id: String, params: UserRetrieveFollowersYouKnowParams, requestOptions: RequestOptions)

### Description
Get mutual followers between the authenticated user and a target user.

### Parameters
- **id** (String) - Required - User ID
- **params** (UserRetrieveFollowersYouKnowParams) - Optional - Pagination options
- **requestOptions** (RequestOptions) - Optional - Request-level overrides

### Return Type
PaginatedUsers
```

--------------------------------

### Configure Headers and Query Parameters

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/configuration.md

Methods available on the builder for managing HTTP headers and query parameters.

```kotlin
builder.headers(Headers)                 // Set all headers
builder.headers(Map<String, Iterable<String>>)
                                         // Set headers as map

builder.putHeader(String name, String value)
                                         // Add single header

builder.putHeaders(String name, Iterable<String> values)
                                         // Add header with multiple values

builder.putAllHeaders(Headers)           // Add multiple headers
builder.putAllHeaders(Map<String, Iterable<String>>)

builder.replaceHeaders(String name, String value)
                                         // Replace header

builder.removeHeaders(String name)       // Remove header

builder.queryParams(QueryParams)         // Set all query params
builder.queryParams(Map<String, Iterable<String>>)

builder.putQueryParam(String key, String value)
builder.putQueryParams(String key, Iterable<String> values)
builder.putAllQueryParams(QueryParams)
builder.replaceQueryParams(String key, String value)
builder.removeQueryParams(String key)
```

--------------------------------

### Retrieve Subscription Details in Kotlin

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/additional-services.md

Fetches the current subscription status and prints plan, credit, and expiration information.

```kotlin
val subscription = client.subscribe().retrieve()
println("Plan: ${subscription.plan()}")
println("Credits: ${subscription.credits()}")
println("Expires: ${subscription.expiresAt()}")
```

--------------------------------

### Manage Client Lifecycle

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/configuration.md

Recommended pattern for reusing a single client instance and closing it upon application termination.

```kotlin
val client = XTwitterScraperOkHttpClient.fromEnv()

// Reuse for all API calls
val tweets = client.x().tweets().search(params)
val users = client.x().users().retrieve(userId)

// Close when application terminates
client.close()
```

--------------------------------

### Implement Builder Pattern

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/types.md

Demonstrates constructing complex objects using the builder pattern.

```kotlin
val params = TweetSearchParams.builder()
    .q("bitcoin")
    .limit(50L)
    .minFaves(100L)
    .build()

// Access individual fields
val query = params.q()
val limit = params.limit()
```

--------------------------------

### Execute verification gates

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/CONTRIBUTING.md

Run the full suite of linting, testing, coverage, and security audit scripts before submitting changes.

```sh
./scripts/lint
./scripts/test
./scripts/coverage
OSV_SCANNER_BIN=/path/to/osv-scanner ./scripts/audit
reuse lint
./scripts/check-reproducible
```

--------------------------------

### GET /x/users

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/endpoints.md

Retrieves information for multiple users based on a list of IDs.

```APIDOC
## GET /x/users

### Description
Retrieves information for multiple users based on a list of IDs.

### Method
GET

### Endpoint
/x/users

### Parameters
#### Query Parameters
- **ids** (String) - Required - Comma-separated list of user IDs.
```

--------------------------------

### GET /x/users/{id}

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/endpoints.md

Retrieves the profile information for a specific user by their ID.

```APIDOC
## GET /x/users/{id}

### Description
Retrieves the profile information for a specific user by their ID.

### Method
GET

### Endpoint
/x/users/{id}

### Parameters
#### Path Parameters
- **id** (String) - Required - The unique identifier of the user.

### Response
#### Success Response (200)
- **id** (string) - User ID
- **username** (string) - Username
- **name** (string) - Display name
- **description** (string) - User bio
- **verified** (boolean) - Verification status
- **followers_count** (number) - Count of followers
- **following_count** (number) - Count of following
- **tweets_count** (number) - Count of tweets
- **created_at** (string) - Account creation timestamp
- **profile_image_url** (string) - URL to profile image
- **url** (string) - User website URL
```

--------------------------------

### create(params: MonitorCreateParams, requestOptions: RequestOptions)

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/monitors.md

Creates a new monitor for an account or keyword. Users can specify the monitor type, target account ID or keyword, and an optional webhook ID for event delivery.

```APIDOC
## create(params: MonitorCreateParams, requestOptions: RequestOptions)

### Description
Creates a new monitor for an account or keyword. This method allows tracking activity for specific users or keywords with 1-second check intervals.

### Signature
`fun create(params: MonitorCreateParams, requestOptions: RequestOptions = RequestOptions.none()): MonitorCreateResponse`

### Parameters
- **params** (MonitorCreateParams) - Required - Monitor configuration object.
- **requestOptions** (RequestOptions) - Optional - Request-level overrides.

### MonitorCreateParams Fields
- **monitorType** (String) - Required - "account" or "keyword".
- **accountId** (String) - Conditional - User ID to monitor (required for account monitors).
- **keyword** (String) - Conditional - Keyword or phrase to monitor (required for keyword monitors).
- **webhookId** (String) - Optional - Webhook endpoint ID for events.

### Return Type
`MonitorCreateResponse`
```

--------------------------------

### GET /x/tweets

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/endpoints.md

Retrieve multiple tweets by providing a list of comma-separated IDs.

```APIDOC
## GET /x/tweets

### Description
Retrieve multiple tweets by providing a list of comma-separated IDs.

### Method
GET

### Endpoint
/x/tweets

### Parameters
#### Query Parameters
- **ids** (string) - Required - Comma-separated tweet IDs
```

--------------------------------

### POST /monitors

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/endpoints.md

Creates a new monitor for either an account or a keyword.

```APIDOC
## POST /monitors

### Description
Creates a new monitor for tracking Twitter activity.

### Method
POST

### Endpoint
/monitors

### Request Body
- **monitor_type** (string) - Required - Type of monitor (account or keyword)
- **account_id** (string) - Optional - ID of the account to monitor
- **keyword** (string) - Optional - Keyword to monitor
- **webhook_id** (string) - Optional - ID of the associated webhook
```

--------------------------------

### Handle XTwitterScraperInvalidDataException

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/errors.md

Example of catching data validation exceptions during response processing.

```kotlin
try {
    val response = client.x().tweets().retrieve("123")
    response.text()  // May throw if malformed
} catch (e: XTwitterScraperInvalidDataException) {
    println("Invalid response data: ${e.message}")
}
```

--------------------------------

### List Webhooks in Kotlin

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/monitors.md

Retrieves all configured webhooks for the authenticated account.

```kotlin
fun list(
    requestOptions: RequestOptions = RequestOptions.none()
): WebhookListResponse
```

--------------------------------

### Handle UnprocessableEntityException

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/errors.md

Example of catching an UnprocessableEntityException when submitting invalid tweet parameters.

```kotlin
try {
    val params = TweetCreateParams.builder()
        .text("x".repeat(300))  // Too long
        .build()
    client.x().tweets().create(params)
} catch (e: UnprocessableEntityException) {
    println("Invalid tweet: ${e.message}")
}
```

--------------------------------

### Configure API Key Authentication

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/configuration.md

Use the builder pattern to set the API key directly. This is the recommended authentication method.

```kotlin
val client = XTwitterScraperOkHttpClient.builder()
    .apiKey("your-api-key")
    .build()
```

--------------------------------

### Verify Maven Signatures

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/README.md

Download and verify the OpenPGP signature for the Kotlin artifact.

```sh
artifact="x-twitter-scraper-kotlin-0.5.2.jar"
base="https://repo.maven.apache.org/maven2/com/xquik/api/x-twitter-scraper-kotlin/0.5.2"
curl --fail --location --remote-name "$base/$artifact"
curl --fail --location --remote-name "$base/$artifact.asc"
gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys 0xD2037E4157E62A59
gpg --verify "$artifact.asc" "$artifact"
```

--------------------------------

### Create Connected Account

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/account-and-profile.md

Connects a new X account using the required account ID and authentication token.

```kotlin
fun create(
    params: AccountCreateParams,
    requestOptions: RequestOptions = RequestOptions.none()
): AccountCreateResponse
```

--------------------------------

### GET /x/tweets/{id}/favoriters

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/endpoints.md

Retrieve a list of users who have favorited a specific tweet.

```APIDOC
## GET /x/tweets/{id}/favoriters

### Description
Retrieve a list of users who have favorited a specific tweet.

### Method
GET

### Endpoint
/x/tweets/{id}/favoriters

### Parameters
#### Path Parameters
- **id** (string) - Required - Tweet ID

#### Query Parameters
- **limit** (number) - Optional - Results per page (default 20)
- **cursor** (string) - Optional - Pagination cursor
```

--------------------------------

### Get quote tweets in Kotlin

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/tweets.md

Retrieves tweets that quote the specified tweet ID.

```kotlin
fun getQuotes(
    id: String,
    params: TweetGetQuotesParams = TweetGetQuotesParams.none(),
    requestOptions: RequestOptions = RequestOptions.none()
): PaginatedTweets
```

--------------------------------

### withOptions(modifier)

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/client.md

Returns a new client instance with modified options, leaving the original client unchanged.

```APIDOC
## withOptions(modifier)

### Description
Returns a new client instance with modified options. The original client remains unchanged.

### Parameters
- **modifier** ((ClientOptions.Builder) -> Unit) - Required - Configuration lambda to modify client options.

### Returns
- **XTwitterScraperClient** - A new client instance with the applied options.
```

--------------------------------

### Get tweet retweeters in Kotlin

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/tweets.md

Retrieves a list of users who have retweeted a specific tweet.

```kotlin
fun getRetweeters(
    id: String,
    params: TweetGetRetweetersParams = TweetGetRetweetersParams.none(),
    requestOptions: RequestOptions = RequestOptions.none()
): PaginatedUsers
```

--------------------------------

### XTwitterScraperClient Initialization

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/client.md

Methods for instantiating the XTwitterScraperClient using either environment variables or a builder configuration.

```APIDOC
## XTwitterScraperClient Initialization

### Description
The XTwitterScraperClient is the main entry point for the Xquik API. It can be initialized via environment variables or a builder for fine-grained control.

### Initialization Methods
- **fromEnv()**: Creates a client by reading `X_TWITTER_SCRAPER_API_KEY`, `X_TWITTER_SCRAPER_BEARER_TOKEN`, and `X_TWITTER_SCRAPER_BASE_URL` from environment variables.
- **builder()**: Provides a fluent interface to configure authentication, timeouts, retries, and network settings.

### Builder Configuration Options
- **apiKey(String?)**: Sets the API key for authentication.
- **bearerToken(String?)**: Sets the OAuth 2.1 bearer token.
- **baseUrl(String?)**: Sets the base API endpoint URL.
- **timeout(Duration)**: Sets the request timeout (default 60s).
- **maxRetries(Int)**: Sets the maximum retry attempts for eligible failures (default 2).
- **logLevel(LogLevel)**: Sets the logging level.
- **jsonMapper(JsonMapper)**: Configures a custom Jackson mapper.
- **proxy(Proxy?)**: Configures an HTTP proxy.

### Example
```kotlin
val client: XTwitterScraperClient = XTwitterScraperOkHttpClient.builder()
    .apiKey("your-api-key")
    .baseUrl("https://xquik.com/api/v1")
    .maxRetries(4)
    .timeout(Duration.ofSeconds(30))
    .build()
```
```

--------------------------------

### list(params: TweetListParams, requestOptions: RequestOptions)

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/tweets.md

Get multiple tweets by IDs in a single request.

```APIDOC
## list(params: TweetListParams, requestOptions: RequestOptions)

### Description
Get multiple tweets by IDs in a single request.

### Parameters
- **params** (TweetListParams) - Required - List of tweet IDs to retrieve
- **requestOptions** (RequestOptions) - Optional - Request-level overrides

### Return Type
PaginatedTweets
```

--------------------------------

### Manage Tweet Drafts with DraftService

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/additional-services.md

Demonstrates creating a new draft and listing existing saved drafts.

```kotlin
val params = DraftCreateParams.builder()
    .text("Draft tweet content")
    .build()

val draft = client.drafts().create(params)

// Later, retrieve drafts
val drafts = client.drafts().list()
for (draft in drafts.drafts()) {
    println(draft.text())
}
```

--------------------------------

### Authentication via API Key

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/endpoints.md

Use the X-Api-Key header for authentication.

```http
X-Api-Key: <api-key>
```

--------------------------------

### Get DM History in Kotlin

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/additional-services.md

Retrieves and iterates through the direct message history for a specific user ID.

```kotlin
val history = client.x().dm().getHistory("user-id")
for (message in history.messages()) {
    println("${message.sender()}: ${message.text()}")
}
```

--------------------------------

### Customize Headers and Query Parameters

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/client.md

Add custom headers and query parameters to all requests made by the client instance.

```kotlin
val client = XTwitterScraperOkHttpClient.builder()
    .putHeader("X-Custom-Header", "value")
    .putQueryParam("debug", "true")
    .build()
```

--------------------------------

### Configure Base URL

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/configuration.md

Define the API endpoint URL. Defaults to https://xquik.com/api/v1.

```kotlin
builder.baseUrl(String?)                 // API endpoint URL
                                         // Default: https://xquik.com/api/v1
```

--------------------------------

### Create Monitor Method Signature

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/monitors.md

The signature for creating a new monitor using MonitorCreateParams.

```kotlin
fun create(
    params: MonitorCreateParams,
    requestOptions: RequestOptions = RequestOptions.none()
): MonitorCreateResponse
```

--------------------------------

### Get tweet favoriters in Kotlin

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/tweets.md

Retrieves a list of users who liked a tweet. Note that X may return a 424 error if this data is withheld.

```kotlin
fun getFavoriters(
    id: String,
    params: TweetGetFavoritersParams = TweetGetFavoritersParams.none(),
    requestOptions: RequestOptions = RequestOptions.none()
): PaginatedUsers
```

```kotlin
val params = TweetGetFavoritersParams.builder()
    .limit(100L)
    .build()

val result = client.x().tweets().getFavoriters("1234567890", params)
for (user in result.users()) {
    println(user.username())
}
```

--------------------------------

### WebhookService.list

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/monitors.md

Lists all webhooks configured for the authenticated account.

```APIDOC
## WebhookService.list

### Description
List all webhooks for the authenticated account.

### Signature
`fun list(requestOptions: RequestOptions = RequestOptions.none()): WebhookListResponse`

### Parameters
- **requestOptions** (RequestOptions) - Optional - Request-level overrides
```

--------------------------------

### Configure Authentication

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/configuration.md

Set the API key or OAuth 2.1 bearer token for the client.

```kotlin
builder.apiKey(String?)                  // API key
builder.bearerToken(String?)             // OAuth 2.1 bearer token
```

--------------------------------

### retrieve(id: String, params: TweetRetrieveParams, requestOptions: RequestOptions)

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/tweets.md

Get a single tweet with full text, author details, engagement metrics, and media.

```APIDOC
## retrieve(id: String, params: TweetRetrieveParams, requestOptions: RequestOptions)

### Description
Get a single tweet with full text, author details, engagement metrics, and media.

### Parameters
- **id** (String) - Required - Numeric tweet ID
- **params** (TweetRetrieveParams) - Optional - Optional retrieval parameters
- **requestOptions** (RequestOptions) - Optional - Request-level overrides

### Return Type
TweetRetrieveResponse
```

--------------------------------

### Get tweet replies in Kotlin

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/tweets.md

Retrieves direct replies to a tweet. Omit the mode parameter for automatic coverage or use Complete mode for nested replies.

```kotlin
fun getReplies(
    id: String,
    params: TweetGetRepliesParams = TweetGetRepliesParams.none(),
    requestOptions: RequestOptions = RequestOptions.none()
): TweetGetRepliesResponse
```

--------------------------------

### Run Maintenance and Evidence Commands

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/OPENSSF.md

Execute these scripts to verify repository health and generate evidence before performing a release.

```sh
./scripts/lint
./scripts/test
./scripts/coverage
./scripts/audit
reuse lint
./scripts/check-reproducible
```

--------------------------------

### Create an async client in Kotlin

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/client.md

Use this to obtain an async version of the client for use with Kotlin coroutines. The async client shares resources with the sync client.

```kotlin
val asyncClient = client.async()
val tweets = asyncClient.x().tweets().search(params)  // Returns suspend function
```

--------------------------------

### Create Monitor Request Body

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/endpoints.md

JSON schema for creating a new monitor, requiring either an account_id or keyword.

```json
{
  "monitor_type": "account|keyword",
  "account_id": "string",
  "keyword": "string",
  "webhook_id": "string"
}
```

--------------------------------

### Configure Logging

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/configuration.md

Set the logging verbosity level for the client.

```kotlin
builder.logLevel(LogLevel)               // Logging verbosity
                                         // Default: LogLevel.fromEnv()
```

```kotlin
enum class LogLevel {
    DEBUG,   // Verbose request/response logging
    INFO,    // Info-level messages
    WARN,    // Warning messages
    ERROR,   // Error messages only
    NONE     // No logging
}
```

```kotlin
val client = XTwitterScraperOkHttpClient.builder()
    .logLevel(LogLevel.DEBUG)
    .build()
```

--------------------------------

### Configure Async Timeouts

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/async-usage.md

Demonstrates setting a client-level timeout via the builder and wrapping specific coroutine calls with withTimeoutOrNull.

```kotlin
val client = XTwitterScraperOkHttpClient.builder()
    .timeout(Duration.ofSeconds(30))
    .fromEnv()
    .build()

withTimeoutOrNull(10_000) {  // 10 second coroutine timeout
    client.async().x().tweets().search(params)
}
```

--------------------------------

### POST /x/media

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/endpoints.md

Uploads media content to X.

```APIDOC
## POST /x/media

### Description
Uploads media content to X.

### Method
POST

### Endpoint
/x/media

### Request Body
- **media_data** (string) - Required - Base64-encoded media data.
- **media_type** (string) - Required - MIME type of the media (e.g., image/jpeg).

### Response
#### Success Response (200)
- **media_id** (string) - Unique identifier for the uploaded media.
- **media_key** (string) - Key associated with the media.
- **size** (integer) - Size of the media in bytes.
- **expires_after_secs** (integer) - Expiration time in seconds.
```

--------------------------------

### Modify client options in Kotlin

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/client.md

Use this to create a new client instance with modified options. The original client instance remains unchanged.

```kotlin
val customClient = client.withOptions { builder ->
    builder.maxRetries(5)
    builder.putHeader("X-Custom-Header", "value")
}
```

--------------------------------

### list(params: MonitorListParams, requestOptions: RequestOptions)

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/monitors.md

Lists all monitors associated with the authenticated account.

```APIDOC
## list(params: MonitorListParams, requestOptions: RequestOptions)

### Description
Returns a list of all monitors configured for the authenticated account, supporting pagination options.

### Signature
`fun list(params: MonitorListParams = MonitorListParams.none(), requestOptions: RequestOptions = RequestOptions.none()): MonitorListResponse`

### Parameters
- **params** (MonitorListParams) - Optional - Pagination options.
- **requestOptions** (RequestOptions) - Optional - Request-level overrides.

### Return Type
`MonitorListResponse`
```

--------------------------------

### Retrieve Credit Information in Kotlin

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/additional-services.md

Access the credit balance and usage statistics using the client's credits service.

```kotlin
val credits = client.credits().retrieve()
println("Total credits: ${credits.totalCredits()}")
println("Used: ${credits.usedCredits()}")
println("Remaining: ${credits.remainingCredits()}")
```

--------------------------------

### client.monitors().create(MonitorCreateParams)

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/monitors.md

Creates a new account monitor to track specific Twitter account activity.

```APIDOC
## client.monitors().create(MonitorCreateParams)

### Description
Creates a new monitor for a specific Twitter account. The monitor can be linked to a webhook to receive real-time events.

### Parameters
- **monitorType** (String) - Required - The type of monitor (e.g., "account").
- **accountId** (String) - Required - The Twitter account ID to monitor.
- **webhookId** (String) - Optional - The ID of the webhook to associate with this monitor.
```

--------------------------------

### Implement Pagination with Async

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/async-usage.md

Uses a while loop to fetch all tweets by iterating through pages using cursors. Ensure the client is closed in a finally block to prevent resource leaks.

```kotlin
suspend fun getAllTweets(query: String): List<SearchTweet> {
    val client = XTwitterScraperOkHttpClient.fromEnv()
    val asyncClient = client.async()
    
    val allTweets = mutableListOf<SearchTweet>()
    var cursor: String? = null
    var hasMore = true
    
    try {
        while (hasMore) {
            val params = TweetSearchParams.builder()
                .q(query)
                .limit(100L)
                .apply { cursor?.let { cursor(it) } }
                .build()
            
            val result = asyncClient.x().tweets().search(params)
            allTweets.addAll(result.tweets())
            
            hasMore = result.hasNextPage()
            cursor = result.nextCursor()
        }
    } finally {
        client.close()
    }
    
    return allTweets
}
```

--------------------------------

### Managing Async Cancellation and Cleanup

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/async-usage.md

Shows how to handle coroutine lifecycle management and ensure resources are closed properly upon cancellation.

```kotlin
val job = GlobalScope.launch {
    try {
        while (isActive) {
            val tweets = asyncClient.x().tweets().search(params)
            // Process tweets
        }
    } finally {
        println("Cancelled, cleaning up")
    }
}

// Cancel the job
job.cancel()
job.join()

client.close()
```

--------------------------------

### Manage Account Connection Challenges in Kotlin

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/account-and-profile.md

Use the AccountConnectionChallengeService to create, retrieve, and list pending connection challenges.

```kotlin
client.x().accountConnectionChallenges()
    .create(params)  // Create connection challenge
    .retrieve(id)    // Get challenge details
    .list()          // List pending challenges
```

--------------------------------

### async()

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/client.md

Returns an async version of the client for use with Kotlin coroutines, sharing the underlying connection pool.

```APIDOC
## async()

### Description
Returns an async version of the client for use with Kotlin coroutines. The async client shares the underlying connection pool and resources with the sync client.

### Returns
- **XTwitterScraperClientAsync** - The asynchronous client instance.
```

--------------------------------

### Execute Parallel User Lookups

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/async-usage.md

Leverages async and awaitAll to fetch multiple user profiles concurrently, improving performance for batch operations.

```kotlin
suspend fun getUserProfiles(
    userIds: List<String>,
    asyncClient: XTwitterScraperClientAsync
): List<UserProfile> {
    return userIds.map { userId ->
        async {
            asyncClient.x().users().retrieve(userId)
        }
    }.awaitAll()
}

// Usage
val client = XTwitterScraperOkHttpClient.fromEnv()
val profiles = getUserProfiles(
    listOf("123", "456", "789"),
    client.async()
)
for (profile in profiles) {
    println("${profile.username()}: ${profile.followersCount()} followers")
}
```

--------------------------------

### SubscribeService

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/additional-services.md

Manage API subscription and billing via client.subscribe().

```APIDOC
## SubscribeService

### Description
Manage API subscription and billing.

### Methods
- **retrieve()**: Get subscription status
- **update(params)**: Update subscription plan
```

--------------------------------

### Configure Request Timeouts

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/configuration.md

Set complete request timeouts or fine-grained connect and request timeouts.

```kotlin
builder.timeout(Duration)                // Complete request timeout
                                         // Default: 60 seconds

builder.timeout(Timeout)                 // Fine-grained timeout:
                                         // - connect timeout
                                         // - request timeout
```

```kotlin
import java.time.Duration

val client = XTwitterScraperOkHttpClient.builder()
    .timeout(Duration.ofSeconds(30))
    .build()

// Fine-grained control
val customTimeout = Timeout.builder()
    .connect(Duration.ofSeconds(10))
    .request(Duration.ofSeconds(60))
    .build()

val client2 = XTwitterScraperOkHttpClient.builder()
    .timeout(customTimeout)
    .build()
```

--------------------------------

### Handle Account Connection Attempts in Kotlin

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/account-and-profile.md

Use the AccountConnectionAttemptService to submit connection attempts and track their status or history.

```kotlin
client.x().accountConnectionAttempts()
    .create(params)  // Submit connection attempt
    .retrieve(id)    // Check attempt status
    .list()          // List attempt history
```

--------------------------------

### retrieve(id: String, requestOptions: RequestOptions)

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/monitors.md

Retrieves the details of a specific monitor by its unique identifier.

```APIDOC
## retrieve(id: String, requestOptions: RequestOptions)

### Description
Fetches the configuration and status details of a specific monitor using its ID.

### Signature
`fun retrieve(id: String, requestOptions: RequestOptions = RequestOptions.none()): MonitorRetrieveResponse`

### Parameters
- **id** (String) - Required - The unique identifier of the monitor.
- **requestOptions** (RequestOptions) - Optional - Request-level overrides.

### Return Type
`MonitorRetrieveResponse`
```

--------------------------------

### Configure OAuth 2.1 Bearer Token

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/configuration.md

Use the builder pattern to set a bearer token for authentication.

```kotlin
val client = XTwitterScraperOkHttpClient.builder()
    .bearerToken("your-oauth-token")
    .build()
```

--------------------------------

### Define NotFoundException Class

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/errors.md

Exception class for HTTP 404 errors.

```kotlin
class NotFoundException(
    headers: Headers,
    body: JsonValue,
    cause: Throwable?
) : XTwitterScraperServiceException(...)
```

--------------------------------

### List Connected Accounts

Source: https://github.com/xquik-dev/x-twitter-scraper-kotlin/blob/main/_autodocs/api-reference/account-and-profile.md

Retrieves and iterates through all connected X accounts.

```kotlin
fun list(
    requestOptions: RequestOptions = RequestOptions.none()
): AccountListResponse
```

```kotlin
val response = client.x().accounts().list()
for (account in response.accounts()) {
    println("${account.username()}: ${account.status()}")
}
```
Tokens:
Raw