0
# Timeline Access
1

2
Access to various Twitter timelines including home timeline, user timeline, and mentions.
3

4
## Timeline Types
5

6
### Home Timeline
7

8
Get tweets from users that the authenticated user follows.
9

10
```java { .api }
11
interface TimelinesResources {
12
    /**
13
     * Get the 20 most recent tweets from home timeline
14
     * @return List of tweets from followed users
15
     */
16
    ResponseList<Status> getHomeTimeline() throws TwitterException;
17
    
18
    /**
19
     * Get home timeline with pagination
20
     * @param paging Pagination parameters (page, count, since_id, max_id)
21
     * @return List of tweets from followed users
22
     */
23
    ResponseList<Status> getHomeTimeline(Paging paging) throws TwitterException;
24
}
25
```
26

27
**Usage Examples:**
28

29
```java
30
TwitterV1 v1 = twitter.v1();
31

32
// Get recent home timeline
33
ResponseList<Status> homeTimeline = v1.timelines().getHomeTimeline();
34
for (Status tweet : homeTimeline) {
35
    System.out.println(tweet.getUser().getScreenName() + ": " + tweet.getText());
36
}
37

38
// Get home timeline with pagination
39
Paging paging = Paging.ofCount(50).sinceId(1234567890L);
40
ResponseList<Status> paginatedTimeline = v1.timelines().getHomeTimeline(paging);
41
```
42

43
### User Timeline
44

45
Get tweets posted by a specific user.
46

47
```java { .api }
48
interface TimelinesResources {
49
    /**
50
     * Get authenticated user's timeline (20 most recent tweets)
51
     * @return List of user's tweets
52
     */
53
    ResponseList<Status> getUserTimeline() throws TwitterException;
54
    
55
    /**
56
     * Get specific user's timeline by screen name
57
     * @param screenName User's screen name (without @)
58
     * @return List of user's tweets
59
     */
60
    ResponseList<Status> getUserTimeline(String screenName) throws TwitterException;
61
    
62
    /**
63
     * Get specific user's timeline by user ID
64
     * @param userId User's numeric ID
65
     * @return List of user's tweets
66
     */
67
    ResponseList<Status> getUserTimeline(long userId) throws TwitterException;
68
    
69
    /**
70
     * Get user timeline with pagination by screen name
71
     * @param screenName User's screen name (without @)
72
     * @param paging Pagination parameters
73
     * @return List of user's tweets
74
     */
75
    ResponseList<Status> getUserTimeline(String screenName, Paging paging) throws TwitterException;
76
    
77
    /**
78
     * Get user timeline with pagination by user ID
79
     * @param userId User's numeric ID
80
     * @param paging Pagination parameters
81
     * @return List of user's tweets
82
     */
83
    ResponseList<Status> getUserTimeline(long userId, Paging paging) throws TwitterException;
84
}
85
```
86

87
**Usage Examples:**
88

89
```java
90
// Get authenticated user's timeline
91
ResponseList<Status> myTimeline = v1.timelines().getUserTimeline();
92

93
// Get specific user's timeline by screen name
94
ResponseList<Status> userTweets = v1.timelines().getUserTimeline("twitterapi");
95

96
// Get user timeline by ID
97
ResponseList<Status> userTweetsById = v1.timelines().getUserTimeline(783214L);
98

99
// Get user timeline with pagination
100
Paging paging = Paging.ofCount(100).maxId(9876543210L);
101
ResponseList<Status> paginatedUserTweets = v1.timelines()
102
    .getUserTimeline("twitterapi", paging);
103
```
104

105
### Mentions Timeline
106

107
Get tweets that mention the authenticated user.
108

109
```java { .api }
110
interface TimelinesResources {
111
    /**
112
     * Get 20 most recent mentions of authenticated user
113
     * @return List of tweets mentioning the user
114
     */
115
    ResponseList<Status> getMentionsTimeline() throws TwitterException;
116
    
117
    /**
118
     * Get mentions timeline with pagination
119
     * @param paging Pagination parameters
120
     * @return List of tweets mentioning the user
121
     */
122
    ResponseList<Status> getMentionsTimeline(Paging paging) throws TwitterException;
123
}
124
```
125

126
**Usage Examples:**
127

128
```java
129
// Get recent mentions
130
ResponseList<Status> mentions = v1.timelines().getMentionsTimeline();
131
for (Status mention : mentions) {
132
    System.out.println("@" + mention.getUser().getScreenName() + " mentioned you: " + 
133
                      mention.getText());
134
}
135

136
// Get mentions with pagination
137
Paging paging = Paging.ofCount(200).sinceId(1234567890L);
138
ResponseList<Status> paginatedMentions = v1.timelines().getMentionsTimeline(paging);
139
```
140

