0
# Lists Management
1

2
Twitter list creation, management, and member operations.
3

4
## List Operations
5

6
### Creating and Managing Lists
7

8
Create, update, and manage Twitter lists.
9

10
```java { .api }
11
interface ListsResources {
12
    /**
13
     * Create a new list
14
     * @param listName Name of the list
15
     * @param isPublicList Whether list is public (true) or private (false)
16
     * @param description List description
17
     * @return Created list
18
     */
19
    UserList createUserList(String listName, boolean isPublicList, String description) throws TwitterException;
20
    
21
    /**
22
     * Update an existing list
23
     * @param listId List ID to update
24
     * @param newListName New name for the list
25
     * @param isPublicList Whether list should be public
26
     * @param newDescription New description
27
     * @return Updated list
28
     */
29
    UserList updateUserList(long listId, String newListName, boolean isPublicList, String newDescription) throws TwitterException;
30
    
31
    /**
32
     * Delete a list
33
     * @param listId List ID to delete
34
     * @return Deleted list
35
     */
36
    UserList destroyUserList(long listId) throws TwitterException;
37
}
38
```
39

40
### List Access and Retrieval
41

42
Retrieve lists and list information.
43

44
```java { .api }
45
interface ListsResources {
46
    /**
47
     * Get lists owned by a user
48
     * @param screenName User's screen name
49
     * @return Lists owned by user
50
     */
51
    ResponseList<UserList> getUserLists(String screenName) throws TwitterException;
52
    
53
    /**
54
     * Get lists a user is subscribed to
55
     * @param screenName User's screen name
56
     * @return Lists user is subscribed to
57
     */
58
    ResponseList<UserList> getUserListSubscriptions(String screenName) throws TwitterException;
59
    
60
    /**
61
     * Show details of a specific list
62
     * @param listId List ID
63
     * @return List details
64
     */
65
    UserList showUserList(long listId) throws TwitterException;
66
    
67
    /**
68
     * Get tweets from a list
69
     * @param listId List ID
70
     * @param paging Pagination parameters
71
     * @return Tweets from list members
72
     */
73
    ResponseList<Status> getUserListStatuses(long listId, Paging paging) throws TwitterException;
74
}
75
```
76

77
## List Membership
78

79
### Managing List Members
80

81
Add, remove, and manage list members.
82

83
```java { .api }
84
interface ListsResources {
85
    /**
86
     * Add user to list by user ID
87
     * @param listId List ID
88
     * @param userId User ID to add
89
     * @return Updated list
90
     */
91
    UserList addUserListMember(long listId, long userId) throws TwitterException;
92
    
93
    /**
94
     * Add multiple users to list
95
     * @param listId List ID
96
     * @param userIds Array of user IDs to add (max 100)
97
     * @return Updated list
98
     */
99
    UserList addUserListMembers(long listId, long... userIds) throws TwitterException;
100
    
101
    /**
102
     * Remove user from list by user ID
103
     * @param listId List ID
104
     * @param userId User ID to remove
105
     * @return Updated list
106
     */
107
    UserList deleteUserListMember(long listId, long userId) throws TwitterException;
108
    
109
    /**
110
     * Remove multiple users from list
111
     * @param listId List ID
112
     * @param userIds Array of user IDs to remove
113
     * @return Updated list
114
     */
115
    UserList deleteUserListMembers(long listId, long... userIds) throws TwitterException;
116
    
117
    /**
118
     * Get list members
119
     * @param listId List ID
120
     * @param cursor Pagination cursor (-1 for first page)
121
     * @return Paginated list of members
122
     */
123
    PagableResponseList<User> getUserListMembers(long listId, long cursor) throws TwitterException;
124
    
125
    /**
126
     * Check if user is member of list
127
     * @param listId List ID
128
     * @param userId User ID to check
129
     * @return User if member, throws exception if not
130
     */
131
    User checkUserListMembership(long listId, long userId) throws TwitterException;
132
}
133
```
134

135
## List Subscriptions
136

137
### Following Lists
138

139
Subscribe to and unsubscribe from lists.
140

141
```java { .api }
142
interface ListsResources {
143
    /**
144
     * Subscribe to a list (follow)
145
     * @param listId List ID to subscribe to
146
     * @return Subscribed list
147
     */
148
    UserList subscribeUserList(long listId) throws TwitterException;
149
    
150
    /**
151
     * Unsubscribe from a list (unfollow)
152
     * @param listId List ID to unsubscribe from
153
     * @return Unsubscribed list
154
     */
155
    UserList unsubscribeUserList(long listId) throws TwitterException;
156
    
157
    /**
158
     * Get list subscribers
159
     * @param listId List ID
160
     * @param cursor Pagination cursor (-1 for first page)
161
     * @return Paginated list of subscribers
162
     */
163
    PagableResponseList<User> getUserListSubscribers(long listId, long cursor) throws TwitterException;
164
    
165
    /**
166
     * Check if user is subscribed to list
167
     * @param listId List ID
168
     * @param userId User ID to check
169
     * @return User if subscribed, throws exception if not
170
     */
171
    User checkUserListSubscription(long listId, long userId) throws TwitterException;
172
}
173
```
174

