X Twitter Scraper Java

https://github.com/xquik-dev/x-twitter-scraper-java
Admin
X Twitter Scraper Java is an SDK that provides convenient access to the X Twitter Scraper REST API...
Tokens:41,361
Snippets:589
Trust Score:5.5
License:Apache-2.0
Update:2 months ago
Show doc for...
Tokens:
Raw
### GET /webhooks

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

Lists all configured webhooks.

```APIDOC
## GET /webhooks

### Description
Lists all configured webhooks.

### Method
GET

### Endpoint
/webhooks

### Response
#### Success Response (200)
- **WebhookListResponse** (Object) - The list of webhooks.
```

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

### Install x-twitter-scraper-java

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

Add the library dependency to your project build configuration.

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

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

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

### Cursor-based Pagination Request

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

Example of a GET request using limit and cursor parameters for paginated results.

```http
GET /endpoint?limit=20&cursor=abc123
```

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

### Upload Media with MediaUploadParams

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/services-overview.md

Example of configuring upload parameters and executing a media upload request.

```java
MediaUploadParams params = MediaUploadParams.builder()
    .account("@username")                    // Target account (required)
    .file(Paths.get("/path/to/file.jpg"))   // File to upload
    .build();

MediaUploadResponse response = client.x().media().upload(params);
```

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

### MonitorCreateParams Usage Example

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

Demonstrates creating a monitor with specific event types using the builder pattern.

```java
MonitorCreateResponse monitor = client.monitors().create(
    MonitorCreateParams.builder()
        .account("@targetaccount")
        .watchEventTypes(Arrays.asList("TWEET_CREATED", "TWEET_DELETED"))
        .build()
);
```

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

### GET /monitors

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

Lists all active monitors.

```APIDOC
## GET /monitors

### Description
Lists all active monitors.

### Method
GET

### Endpoint
/monitors
```

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

### Install SDK via Gradle

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

Add the dependency to your build.gradle file to include the SDK in your project.

```gradle
dependencies {
    implementation 'com.xquik.api:x-twitter-scraper-java:latest'
}
```

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

### GET /api-keys

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

Lists all API keys associated with the account.

```APIDOC
## GET /api-keys

### Description
Lists all API keys.

### Method
GET

### Endpoint
/api-keys
```

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

### GET /draws

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

Lists all available draws.

```APIDOC
## GET /draws

### Description
Lists all available draws.

### Method
GET

### Endpoint
/draws
```

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

### GET /credits/balance

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

Retrieves the current credit balance.

```APIDOC
## GET /credits/balance

### Description
Retrieves the current credit balance.

### Method
GET

### Endpoint
/credits/balance
```

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

### GET /account

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

Retrieves the current account information.

```APIDOC
## GET /account

### Description
Retrieves the current account information including ID, email, username, and locale.

### Method
GET

### Endpoint
/account

### Response
#### Success Response (200)
- **id** (String) - Account ID
- **email** (String) - Account email
- **username** (String) - Account username
- **locale** (Optional<String>) - Account locale
```

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

### Implement TweetCreateParams usage

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

Examples for creating simple tweets, tweets with media attachments, and replies.

```java
// Simple tweet
SearchTweet tweet = client.x().tweets().create(
    TweetCreateParams.builder()
        .account("@myaccount")
        .text("Hello world!")
        .build()
);

// Tweet with media
SearchTweet tweetWithMedia = client.x().tweets().create(
    TweetCreateParams.builder()
        .account("@myaccount")
        .text("Check out this image!")
        .mediaIds(Arrays.asList("media_id_1", "media_id_2"))
        .build()
);

// Reply to a tweet
SearchTweet reply = client.x().tweets().create(
    TweetCreateParams.builder()
        .account("@myaccount")
        .text("@otheruser Great tweet!")
        .replyToTweetId("tweet_id_123")
        .build()
);
```

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

### GET /x/users/by/username/{username}

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

Retrieves a user profile by their username.

```APIDOC
## GET /x/users/by/username/{username}

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

### Method
GET

### Endpoint
/x/users/by/username/{username}

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the user.

### Response
#### Success Response (200)
- **UserProfile** (object) - The user profile details.
```

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

### GET /subscription

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

Retrieves the current subscription status.

```APIDOC
## GET /subscription

### Description
Retrieves the current subscription status.

### Method
GET

### Endpoint
/subscription
```

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

### Configure JDK 25 for Compatibility Tests

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

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

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

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

### GET /extractions

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

Lists all data extraction tasks.

```APIDOC
## GET /extractions

### Description
Lists all data extraction tasks.

### Method
GET

### Endpoint
/extractions

### Parameters
#### Query Parameters
- **status** (String) - Optional - Filter by status
- **limit** (Integer) - Optional - Max results
- **cursor** (String) - Optional - Pagination cursor

### Response
#### Success Response (200)
- **ExtractionListResponse** (Object) - The list of extraction tasks.
```

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

### TweetSearchParams Usage Example

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/services-overview.md

Demonstrates how to build search parameters and execute a tweet search request.