141
### Retweets Timeline
142

143
Get retweets of the authenticated user's tweets.
144

145
```java { .api }
146
interface TimelinesResources {
147
    /**
148
     * Get 20 most recent retweets of authenticated user's tweets
149
     * @return List of retweets of user's tweets
150
     */
151
    ResponseList<Status> getRetweetsOfMe() throws TwitterException;
152
    
153
    /**
154
     * Get retweets of user's tweets with pagination
155
     * @param paging Pagination parameters
156
     * @return List of retweets of user's tweets
157
     */
158
    ResponseList<Status> getRetweetsOfMe(Paging paging) throws TwitterException;
159
}
160
```
161

162
**Usage Examples:**
163

164
```java
165
// Get recent retweets of your tweets
166
ResponseList<Status> myRetweets = v1.timelines().getRetweetsOfMe();
167
for (Status retweet : myRetweets) {
168
    Status originalTweet = retweet.getRetweetedStatus();
169
    System.out.println("Your tweet retweeted: " + originalTweet.getText());
170
    System.out.println("Retweeted by: " + retweet.getUser().getScreenName());
171
}
172

173
// Get retweets with pagination
174
Paging paging = Paging.ofCount(50).maxId(9876543210L);
175
ResponseList<Status> paginatedRetweets = v1.timelines().getRetweetsOfMe(paging);
176
```
177

178
## Pagination Control
179

180
### Paging Class
181

182
Comprehensive pagination control for timeline requests.
183

184
```java { .api }
185
class Paging {
186
    /**
187
     * Create pagination by page number (deprecated approach)
188
     * @param page Page number (1-indexed)
189
     * @return Paging object for page-based pagination
190
     */
191
    static Paging ofPage(int page);
192
    
193
    /**
194
     * Create pagination by count only
195
     * @param count Number of tweets to retrieve (max 200)
196
     * @return Paging object with count setting
197
     */
198
    static Paging ofCount(int count);
199
    
200
    /**
201
     * Set page number (deprecated - use cursor-based pagination instead)
202
     * @param page Page number
203
     * @return Paging with page setting
204
     */
205
    Paging withPage(int page);
206
    
207
    /**
208
     * Set number of tweets per page
209
     * @param count Number of tweets (1-200, default 20)
210
     * @return Paging with count setting
211
     */
212
    Paging count(int count);
213
    
214
    /**
215
     * Set since_id for retrieving tweets newer than specified ID
216
     * @param sinceId Tweet ID - only tweets newer than this will be returned
217
     * @return Paging with since_id setting
218
     */
219
    Paging sinceId(long sinceId);
220
    
221
    /**
222
     * Set max_id for retrieving tweets older than specified ID
223
     * @param maxId Tweet ID - only tweets older than this will be returned
224
     * @return Paging with max_id setting
225
     */
226
    Paging maxId(long maxId);
227
    
228
    /**
229
     * Get current page number
230
     */
231
    int getPage();
232
    
233
    /**
234
     * Get current count setting
235
     */
236
    int getCount();
237
    
238
    /**
239
     * Get current since_id setting
240
     */
241
    long getSinceId();
242
    
243
    /**
244
     * Get current max_id setting
245
     */
246
    long getMaxId();
247
}
248
```
249

250
**Pagination Strategies:**
251

252
```java
253
TwitterV1 v1 = twitter.v1();
254

255
// Strategy 1: Get latest tweets (since a specific tweet)
256
long lastSeenId = 1234567890L;
257
Paging newTweets = Paging.ofCount(50).sinceId(lastSeenId);
258
ResponseList<Status> latest = v1.timelines().getHomeTimeline(newTweets);
259

260
// Strategy 2: Get older tweets (before a specific tweet)
261
long oldestId = 9876543210L;
262
Paging olderTweets = Paging.ofCount(100).maxId(oldestId - 1);
263
ResponseList<Status> older = v1.timelines().getHomeTimeline(olderTweets);
264

265
// Strategy 3: Get maximum tweets per request
266
Paging maxTweets = Paging.ofCount(200); // 200 is the maximum
267
ResponseList<Status> bulk = v1.timelines().getHomeTimeline(maxTweets);
268

269
// Strategy 4: Continuous pagination through timeline
270
long maxId = Long.MAX_VALUE;
271
List<Status> allTweets = new ArrayList<>();
272

273
while (allTweets.size() < 1000) { // Stop after 1000 tweets
274
    Paging paging = Paging.ofCount(200).maxId(maxId - 1);
275
    ResponseList<Status> batch = v1.timelines().getHomeTimeline(paging);
276
    
277
    if (batch.isEmpty()) break; // No more tweets
278
    
279
    allTweets.addAll(batch);
280
    maxId = batch.get(batch.size() - 1).getId();
281
}
282
```
283