175
**Usage Examples:**
176

177
```java
178
TwitterV1 v1 = twitter.v1();
179

180
// Create a new public list
181
UserList techList = v1.list().createUserList(
182
    "Tech Leaders", 
183
    true, 
184
    "Influential people in technology"
185
);
186

187
// Add members to the list
188
v1.list().addUserListMember(techList.getId(), 783214L); // Add by user ID
189
v1.list().addUserListMembers(techList.getId(), 783214L, 17874544L, 95731L); // Add multiple
190

191
// Get tweets from the list
192
ResponseList<Status> listTweets = v1.list().getUserListStatuses(techList.getId(), null);
193
for (Status tweet : listTweets) {
194
    System.out.println(tweet.getUser().getScreenName() + ": " + tweet.getText());
195
}
196

197
// Subscribe to another user's list
198
v1.list().subscribeUserList(anotherListId);
199

200
// Get all lists you own
201
ResponseList<UserList> myLists = v1.list().getUserLists("myusername");
202
for (UserList list : myLists) {
203
    System.out.println(list.getName() + " (" + list.getMemberCount() + " members)");
204
}
205
```
206

207
## List Data Model
208

209
### UserList Interface
210

211
Complete list information and metadata.
212

213
```java { .api }
214
interface UserList extends TwitterResponse {
215
    /**
216
     * List unique identifier
217
     */
218
    long getId();
219
    
220
    /**
221
     * List name
222
     */
223
    String getName();
224
    
225
    /**
226
     * List description
227
     */
228
    String getDescription();
229
    
230
    /**
231
     * List owner user
232
     */
233
    User getUser();
234
    
235
    /**
236
     * Number of members in list
237
     */
238
    int getMemberCount();
239
    
240
    /**
241
     * Number of subscribers to list
242
     */
243
    int getSubscriberCount();
244
    
245
    /**
246
     * List creation timestamp
247
     */
248
    LocalDateTime getCreatedAt();
249
    
250
    /**
251
     * Whether list is public
252
     */
253
    boolean isPublic();
254
    
255
    /**
256
     * Whether authenticated user is following this list
257
     */
258
    boolean isFollowing();
259
    
260
    /**
261
     * List slug (URL-friendly name)
262
     */
263
    String getSlug();
264
    
265
    /**
266
     * Full list name (owner/listname)
267
     */
268
    String getFullName();
269
    
270
    /**
271
     * List URI
272
     */
273
    String getURI();
274
}
275
```
276

277
## Advanced List Management
278

279
### List Analytics
280

281
```java
282
public class ListAnalytics {
283
    private final TwitterV1 v1;
284
    
285
    public ListStats analyzeList(long listId) throws TwitterException {
286
        UserList list = v1.list().showUserList(listId);
287
        PagableResponseList<User> members = v1.list().getUserListMembers(listId, -1);
288
        ResponseList<Status> recentTweets = v1.list().getUserListStatuses(listId, 
289
            Paging.ofCount(200));
290
        
291
        ListStats stats = new ListStats();
292
        stats.listName = list.getName();
293
        stats.memberCount = list.getMemberCount();
294
        stats.subscriberCount = list.getSubscriberCount();
295
        
296
        // Analyze member activity
297
        stats.averageFollowerCount = members.stream()
298
            .mapToInt(User::getFollowersCount)
299
            .average().orElse(0.0);
300
            
301
        stats.verifiedMemberCount = (int) members.stream()
302
            .filter(User::isVerified)
303
            .count();
304
            
305
        // Analyze recent activity
306
        stats.recentTweetCount = recentTweets.size();
307
        stats.averageRetweetCount = recentTweets.stream()
308
            .mapToInt(Status::getRetweetCount)
309
            .average().orElse(0.0);
310
            
311
        return stats;
312
    }
313
    
314
    public static class ListStats {
315
        public String listName;
316
        public int memberCount;
317
        public int subscriberCount;
318
        public double averageFollowerCount;
319
        public int verifiedMemberCount;
320
        public int recentTweetCount;
321
        public double averageRetweetCount;
322
    }
323
}
324
```
325

326
### Bulk List Operations
327