```java
TweetSearchParams params = TweetSearchParams.builder()
    .q("from:elonmusk")              // Search query (required)
    .limit(100L)                      // Max tweets (default ~20)
    .cursor("cursor_string")          // Pagination cursor
    .queryType(QueryType.LATEST)      // Sort: LATEST or TOP
    .sinceTime("2024-01-01T00:00:00Z")  // ISO 8601 timestamp
    .untilTime("2024-12-31T23:59:59Z")  // ISO 8601 timestamp
    .build();

PaginatedTweets tweets = client.x().tweets().search(params);
```

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

### Handle UnauthorizedException

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

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

```java
try {
    XTwitterScraperClient client = XTwitterScraperOkHttpClient.builder()
        .apiKey("invalid-key")
        .build();
    client.account().retrieve();
} catch (UnauthorizedException e) {
    System.out.println("Authentication failed");
    System.out.println("Check API key and bearer token");
}
```

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

### GET /drafts

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

Lists drafts with optional filtering and pagination.

```APIDOC
## GET /drafts

### Description
Lists drafts with optional filtering and pagination.

### Method
GET

### Endpoint
/drafts

### Parameters
#### Query Parameters
- **account** (string) - Optional - Filter by account
- **limit** (integer) - Optional - Max results
- **cursor** (string) - Optional - Pagination cursor
```

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

### Implement pagination loop

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

Example of iterating through tweet pages using the cursor.

```java
PaginatedTweets response = client.x().tweets().search(params);
List<SearchTweet> tweets = response.tweets();
String cursor = response.nextCursor();

// Pagination loop
while (response.hasNextPage()) {
    params = params.toBuilder().cursor(response.nextCursor()).build();
    response = client.x().tweets().search(params);
}
```

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

### GET /webhooks/{webhookId}

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

Retrieves details for a specific webhook.

```APIDOC
## GET /webhooks/{webhookId}

### Description
Retrieves details for a specific webhook.

### Method
GET

### Endpoint
/webhooks/{webhookId}

### Parameters
#### Path Parameters
- **webhookId** (String) - Required - The ID of the webhook.

### Response
#### Success Response (200)
- **WebhookDetail** (Object) - The webhook details.
```

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

### GET /x/media/{mediaId}

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

Downloads a media file by its ID.

```APIDOC
## GET /x/media/{mediaId}

### Description
Downloads the binary content of a media file by its ID.

### Method
GET

### Endpoint
/x/media/{mediaId}

### Parameters
#### Path Parameters
- **mediaId** (string) - Required - The unique identifier of the media.

### Response
#### Success Response (200)
- **Binary file content** (blob) - The raw file data.
```

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

### Execute and Poll Extraction

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

Example of creating an extraction task, polling for status, and exporting results.

```java
ExtractionCreateResponse extraction = client.extractions().create(
    ExtractionCreateParams.builder()
        .toolType("user_followers")
        .account("@targetuser")
        .build()
);

// Poll for completion
ExtractionDetail detail = client.extractions().retrieve(
    extraction.extractionId()
);

while ("running".equals(detail.status())) {
    Thread.sleep(5000);
    detail = client.extractions().retrieve(extraction.extractionId());
}

// Download results
HttpResponse response = client.extractions().exportResults(
    extraction.extractionId()
);
```

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

### Build SDK from Source

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

Clone the repository and use the Gradle wrapper to build the project locally.

```bash
git clone https://github.com/Xquik-dev/x-twitter-scraper-java.git
cd x-twitter-scraper-java
./gradlew build
```

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

### GET /x/users/search

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

Searches for users based on a query string with optional pagination.

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

### Description
Searches for users on the platform using a query string.

### Method
GET

### Endpoint
/x/users/search

### Parameters
#### Query Parameters
- **q** (string) - Required - Search query
- **limit** (integer) - Optional - Max results
- **cursor** (string) - Optional - Pagination cursor

### Response
#### Success Response (200)
- **PaginatedUsers** (object) - The paginated list of users.
```

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

### Implement TweetSearchParams usage

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

Examples for performing simple searches, advanced filtered searches, and handling pagination.

```java
// Simple search
TweetSearchParams params = TweetSearchParams.builder()
    .q("from:elonmusk")
    .build();

// Advanced search with filters
TweetSearchParams params = TweetSearchParams.builder()
    .q("bitcoin lang:en -is:retweet")
    .limit(100L)
    .queryType(QueryType.TOP)
    .sinceTime("2024-01-01T00:00:00Z")
    .untilTime("2024-12-31T23:59:59Z")
    .build();

// Pagination
PaginatedTweets response = client.x().tweets().search(params);
if (response.hasNextPage()) {
    TweetSearchParams nextParams = params.toBuilder()
        .cursor(response.nextCursor())
        .build();
    PaginatedTweets nextResponse = client.x().tweets().search(nextParams);
}
```

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

### Get Monitor Events in Java

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

Retrieves a paginated list of events captured by a specific monitor.

```java
import com.x_twitter_scraper.api.models.events.EventListParams;

var events = client.events().list("monitorId123",
    EventListParams.builder()
        .limit(20L)
        .build()
);

for (var event : events.events()) {
    System.out.println(event.type() + " at " + event.timestamp());
}
```

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

### Per-Service Configuration

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/services-overview.md

Demonstrates how to apply custom options, such as timeouts, to a specific service instance.

```java
AccountService customAccountService = client.account().withOptions(opts -> {
    opts.timeout(Duration.ofSeconds(5));
});