284
## Timeline Filtering and Options
285

286
### Rate Limiting Considerations
287

288
All timeline endpoints have rate limits that should be monitored.
289

290
```java
291
ResponseList<Status> timeline = v1.timelines().getHomeTimeline();
292

293
// Check rate limit status
294
RateLimitStatus rateLimit = timeline.getRateLimitStatus();
295
System.out.println("Remaining requests: " + rateLimit.getRemaining());
296
System.out.println("Rate limit resets at: " + 
297
                  Instant.ofEpochSecond(rateLimit.getResetTimeInSeconds()));
298

299
if (rateLimit.getRemaining() < 5) {
300
    // Approaching rate limit - consider backing off
301
    int sleepTime = rateLimit.getSecondsUntilReset();
302
    System.out.println("Rate limit low, sleeping for " + sleepTime + " seconds");
303
    Thread.sleep(sleepTime * 1000);
304
}
305
```
306

307
### Timeline Processing Patterns
308

309
#### Real-time Timeline Monitoring
310

311
```java
312
public class TimelineMonitor {
313
    private final TwitterV1 v1;
314
    private long lastSeenId = 1L;
315
    
316
    public TimelineMonitor(TwitterV1 v1) {
317
        this.v1 = v1;
318
    }
319
    
320
    public List<Status> getNewTweets() throws TwitterException {
321
        Paging paging = Paging.ofCount(200).sinceId(lastSeenId);
322
        ResponseList<Status> newTweets = v1.timelines().getHomeTimeline(paging);
323
        
324
        if (!newTweets.isEmpty()) {
325
            lastSeenId = newTweets.get(0).getId();
326
        }
327
        
328
        return newTweets;
329
    }
330
    
331
    public void monitorTimeline() {
332
        ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(1);
333
        
334
        scheduler.scheduleAtFixedRate(() -> {
335
            try {
336
                List<Status> newTweets = getNewTweets();
337
                for (Status tweet : newTweets) {
338
                    processTweet(tweet);
339
                }
340
            } catch (TwitterException e) {
341
                System.err.println("Error fetching timeline: " + e.getMessage());
342
            }
343
        }, 0, 60, TimeUnit.SECONDS); // Check every minute
344
    }
345
    
346
    private void processTweet(Status tweet) {
347
        // Process new tweet
348
        System.out.println("New tweet: " + tweet.getText());
349
    }
350
}
351
```
352

353
#### Historical Timeline Analysis
354

355
```java
356
public class TimelineAnalyzer {
357
    private final TwitterV1 v1;
358
    
359
    public List<Status> getAllUserTweets(String screenName, int maxTweets) 
360
            throws TwitterException {
361
        List<Status> allTweets = new ArrayList<>();
362
        long maxId = Long.MAX_VALUE;
363
        
364
        while (allTweets.size() < maxTweets) {
365
            int remaining = Math.min(200, maxTweets - allTweets.size());
366
            Paging paging = Paging.ofCount(remaining).maxId(maxId - 1);
367
            
368
            ResponseList<Status> batch = v1.timelines()
369
                .getUserTimeline(screenName, paging);
370
            
371
            if (batch.isEmpty()) break;
372
            
373
            allTweets.addAll(batch);
374
            maxId = batch.get(batch.size() - 1).getId();
375
            
376
            // Respect rate limits
377
            RateLimitStatus rateLimit = batch.getRateLimitStatus();
378
            if (rateLimit.getRemaining() <= 1) {
379
                try {
380
                    Thread.sleep(rateLimit.getSecondsUntilReset() * 1000L);
381
                } catch (InterruptedException e) {
382
                    Thread.currentThread().interrupt();
383
                    break;
384
                }
385
            }
386
        }
387
        
388
        return allTweets;
389
    }
390
}
391
```
392

393
#### Timeline Content Filtering
394

