Paginate Instagram data with iterators

Use JxInsta’s paginator classes to iterate through posts, followers, comments, messages, and feed items one page at a time using Java’s Iterator pattern.

JxInsta exposes several paginator classes that implement Iterator<List<T>>, letting you walk through large Instagram datasets one page at a time using the standard Java iterator pattern. Rather than loading all results into memory upfront, each call to next() fetches only the current page from the API, which keeps memory usage predictable and lets you stop early once you have the data you need.

The standard pagination loop

Every paginator in JxInsta follows the same usage pattern: call hasNext() to check whether another page is available, then call next() to retrieve it. If you call next() when hasNext() is false, a NoSuchElementException is thrown.

while (paginator.hasNext()) {
    List<Item> page = paginator.next();
    for (Item item : page) {
        // process each item
    }
}

Add a short delay between next() calls when iterating large datasets. Fetching many pages in rapid succession increases the risk of hitting Instagram’s rate limits. A delay of 1–2 seconds per page is a reasonable starting point.

FeedPaginator

FeedPaginator iterates pages of Post objects from the authenticated account’s home feed. Obtain one by calling getFeed() on the Mobile JxInsta client.

JxInsta insta = new JxInsta("your_username", "your_password");

FeedPaginator feedPages = insta.getFeed();

while (feedPages.hasNext()) {
    List<Post> page = feedPages.next();
    for (Post post : page) {
        System.out.println(post.id + " — " + post.caption);
    }
}

Each page contains a variable number of posts depending on the feed response. The paginator tracks the next_max_id cursor internally and sets hasNext() to false when more_available is no longer returned by the API.

FeedPaginator is available on the Mobile module only. The Web module does not expose a feed paginator.

PostPaginator

PostPaginator iterates a user’s grid posts, returning pages of Post objects. Obtain one by calling getPosts() on a Profile object. Each page fetches 12 posts and advances using a max_id cursor.

Mobile

Profile profile = insta.getProfile("natgeo");
PostPaginator postPages = profile.getPosts();

while (postPages.hasNext()) {
    List<Post> page = postPages.next();
    for (Post post : page) {
        System.out.println(post.id + " — " + post.caption);
    }
}

Web

The Web client accepts an optional starting cursor. Pass null to start from the first page.

Profile profile = insta.getProfile("natgeo");
PostPaginator postPages = profile.getPosts(null);

while (postPages.hasNext()) {
    List<Post> page = postPages.next();
    for (Post post : page) {
        System.out.println(post.id + " — " + post.caption);
    }
}

ProfilePaginator

ProfilePaginator iterates follower or following lists, returning pages of Profile objects. Obtain one by calling getFollowers() or getFollowings() on a Profile. The Mobile paginator requests up to 200 profiles per page.

Mobile

ProfilePaginator followerPages = profile.getFollowers();

while (followerPages.hasNext()) {
    List<Profile> page = followerPages.next();
    for (Profile follower : page) {
        System.out.println(follower.username + " (" + follower.pk + ")");
    }
}

Use getFollowings() in the same way to iterate accounts the profile follows.

ProfilePaginator followingPages = profile.getFollowings();

while (followingPages.hasNext()) {
    List<Profile> page = followingPages.next();
    for (Profile following : page) {
        System.out.println(following.username);
    }
}

Web

ProfilePaginator followerPages = profile.getFollowers(null);

while (followerPages.hasNext()) {
    List<Profile> page = followerPages.next();
    for (Profile follower : page) {
        System.out.println(follower.username + " (" + follower.pk + ")");
    }
}

Paginating a large follower list (hundreds of thousands of accounts) can trigger Instagram’s rate limits. Add a delay of at least 1 second between pages and avoid running full pagination loops unattended.

CommentPaginator

CommentPaginator iterates the comments on a single post, returning pages of Comment objects. Obtain one by calling getComments() on a Post object. It is available on both the Mobile and Web modules.

Post post = insta.getPost("https://www.instagram.com/p/ABC123xyz/");
CommentPaginator commentPages = post.getComments();

while (commentPages.hasNext()) {
    List<Comment> page = commentPages.next();
    for (Comment comment : page) {
        System.out.println(comment);
    }
}

The paginator uses a min_id cursor internally and sets hasNext() to false when no next_min_id is returned.

MessagePaginator

MessagePaginator iterates the message history of a Direct Message thread, returning pages of Message objects in reverse-chronological order (newest first). Obtain one by calling getMessages() on a Thread object.

Thread thread = insta.getThread("thread_id_here");
MessagePaginator messagePages = thread.getMessages();

while (messagePages.hasNext()) {
    List<Message> page = messagePages.next();
    for (Message message : page) {
        System.out.println(message);
    }
}

Each page fetches 20 messages. The paginator advances using the oldest_cursor from the thread response and stops when no cursor is returned.

MessagePaginator is available on the Mobile module only. The Web module does not expose Direct Message APIs.

HashtagPaginator

HashtagPaginator iterates public posts associated with a hashtag, returning pages of HashtagPost records. Obtain one from PublicAPIs.hashtagSearch() — no login is required.

HashtagPaginator hashtagPages = PublicAPIs.hashtagSearch("astronomy", null);

while (hashtagPages.hasNext()) {
    List<HashtagPost> page = hashtagPages.next();
    for (HashtagPost post : page) {
        System.out.println(post.username() + ": " + post.caption());
        System.out.println("Download: " + post.downloadUrl());
    }
}

Pass a cursor string as the second argument to hashtagSearch() to resume from a specific page, or pass null to start from the beginning. Each page contains up to 29 posts.

HashtagPaginator is available in the Web module only. It does not require an authenticated session, but it shares the same public rate limits as the other PublicAPIs methods.

Paginator reference

Paginator	Module	Source method	Item type	Page size
FeedPaginator	Mobile	insta.getFeed()	Post	Variable
PostPaginator	Mobile + Web	profile.getPosts()	Post	12
ProfilePaginator	Mobile + Web	profile.getFollowers() / getFollowings()	Profile	200 (Mobile) / 50 (Web)
CommentPaginator	Mobile + Web	post.getComments()	Comment	~20
MessagePaginator	Mobile	thread.getMessages()	Message	20
HashtagPaginator	Web	PublicAPIs.hashtagSearch(tag, cursor)	HashtagPost	29