AccountRetrieveResponse response = customAccountService.retrieve();
```

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

### Initialize Client and Search Tweets

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

Instantiate the client using environment variables and perform a paginated tweet search.

```java
import com.x_twitter_scraper.api.client.XTwitterScraperClient;
import com.x_twitter_scraper.api.client.okhttp.XTwitterScraperOkHttpClient;
import com.x_twitter_scraper.api.models.PaginatedTweets;
import com.x_twitter_scraper.api.models.x.tweets.TweetSearchParams;

// Create client from environment variables
XTwitterScraperClient client = XTwitterScraperOkHttpClient.fromEnv();

// Search tweets
TweetSearchParams params = TweetSearchParams.builder()
    .q("from:elonmusk")
    .limit(10L)
    .build();

PaginatedTweets tweets = client.x().tweets().search(params);

// Process results
for (var tweet : tweets.tweets()) {
    System.out.println(tweet.text());
}
```

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

### Manage Client Lifecycle

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/core-concepts.md

Shows client instantiation and proper resource cleanup using a try-finally block.

```java
// Create client (allocates connection pool, thread pools)
XTwitterScraperClient client = XTwitterScraperOkHttpClient.fromEnv();

try {
    // Use client for application lifetime
    client.x().tweets().search(params);
    
} finally {
    // Optional: Close when shutting down
    // Usually not necessary - SDK releases idle resources automatically
    client.close();
}
```

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

### GET /x/users/{userId}/following

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

Retrieves the list of users that a specific user is following.

```APIDOC
## GET /x/users/{userId}/following

### Description
Retrieves a paginated list of users that the specified user is following.

### Method
GET

### Endpoint
/x/users/{userId}/following

### Parameters
#### Path Parameters
- **userId** (string) - Required - The unique identifier of the user.

### Response
#### Success Response (200)
- **PaginatedUsers** (object) - The paginated list of followed users.
```

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

### Handle BadRequestException

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

Example of catching a 400 error caused by invalid request parameters.

```java
try {
    TweetSearchParams params = TweetSearchParams.builder()
        .q("")  // Empty query
        .build();
    client.x().tweets().search(params);
} catch (BadRequestException e) {
    System.out.println("Invalid request: " + e.body());
    // body() contains API error details as JSON
}
```

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

### Initialize XTwitterScraperOkHttpClient via Static Methods

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/client-setup.md

Access the client builder or create an instance directly from environment variables.

```java
class XTwitterScraperOkHttpClient {
    static Builder builder()
    static XTwitterScraperClient fromEnv()
}
```

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

### GET /drafts/{draftId}

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

Retrieves details for a specific draft.

```APIDOC
## GET /drafts/{draftId}

### Description
Retrieves details for a specific draft.

### Method
GET

### Endpoint
/drafts/{draftId}

### Parameters
#### Path Parameters
- **draftId** (string) - Required - The ID of the draft
```

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

### Create Monitor in Java

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

Initializes a new monitor for a specific account to track defined event types.

```java
import com.x_twitter_scraper.api.models.monitors.MonitorCreateParams;
import com.x_twitter_scraper.api.models.monitors.MonitorCreateResponse;

MonitorCreateResponse monitor = client.monitors().create(
    MonitorCreateParams.builder()
        .account("@targetaccount")
        .watchEventTypes(java.util.Arrays.asList(
            "TWEET_CREATED", "TWEET_DELETED", "USER_FOLLOWED"
        ))
        .build()
);

System.out.println("Monitor created: " + monitor.monitorId());
```

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

### client.x().media().upload(params)

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

Configures parameters for uploading media files.

```APIDOC
## client.x().media().upload(params)

### Description
Uploads media to the platform for a specific account.

### Parameters
- **params** (MediaUploadParams) - Required - Configuration object containing:
  - **account** (String) - Required - Target account (@username).
  - **file** (Object) - Required - The file to upload (supports Path, InputStream, byte[], or MultipartField).
```

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

### Modify client configuration

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/client-setup.md

Use the withOptions method to create a new client instance with modified settings while preserving the original client's configuration.

```java
XTwitterScraperClient customClient = client.withOptions(opts -> {
    opts.baseUrl("https://staging.xquik.com/api/v1");
    opts.maxRetries(5);
});
```

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

### Get User Followers

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

Fetch a user's followers, including support for manual pagination using cursors.

```java
import com.x_twitter_scraper.api.models.PaginatedUsers;

String userId = "123456789";
PaginatedUsers followers = client.x().users().followers(userId);

System.out.println("Total fetched: " + followers.users().size());

// Paginate through followers
String cursor = null;
int totalFetched = 0;

do {
    if (cursor != null) {
        followers = client.x().users().followers(userId,
            new com.x_twitter_scraper.api.models.x.users.UserFollowersParams
                .Builder().cursor(cursor).build());
    }
    
    totalFetched += followers.users().size();
    cursor = followers.nextCursor();
    
} while (cursor != null && totalFetched < 1000);
```

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

### Project File Structure

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

Displays the directory layout of the documentation output folder.

```text
/output/
├── INDEX.md                 ← Start here for navigation
├── README.md               ← Quick start
├── client-setup.md         ← Configuration details
├── services-overview.md    ← Service reference
├── types.md               ← Type definitions
├── parameters.md          ← Request parameters
├── errors.md              ← Error handling
├── usage-examples.md      ← Code examples
├── core-concepts.md       ← Architecture
├── api-endpoints.md       ← REST endpoints
└── MANIFEST.md            ← This file
```

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

### GET /monitors/{monitorId}

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

Retrieves details for a specific monitor.

```APIDOC
## GET /monitors/{monitorId}