328
```java
329
public class BulkListManager {
330
    private final TwitterV1 v1;
331
    
332
    public void populateListFromSearch(long listId, String searchQuery, int maxUsers) 
333
            throws TwitterException {
334
        Query query = Query.of(searchQuery).count(100);
335
        QueryResult searchResult = v1.search().search(query);
336
        
337
        Set<Long> uniqueUsers = new HashSet<>();
338
        
339
        // Collect unique users from search results
340
        for (Status tweet : searchResult.getTweets()) {
341
            uniqueUsers.add(tweet.getUser().getId());
342
            if (uniqueUsers.size() >= maxUsers) break;
343
        }
344
        
345
        // Add users to list in batches of 100
346
        List<Long> userList = new ArrayList<>(uniqueUsers);
347
        for (int i = 0; i < userList.size(); i += 100) {
348
            int end = Math.min(i + 100, userList.size());
349
            List<Long> batch = userList.subList(i, end);
350
            
351
            long[] batchArray = batch.stream().mapToLong(Long::longValue).toArray();
352
            v1.list().addUserListMembers(listId, batchArray);
353
            
354
            // Rate limiting
355
            Thread.sleep(1000);
356
        }
357
    }
358
    
359
    public void cleanupInactiveMembers(long listId, int inactiveDays) throws TwitterException {
360
        PagableResponseList<User> members = v1.list().getUserListMembers(listId, -1);
361
        List<Long> toRemove = new ArrayList<>();
362
        
363
        LocalDateTime cutoffDate = LocalDateTime.now().minusDays(inactiveDays);
364
        
365
        for (User member : members) {
366
            try {
367
                ResponseList<Status> recentTweets = v1.timelines()
368
                    .getUserTimeline(member.getId(), Paging.ofCount(1));
369
                    
370
                if (recentTweets.isEmpty() || 
371
                    recentTweets.get(0).getCreatedAt().isBefore(cutoffDate)) {
372
                    toRemove.add(member.getId());
373
                }
374
                
375
                Thread.sleep(100); // Rate limiting
376
            } catch (TwitterException e) {
377
                if (e.getStatusCode() == 401) {
378
                    // Protected account or suspended - remove from list
379
                    toRemove.add(member.getId());
380
                }
381
            }
382
        }
383
        
384
        // Remove inactive members in batches
385
        for (int i = 0; i < toRemove.size(); i += 100) {
386
            int end = Math.min(i + 100, toRemove.size());
387
            List<Long> batch = toRemove.subList(i, end);
388
            
389
            long[] batchArray = batch.stream().mapToLong(Long::longValue).toArray();
390
            v1.list().deleteUserListMembers(listId, batchArray);
391
            
392
            Thread.sleep(1000);
393
        }
394
    }
395
}
396
```
397

398
### List Content Curation
399

400
```java
401
public class ListCurator {
402
    private final TwitterV1 v1;
403
    
404
    public void curateListByTopic(long listId, List<String> keywords, int minFollowers) 
405
            throws TwitterException {
406
        
407
        PagableResponseList<User> currentMembers = v1.list().getUserListMembers(listId, -1);
408
        Set<Long> relevantMembers = new HashSet<>();
409
        
410
        // Analyze current members' recent tweets for relevance
411
        for (User member : currentMembers) {
412
            try {
413
                ResponseList<Status> recentTweets = v1.timelines()
414
                    .getUserTimeline(member.getId(), Paging.ofCount(20));
415
                
416
                long relevantTweetCount = recentTweets.stream()
417
                    .filter(tweet -> containsKeywords(tweet.getText(), keywords))
418
                    .count();
419
                
420
                // Keep members who tweet about the topic and meet follower threshold
421
                if (relevantTweetCount >= 3 && member.getFollowersCount() >= minFollowers) {
422
                    relevantMembers.add(member.getId());
423
                }
424
                
425
                Thread.sleep(100);
426
            } catch (TwitterException e) {
427
                // Handle rate limits and errors
428
                if (e.exceededRateLimitation()) {
429
                    Thread.sleep(e.getRetryAfter() * 1000);
430
                }
431
            }
432
        }
433
        
434
        // Remove irrelevant members
435
        List<Long> toRemove = currentMembers.stream()
436
            .map(User::getId)
437
            .filter(id -> !relevantMembers.contains(id))
438
            .collect(Collectors.toList());
439
            
440
        for (long userId : toRemove) {
441
            v1.list().deleteUserListMember(listId, userId);
442
            Thread.sleep(100);
443
        }
444
    }
445
    
446
    private boolean containsKeywords(String text, List<String> keywords) {
447
        String lowerText = text.toLowerCase();
448
        return keywords.stream()
449
            .anyMatch(keyword -> lowerText.contains(keyword.toLowerCase()));
450
    }
451
}
452
```