Stories and highlights

Retrieve feed stories, user-specific story reels, and story highlights using JxInsta’s Mobile and Web modules. Covers Story fields and download URLs.

The Story class represents a single Instagram story or highlight item and gives you direct access to its media URL, type, and engagement data. JxInsta lets you retrieve stories from three places: the authenticated account’s feed, a specific user’s active story reel, or a user’s saved highlights. The Mobile and Web modules share an identical Story field surface, so the same code for reading fields works in both.

Feed stories

Use getStories() on the Mobile client or getFeedStories() on the Web client to retrieve the batch of story reels currently visible in the authenticated account’s home feed. Both methods return List<Story[]> where each Story[] is the set of story items belonging to one user.

Mobile

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

List<Story[]> feedReels = insta.getStories();

for (Story[] reel : feedReels) {
    for (Story story : reel) {
        System.out.println(story.username + " — " + story.download_url);
    }
}

Web

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

List<Story[]> feedReels = insta.getFeedStories();

for (Story[] reel : feedReels) {
    for (Story story : reel) {
        System.out.println(story.userID + " — " + story.download_url);
    }
}

The Web client populates userID but does not always populate username on story items returned from the feed. Use userID as the reliable identifier when iterating feed results on the Web module.

User stories

getStory() on a Profile object retrieves the currently active story items for that specific account. It returns List<Story> — a flat list of all story frames, not grouped into reels.

Profile profile = insta.getProfile("natgeo");
List<Story> stories = profile.getStory();

if (stories != null && !stories.isEmpty()) {
    for (Story story : stories) {
        System.out.println(story.storyId + " — " + story.download_url);
    }
}

getStory() behaves the same way on both the Mobile and Web modules. On Mobile it returns an empty list when the user has no active stories; on Web it returns null. Always guard against both.

Highlights

getHighlights() on a Profile object returns List<Story> containing the items from all of the account’s saved highlight collections.

Profile profile = insta.getProfile("natgeo");
List<Story> highlights = profile.getHighlights();

if (highlights != null && !highlights.isEmpty()) {
    for (Story item : highlights) {
        System.out.println(item.storyId + " is_video=" + item.is_video);
        System.out.println("Download: " + item.download_url);
    }
}

Highlight items are returned in the same Story format as active stories. You can use item.is_video to branch between image and video handling without any extra API calls.

Downloading story media

download_url is always populated and points directly to the CDN-hosted media file. For video stories the URL comes from the first entry in video_versions; for image stories it comes from the first candidate in image_versions2. The URL does not require authentication to fetch.

for (Story story : stories) {
    if (story.is_video) {
        // download_url is the highest-quality video version
        System.out.println("Video: " + story.download_url);
        System.out.println("Duration: " + story.duration + "s");
    } else {
        // download_url is the highest-resolution image candidate
        System.out.println("Image: " + story.download_url);
    }
}

Liking a story (Mobile only)

On the Mobile module, Story implements Likable, which exposes like() and dislike(). These methods are not available on the Web module.

// Mobile only
Story story = stories.get(0);
story.like();    // react with a like
story.dislike(); // remove the like

like() and dislike() throw InstagramException if the request fails or if the story has already expired. Wrap calls in a try-catch when iterating over many stories.

Story field reference

The following fields are present on Story objects from both the Mobile and Web modules.

Field	Type	Description
storyId	String	The unique identifier of the story item.
userID	String	The numeric ID (pk) of the account that posted the story.
username	String	The username of the poster. May not be populated on Web feed responses.
download_url	String	Direct CDN URL to the story media (image or video).
is_video	boolean	true if the story item is a video, false if it is an image.
duration	int	Video length in seconds. -1 for image stories or when not available.
views	int	Viewer count. -1 when Instagram does not return this value.
likes	int	Like count. Mobile sets this to 1 if the authenticated user has liked it. Web returns -1 (not tracked).