### Description
Retrieves details for a specific monitor.

### Method
GET

### Endpoint
/monitors/{monitorId}

### Parameters
#### Path Parameters
- **monitorId** (String) - Required - The ID of the monitor.
```

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

### Initialize XTwitterScraperClient

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

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

```java
import com.x_twitter_scraper.api.client.XTwitterScraperClient;
import com.x_twitter_scraper.api.client.okhttp.XTwitterScraperOkHttpClient;

XTwitterScraperClient client = XTwitterScraperOkHttpClient.fromEnv();
```

```java
XTwitterScraperClient client = XTwitterScraperOkHttpClient.builder()
    .apiKey("your-api-key")
    .build();
```

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

### Enable HTTP Logging

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/client-setup.md

Configures logging levels via environment variables.

```bash
# Info level
export X_TWITTER_SCRAPER_LOG=info

# Debug level
export X_TWITTER_SCRAPER_LOG=debug
```

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

### GET /x/tweets/{tweetId}

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

Retrieves a specific tweet by ID.

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

### Description
Retrieves details for a specific tweet.

### Method
GET

### Endpoint
/x/tweets/{tweetId}

### Parameters
#### Path Parameters
- **tweetId** (String) - Required - The ID of the tweet
```

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

### Accessing X Twitter Scraper Services

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/services-overview.md

Initialize the client using environment variables and access specific service modules through the client instance.

```java
XTwitterScraperClient client = XTwitterScraperOkHttpClient.fromEnv();

// Each service is accessed as a method on the client
client.x().tweets().search(params);        // Tweet operations
client.x().users().lookup("elonmusk");     // User operations
client.account().retrieve();                // Account settings
client.compose().create(params);            // AI composition
client.extractions().create(params);        // Data extraction
client.monitors().create(params);           // Account monitoring
client.webhooks().create(params);           // Webhook management
```

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

### GET /x/tweets/search

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

Searches for tweets based on query parameters.

```APIDOC
## GET /x/tweets/search

### Description
Searches for tweets using X operators and supports pagination.

### Method
GET

### Endpoint
/x/tweets/search

### Parameters
#### Query Parameters
- **q** (String) - Required - Search query with X operators
- **limit** (Integer) - Optional - Max tweets to return
- **cursor** (String) - Optional - Pagination cursor
- **query_type** (String) - Optional - LATEST or TOP
- **since_time** (String) - Optional - ISO 8601 timestamp
- **until_time** (String) - Optional - ISO 8601 timestamp

### Response
#### Success Response (200)
- **has_next_page** (boolean) - Indicates if more pages exist
- **next_cursor** (String) - Cursor for next page
- **tweets** (List<SearchTweet>) - List of tweets
```

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

### Perform integration testing with real client

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/core-concepts.md

Configures a client pointing to a staging environment for integration testing. Ensure the client is closed in a finally block to release resources.

```java
XTwitterScraperClient client = XTwitterScraperOkHttpClient.builder()
    .baseUrl("https://staging.xquik.com/api/v1")  // Test endpoint
    .apiKey(testApiKey)
    .build();

try {
    PaginatedTweets tweets = client.x().tweets().search(params);
    assertEquals(0, tweets.tweets().size());  // Test staging has no data
} finally {
    client.close();
}
```

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

### GET /draws/{drawId}

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

Retrieves details for a specific draw by its ID.

```APIDOC
## GET /draws/{drawId}

### Description
Retrieves details for a specific draw by its ID.

### Method
GET

### Endpoint
/draws/{drawId}

### Parameters
#### Path Parameters
- **drawId** (string) - Required - The ID of the draw
```

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

### GET /extractions/{extractionId}/export

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

Exports the results of an extraction task.

```APIDOC
## GET /extractions/{extractionId}/export

### Description
Exports the results of an extraction task.

### Method
GET

### Endpoint
/extractions/{extractionId}/export

### Parameters
#### Path Parameters
- **extractionId** (String) - Required - The ID of the extraction task.

#### Query Parameters
- **format** (String) - Optional - The export format (e.g., CSV, JSON).

### Response
#### Success Response (200)
- **Binary file** (File) - The exported data file.
```

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

### Implement Basic Error Handling

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

Demonstrates catching specific SDK exceptions to handle different failure scenarios like authentication, rate limiting, and network issues.