395
```java
396
public class TimelineFilter {
397
    
398
    public List<Status> filterTweets(ResponseList<Status> timeline, 
399
                                   Predicate<Status> filter) {
400
        return timeline.stream()
401
            .filter(filter)
402
            .collect(Collectors.toList());
403
    }
404
    
405
    // Common filters
406
    public static Predicate<Status> originalTweetsOnly() {
407
        return tweet -> tweet.getRetweetedStatus() == null;
408
    }
409
    
410
    public static Predicate<Status> retweetsOnly() {
411
        return tweet -> tweet.getRetweetedStatus() != null;
412
    }
413
    
414
    public static Predicate<Status> withMedia() {
415
        return tweet -> tweet.getMediaEntities().length > 0;
416
    }
417
    
418
    public static Predicate<Status> withHashtag(String hashtag) {
419
        return tweet -> Arrays.stream(tweet.getHashtagEntities())
420
            .anyMatch(entity -> entity.getText().equalsIgnoreCase(hashtag));
421
    }
422
    
423
    public static Predicate<Status> fromUser(String screenName) {
424
        return tweet -> tweet.getUser().getScreenName()
425
            .equalsIgnoreCase(screenName);
426
    }
427
    
428
    public static Predicate<Status> newerThan(LocalDateTime time) {
429
        return tweet -> tweet.getCreatedAt().isAfter(time);
430
    }
431
}
432

433
// Usage example
434
ResponseList<Status> timeline = v1.timelines().getHomeTimeline();
435

436
List<Status> originalTweetsWithMedia = new TimelineFilter()
437
    .filterTweets(timeline, 
438
        TimelineFilter.originalTweetsOnly()
439
            .and(TimelineFilter.withMedia())
440
            .and(TimelineFilter.newerThan(LocalDateTime.now().minusHours(24)))
441
    );
442
```
443

444
## Response Data Structure
445

446
### Timeline Response List
447

448
All timeline methods return `ResponseList<Status>` with rate limiting information.
449

450
```java { .api }
451
interface ResponseList<T> extends List<T>, TwitterResponse {
452
    /**
453
     * Get rate limit status for this response
454
     */
455
    RateLimitStatus getRateLimitStatus();
456
    
457
    /**
458
     * Get access level for this response
459
     */
460
    int getAccessLevel();
461
}
462
```
463

464
### Status Information
465

466
Each timeline entry is a `Status` object containing tweet data.
467

468
```java { .api }
469
interface Status {
470
    /**
471
     * Tweet creation timestamp
472
     */
473
    LocalDateTime getCreatedAt();
474
    
475
    /**
476
     * Unique tweet identifier
477
     */
478
    long getId();
479
    
480
    /**
481
     * Tweet text content
482
     */
483
    String getText();
484
    
485
    /**
486
     * Tweet author information
487
     */
488
    User getUser();
489
    
490
    /**
491
     * Whether this is a retweet
492
     */
493
    boolean isRetweet();
494
    
495
    /**
496
     * Original tweet if this is a retweet
497
     */
498
    Status getRetweetedStatus();
499
    
500
    /**
501
     * Reply information
502
     */
503
    long getInReplyToStatusId();
504
    String getInReplyToScreenName();
505
    
506
    /**
507
     * Engagement metrics
508
     */
509
    int getRetweetCount();
510
    int getFavoriteCount();
511
    
512
    /**
513
     * User interaction status
514
     */
515
    boolean isRetweeted();
516
    boolean isFavorited();
517
    
518
    /**
519
     * Tweet entities (URLs, mentions, hashtags, media)
520
     */
521
    URLEntity[] getURLEntities();
522
    UserMentionEntity[] getUserMentionEntities();
523
    HashtagEntity[] getHashtagEntities();
524
    MediaEntity[] getMediaEntities();
525
    
526
    /**
527
     * Geographic information
528
     */
529
    GeoLocation getGeoLocation();
530
    Place getPlace();
531
}
532
```
533

534
## Error Handling
535

536
Timeline operations can fail due to various reasons including rate limiting, authentication issues, or user privacy settings.
537

538
```java
539
try {
540
    ResponseList<Status> timeline = v1.timelines().getUserTimeline("privateuser");
541
} catch (TwitterException e) {
542
    switch (e.getStatusCode()) {
543
        case 401:
544
            System.out.println("User's tweets are protected");
545
            break;
546
        case 404:
547
            System.out.println("User not found");
548
            break;
549
        case 429:
550
            System.out.println("Rate limit exceeded");
551
            int retryAfter = e.getRetryAfter();
552
            System.out.println("Retry after " + retryAfter + " seconds");
553
            break;
554
        default:
555
            System.out.println("API error: " + e.getMessage());
556
    }
557
}
558
```