```java
try {
    PaginatedTweets tweets = client.x().tweets().search(params);
} catch (BadRequestException e) {
    // Invalid parameters
    System.out.println("Bad request: " + e.body());
} catch (UnauthorizedException e) {
    // Auth failed
    System.out.println("Authentication failed");
} catch (RateLimitException e) {
    // Rate limited
    System.out.println("Rate limited, retry after: " + 
        e.headers().get("Retry-After"));
} catch (XTwitterScraperServiceException e) {
    // Other HTTP error
    System.out.println("HTTP " + e.statusCode() + ": " + e.body());
} catch (XTwitterScraperIoException e) {
    // Network error
    System.out.println("Network error: " + e.getMessage());
} catch (XTwitterScraperException e) {
    // Generic SDK error
    System.out.println("SDK error: " + e.getMessage());
}
```

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

### Execute Verification Gates

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

Run the full suite of linting, testing, coverage, and 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 /extractions/{extractionId}

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

Retrieves details for a specific extraction task.

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

### Description
Retrieves details for a specific extraction task.

### Method
GET

### Endpoint
/extractions/{extractionId}

### Parameters
#### Path Parameters
- **extractionId** (String) - Required - The ID of the extraction task.

### Response
#### Success Response (200)
- **ExtractionDetail** (Object) - The extraction task details.
```

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

### Share Client Instance for Concurrency

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/core-concepts.md

Initialize a single client instance to benefit from shared connection and thread pools. This approach ensures efficient resource usage and consistent rate limiting.

```java
// Good - shared instance
XTwitterScraperClient client = XTwitterScraperOkHttpClient.fromEnv();

// Use from multiple threads
executor.submit(() -> {
    client.x().tweets().search(params1);
});

executor.submit(() -> {
    client.x().tweets().search(params2);
});
```

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

### GET /x/users/{userId}

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

Retrieves a user profile by their unique ID.

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

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

### Method
GET

### Endpoint
/x/users/{userId}

### Parameters
#### Path Parameters
- **userId** (string) - Required - The unique identifier of the user.

### Response
#### Success Response (200)
- **UserProfile** (object) - The user profile details.
```

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

### POST /monitors

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

Creates a new monitor for a target account.

```APIDOC
## POST /monitors

### Description
Creates a new monitor for a target account.

### Method
POST

### Endpoint
/monitors

### Request Body
- **account** (String) - Required - The handle of the target account.
- **watch_event_types** (Array) - Required - List of event types to watch (e.g., TWEET_CREATED, TWEET_DELETED).

### Request Example
{
  "account": "@targetaccount",
  "watch_event_types": ["TWEET_CREATED", "TWEET_DELETED"]
}
```

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

### Download Media via Java SDK

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

Downloads binary media content and saves it to the local filesystem.

```java
HttpResponse response = client.x().media().download("mediaId123");
Files.copy(response.body(), Paths.get("downloaded.jpg"));
```

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

### GET /trends

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

Retrieves trending topics based on the provided Where on Earth ID.

```APIDOC
## GET /trends

### Description
Retrieves trending topics for a specific location.

### Method
GET

### Endpoint
/trends

### Parameters
#### Query Parameters
- **woeid** (integer) - Required - Where on Earth ID (1=worldwide)
- **exclude** (string) - Optional - Exclude type (hashtags, promoted_content)
```

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

### Initialize XTwitterScraperClient

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

Configure the client using environment variables or manual builder settings. Manual configuration allows overriding base URLs, retry limits, and timeouts.

```java
import com.x_twitter_scraper.api.client.XTwitterScraperClient;
import com.x_twitter_scraper.api.client.okhttp.XTwitterScraperOkHttpClient;

// Load from X_TWITTER_SCRAPER_API_KEY, X_TWITTER_SCRAPER_BEARER_TOKEN env vars
XTwitterScraperClient client = XTwitterScraperOkHttpClient.fromEnv();
```

```java
XTwitterScraperClient client = XTwitterScraperOkHttpClient.builder()
    .apiKey("your-api-key")
    .bearerToken("your-bearer-token")
    .baseUrl("https://xquik.com/api/v1")
    .maxRetries(2)
    .timeout(java.time.Duration.ofSeconds(30))
    .build();
```

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

### GET /draws/{drawId}/export

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

Exports the results of a draw in a specified format.

```APIDOC
## GET /draws/{drawId}/export

### Description
Exports the results of a draw in a specified format.

### Method
GET

### Endpoint
/draws/{drawId}/export

### Parameters
#### Path Parameters
- **drawId** (string) - Required - The ID of the draw

#### Query Parameters
- **format** (string) - Optional - The export format (e.g., CSV, JSON)
```

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

### Get Draft Details Endpoint

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

Retrieves details for a specific draft by ID.

```http
GET /drafts/{draftId}
```

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

### GET /monitors/{monitorId}/events/{eventId}

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

Retrieves the details of a specific event.

```APIDOC
## GET /monitors/{monitorId}/events/{eventId}

### Description
Retrieves the details of a specific event.

### Method
GET

### Endpoint
/monitors/{monitorId}/events/{eventId}

### Parameters
#### Path Parameters
- **monitorId** (String) - Required - The ID of the monitor.
- **eventId** (String) - Required - The ID of the event.

### Response
#### Success Response (200)
- **EventDetail** (Object) - The event details.
```

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

### Get Extraction Details Endpoint

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

Retrieves details for a specific extraction by ID.

```http
GET /extractions/{extractionId}
```

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

### XTwitterScraperClient Service Access

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/services-overview.md

Demonstrates how to initialize the client and access the various service interfaces available in the SDK.

```APIDOC
## SDK Service Access

### Description
The `XTwitterScraperClient` serves as the primary entry point for all SDK operations. Services are accessed via method chaining on the client instance.

### Usage
```java
XTwitterScraperClient client = XTwitterScraperOkHttpClient.fromEnv();

// Accessing core services
client.x().tweets().search(params);
client.x().users().lookup("elonmusk");
client.account().retrieve();
client.compose().create(params);
client.extractions().create(params);
client.monitors().create(params);
client.webhooks().create(params);
```
```

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

### Set Authentication Environment Variable

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

Configure the API key via environment variable.

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

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

### Get Webhook Details Endpoint

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

Retrieves details for a specific webhook by ID.

```http
GET /webhooks/{webhookId}
```

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

### Get Event Details Endpoint

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

Retrieves details for a specific event by ID.

```http
GET /monitors/{monitorId}/events/{eventId}
```

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

### client.x().users().search(params)

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

Configures parameters for searching users.

```APIDOC
## client.x().users().search(params)

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

### Parameters
- **params** (UserSearchParams) - Required - Configuration object containing:
  - **q** (String) - Required - User search query (username or display name).
  - **limit** (Long) - Optional - Max results to return.
  - **cursor** (String) - Optional - Pagination cursor.
```

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

### Construct parameters using the builder pattern

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

Standard approach for initializing parameter objects using the fluent builder API.

```java
SomeParams params = SomeParams.builder()
    .requiredField("value")
    .optionalField("value")
    .anotherOptional("value")
    .build();
```

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

### GET /x/users/{userId}/followers

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

Retrieves the list of followers for a specific user.

```APIDOC
## GET /x/users/{userId}/followers

### Description
Retrieves a paginated list of followers for the specified user.

### Method
GET

### Endpoint
/x/users/{userId}/followers

### Parameters
#### Path Parameters
- **userId** (string) - Required - The unique identifier of the user.
#### Query Parameters
- **limit** (integer) - Optional - Max results
- **cursor** (string) - Optional - Pagination cursor

### Response
#### Success Response (200)
- **PaginatedUsers** (object) - The paginated list of followers.
```

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

### POST /compose

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

Creates a new content composition.

```APIDOC
## POST /compose

### Description
Creates a new content composition.

### Method
POST

### Endpoint
/compose

### Request Body
- **topic** (string) - Topic description
- **style** (string) - Writing style
- **tone** (string) - Writing tone

### Request Example
{
  "topic": "topic description",
  "style": "professional",
  "tone": "friendly"
}
```

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

### Get User Profile with Java

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

Fetches a user profile by their Twitter username.

```java
UserProfile user = client.x().users().getByUsername("elonmusk");
```

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

### Get Tweet by ID

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

Retrieves a specific tweet using its unique identifier.

```java
SearchTweet tweet = client.x().tweets().get("1234567890");
```

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

### Retrieve Monitor Details in Java

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

Fetches specific configuration details for a monitor using its unique identifier.

```java
var monitor = client.monitors().retrieve("monitorId123");
System.out.println("Events watched: " + monitor.watchEventTypes());
```

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

### List Monitors in Java

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

Retrieves all active monitors and iterates through their status and account details.

```java
var response = client.monitors().list();

for (var monitor : response.monitors()) {
    System.out.println("Monitoring: " + monitor.account() + 
        " (Status: " + monitor.status() + ")");
}
```

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

### Configure Custom Client Options

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

Applies specific configuration overrides, such as timeouts, to a service client instance using the withOptions method.

```java
// Create a client with custom timeout for a single service
var customClient = client.x().tweets().withOptions(opts -> {
    opts.timeout(java.time.Duration.ofSeconds(60));
});

// Perform operation with extended timeout
PaginatedTweets tweets = customClient.search(params);
```

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

### Get Draw Details Endpoint

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

Fetches details for a specific draw using its ID.

```http
GET /draws/{drawId}
```

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

### List Draws Endpoint

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

Retrieves a list of existing draws via GET /draws.

```http
GET /draws
```

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

### GET /monitors/{monitorId}/events

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

Retrieves a list of events associated with a specific monitor.

```APIDOC
## GET /monitors/{monitorId}/events

### Description
Retrieves a list of events associated with a specific monitor.

### Method
GET

### Endpoint
/monitors/{monitorId}/events

### Parameters
#### Path Parameters
- **monitorId** (String) - Required - The ID of the monitor.

#### Query Parameters
- **limit** (Integer) - Optional - Max results
- **cursor** (String) - Optional - Pagination cursor
- **event_type** (String) - Optional - Filter by type

### Response
#### Success Response (200)
- **EventListResponse** (Object) - The list of events.
```

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

### POST /x/media/upload

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

Uploads a media file to a target account.

```APIDOC
## POST /x/media/upload

### Description
Uploads a media file to the specified account.

### Method
POST

### Endpoint
/x/media/upload

### Parameters
#### Request Body
- **account** (string) - Required - Target account
- **file** (file) - Required - Media file

### Response
#### Success Response (200)
- **media_id** (string) - The ID of the uploaded media.
- **type** (string) - Optional - The type of media.
- **url** (string) - Optional - The URL of the uploaded media.
```

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

### POST /credits/topup

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

Tops up the credit balance.

```APIDOC
## POST /credits/topup

### Description
Adds credits to the account balance.

### Method
POST

### Endpoint
/credits/topup

### Parameters
#### Request Body
- **amount** (number) - Required - The amount to top up
- **payment_method** (string) - Required - The payment method used
```

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

### Configure client timeouts

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/client-setup.md

Create a custom Timeout object and apply it during the client initialization process.

```java
Timeout timeout = Timeout.builder()
    .connect(Duration.ofSeconds(5))
    .read(Duration.ofSeconds(10))
    .write(Duration.ofSeconds(10))
    .request(Duration.ofSeconds(30))
    .build();

XTwitterScraperClient client = XTwitterScraperOkHttpClient.builder()
    .timeout(timeout)
    .build();
```

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

### Handle PermissionDeniedException

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

Example of catching a 403 error when an operation is not permitted for the current account.

```java
try {
    // If feature not available in your subscription tier
    client.extractions().create(params);
} catch (PermissionDeniedException e) {
    System.out.println("Feature not available: " + e.body());
}
```

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

### Download Media from X

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

Downloads media content by ID and saves it to a local file path using standard Java NIO.

```java
import com.x_twitter_scraper.api.core.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.StandardCopyOption;

HttpResponse response = client.x().media().download("mediaId123");

Files.copy(
    response.body(),
    Paths.get("/path/to/downloaded/file.jpg"),
    StandardCopyOption.REPLACE_EXISTING
);
```

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

### ClientOptions

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/client-setup.md

Configuration class for global client behavior. Immutable after construction, it defines the base URL, authentication tokens, and retry policies.

```APIDOC
## ClientOptions

### Description
Contains all configuration for client behavior. Immutable after construction.

### Usage
```java
// Creating a modified client
XTwitterScraperClient customClient = client.withOptions(opts -> {
    opts.baseUrl("https://staging.xquik.com/api/v1");
    opts.maxRetries(5);
});
```
```

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

### Get Monitor Details API Endpoint

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

Retrieves detailed information for a specific monitor by ID.

```http
GET /monitors/{monitorId}
```

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

### Utilize Service Method Overloads

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/services-overview.md

Demonstrates flexible method signatures for common operations like searching and retrieving tweets.

```java
// Search tweets
PaginatedTweets search(TweetSearchParams params)
PaginatedTweets search(TweetSearchParams params, RequestOptions options)

// Single tweet lookup
SearchTweet get(String tweetId)
SearchTweet get(String tweetId, TweetGetParams params)
SearchTweet get(String tweetId, TweetGetParams params, RequestOptions options)

// Convenience: minimal params
SearchTweet get(String tweetId, RequestOptions options)
```

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

### Package Structure Visualization

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

Visual representation of the project's package hierarchy and module organization.

```text
com.x_twitter_scraper.api
├── client                      # Client interfaces and implementations
│   ├── XTwitterScraperClient
│   ├── XTwitterScraperClientAsync
│   └── okhttp                  # OkHttp-specific implementations
├── core                        # Core utilities
│   ├── ClientOptions
│   ├── RequestOptions
│   ├── Timeout
│   └── http                    # HTTP abstractions
├── services                    # Service implementations
│   └── blocking                # Synchronous services
├── models                      # Request/response types
├── errors                      # Exception types
└── generated                   # Auto-generated code
```

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

### Implement batch pagination

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/core-concepts.md

Use cursors and batch limits to retrieve large datasets efficiently without overloading memory.

```java
// Good - fetches all available data efficiently
List<SearchTweet> allTweets = new ArrayList<>();
String cursor = null;

do {
    TweetSearchParams params = baseParams.toBuilder()
        .cursor(cursor)
        .limit(100L)  // Fetch in batches
        .build();
    
    PaginatedTweets response = client.x().tweets().search(params);
    allTweets.addAll(response.tweets());
    cursor = response.nextCursor();
} while (response.hasNextPage());
```

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

### MonitorService

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/services-overview.md

Interface for managing real-time account monitors.

```APIDOC
## MonitorService

### Methods
- **create(MonitorCreateParams params)**: Create a new monitor for an account.
- **list()**: List all monitors.
- **list(MonitorListParams params)**: List monitors with filtering parameters.
- **retrieve(String monitorId)**: Get details for a specific monitor.
- **update(String monitorId, MonitorUpdateParams params)**: Update settings for an existing monitor.
- **delete(String monitorId)**: Delete a monitor.
```

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

### Client Configuration

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/client-setup.md

Configuring the client with custom retry limits, headers, and query parameters.

```APIDOC
## Client Configuration

### Description
Configure the `XTwitterScraperClient` using the builder pattern to set retry limits, custom headers, and default query parameters.

### Usage
```java
// Configure retries
XTwitterScraperClient client = XTwitterScraperOkHttpClient.builder()
    .maxRetries(4)
    .build();

// Add custom headers and query parameters
XTwitterScraperClient client = XTwitterScraperOkHttpClient.builder()
    .putHeader("X-Custom-Header", "value")
    .putQueryParam("debug", "true")
    .build();
```
```

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

### Verify Maven Signatures

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

Download and verify the artifact signature using GPG.

```sh
artifact="x-twitter-scraper-java-0.5.2.jar"
base="https://repo.maven.apache.org/maven2/com/xquik/api/x-twitter-scraper-java/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"
```

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

### Get User Profile

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

Retrieve user profile information using either a user ID or a username.

```java
import com.x_twitter_scraper.api.models.UserProfile;

// By user ID
UserProfile user = client.x().users().get("userId123");

// By username
UserProfile user = client.x().users().getByUsername("elonmusk");

System.out.println("Followers: " + user.followerCount());
System.out.println("Bio: " + user.bio());
```

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

### Run maintenance and evidence verification commands

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

Execute these scripts to verify repository health, test coverage, and compliance before performing a release.

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

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

### Create Monitor API Endpoint

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

Creates a new monitor for tracking specific account events.

```http
POST /monitors
```

```json
{
  "account": "@targetaccount",
  "watch_event_types": ["TWEET_CREATED", "TWEET_DELETED"]
}
```

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

### Create Webhook Endpoint

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

Creates a new webhook configuration.

```http
POST /webhooks
```

```json
{
  "url": "https://example.com/webhook",
  "events": ["TWEET_CREATED", "USER_FOLLOWED"]
}
```

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

### Invoke tweet retrieval overloads

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/core-concepts.md

Examples of calling different service method overloads based on the required level of configuration.

```java
// Use appropriate overload for your needs
SearchTweet tweet = client.x().tweets().get("123");
SearchTweet tweet = client.x().tweets().get("123", tweetParams);
SearchTweet tweet = client.x().tweets().get("123", requestOptions);
SearchTweet tweet = client.x().tweets().get("123", params, options);
```

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

### Configure XTwitterScraper client hierarchy

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/core-concepts.md

Demonstrates how to apply configuration overrides at the client, service, and request levels. Request-level settings take the highest precedence.

```java
// 1. Client-level defaults
XTwitterScraperClient client = XTwitterScraperOkHttpClient.builder()
    .timeout(java.time.Duration.ofSeconds(30))
    .maxRetries(2)
    .build();

// 2. Service-level override
XTwitterScraperClient customService = client.x().tweets().withOptions(opts ->
    opts.timeout(java.time.Duration.ofSeconds(60))
);

// 3. Request-level override
PaginatedTweets tweets = client.x().tweets().search(
    params,
    com.x_twitter_scraper.api.core.RequestOptions.builder()
        .timeout(java.time.Duration.ofSeconds(120))
        .build()
);
```

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

### client.x().users().followers(userId, params)

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

Configures parameters for retrieving user followers.

```APIDOC
## client.x().users().followers(userId, params)

### Description
Retrieves a list of followers for a specific user.

### Parameters
- **userId** (Long) - Required - The ID of the user.
- **params** (UserFollowersParams) - Required - Configuration object containing:
  - **limit** (Long) - Optional - Max results to return.
  - **cursor** (String) - Optional - Pagination cursor.
```

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

### Follow User

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

Initiates a follow request for the specified user ID.

```java
client.x().profile().follow("userId123");
System.out.println("Following user");
```

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

### MonitorCreateParams

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

Parameters for creating a new monitor for a specific account.

```APIDOC
## MonitorCreateParams

### Description
Parameters used to create a monitor for a specific Twitter account. Usage: `client.monitors().create(params)`.

### Parameters
- **account** (String) - Required - Account to monitor (@username)
- **watchEventTypes** (List<String>) - Optional - Event types to watch (Default: All types)

### Event Types
- TWEET_CREATED
- TWEET_DELETED
- TWEET_LIKED
- TWEET_UNLIKED
- USER_FOLLOWED
- USER_UNFOLLOWED
- USER_BLOCKED
- USER_UNBLOCKED
- DM_RECEIVED
- DM_SENT

### Example
```java
MonitorCreateResponse monitor = client.monitors().create(
    MonitorCreateParams.builder()
        .account("@targetaccount")
        .watchEventTypes(Arrays.asList("TWEET_CREATED", "TWEET_DELETED"))
        .build()
);
```
```

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

### MediaService

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/services-overview.md

Methods for uploading and downloading media files.

```APIDOC
## MediaService

### Methods
- **upload(MediaUploadParams params)**: Upload a media file.
- **download(String mediaId)**: Download media.
- **download(String mediaId, MediaDownloadParams params)**: Download media with parameters.
```

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

### TrendService Interface and Usage

Source: https://github.com/xquik-dev/x-twitter-scraper-java/blob/main/_autodocs/services-overview.md

Provides methods to fetch trending topics and demonstrates how to configure parameters using the builder pattern.

```java
interface TrendService {
    // Get trending topics by region
    TrendListResponse list()
    TrendListResponse list(TrendListParams params)
}
```

```java
TrendListParams params = TrendListParams.builder()
    .woeid(1)  // Where on Earth ID (1 = worldwide)
    .build();

TrendListResponse trends = client.trends().list(params);
```

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

### MonitorCreateParams Definition and Usage

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

Defines parameters for creating a monitor, including the required account username and optional event types.

```java
class MonitorCreateParams {
    String account()                    // Required (@username)
    Optional<List<String>> watchEventTypes()
    
    static Builder builder()
}
```
Tokens:
Raw