Get started

Learn how to authenticate with Instagram, fetch a profile, follow a user, and post a picture using JxInsta in under 10 lines of Java.

JxInsta lets you interact with Instagram programmatically using either the Mobile module (bearer token) or the Web module (session cookies). This quickstart walks you through adding the dependency, authenticating, and performing your first actions — from fetching a profile to posting a picture.

Prerequisites

• Java 21 or later
• Gradle or Maven build system
• An Instagram account (username and password)

1. Add the dependency

   Add the JitPack repository and the JxInsta module to your build file. Choose mobile for DM support or web for session-based access and public endpoints.

   Gradle (Mobile)

   settings.gradle

   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
       repositories {
           mavenCentral()
           maven { url 'https://jitpack.io' }
       }
   }
   

   build.gradle

   dependencies {
       implementation 'com.github.Errorxcode.jxinsta:mobile:2.0'
   }
   

   Gradle (Web)

   settings.gradle

   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
       repositories {
           mavenCentral()
           maven { url 'https://jitpack.io' }
       }
   }
   

   build.gradle

   dependencies {
       implementation 'com.github.Errorxcode.jxinsta:web:2.0'
   }
   
2. Authenticate

   Create a JxInsta instance with your username and password. After login, save the credential for reuse to avoid repeated logins.

   Mobile

   import com.jxinsta.mobile.JxInsta;
   import com.jxinsta.mobile.InstagramException;
   
   try {
       JxInsta insta = new JxInsta("your_username", "your_password");
       // Save insta.token for future runs
       System.out.println("Token: " + insta.token);
   } catch (InstagramException e) {
       System.err.println("Login failed: " + e.getReason());
   } catch (IOException e) {
       System.err.println("Network error: " + e.getMessage());
   }
   

   To reuse an existing token:

   JxInsta insta = JxInsta.getInstance("your_saved_token");
   

   Web

   import com.jxinsta.web.JxInsta;
   import com.jxinsta.web.InstagramException;
   
   try {
       JxInsta insta = new JxInsta("your_username", "your_password");
       // Save insta.session and insta.crsf for future runs
       System.out.println("Session: " + insta.session);
   } catch (InstagramException e) {
       System.err.println("Login failed: " + e.getReason());
   } catch (IOException e) {
       System.err.println("Network error: " + e.getMessage());
   }
   

   To reuse an existing session:

   JxInsta insta = JxInsta.getInstance("your_session_id", "your_csrf_token");
   

   Save insta.token (Mobile) or insta.session + insta.crsf (Web) to a file after first login. Reuse them with getInstance() to skip the login request on subsequent runs. See Session Caching.

3. Fetch a profile

   Call getProfile() with any Instagram username to retrieve profile data and perform social actions.

   import com.jxinsta.mobile.endpoints.profile.Profile;
   
   Profile profile = insta.getProfile("someusername");
   System.out.println("Name: " + profile.name);
   System.out.println("Bio: " + profile.biography);
   System.out.println("Followers: " + profile.followers);
   System.out.println("Private: " + profile.isPrivate);
   
   // Follow the user
   profile.follow();
   
4. Post a picture

   Upload an image to Instagram using an InputStream. Optionally disable likes and comments.

   import java.io.FileInputStream;
   
   try (FileInputStream fis = new FileInputStream("photo.jpg")) {
       insta.postPicture(fis, "My first post via JxInsta!", false);
       System.out.println("Posted successfully.");
   } catch (InstagramException e) {
       System.err.println("Post failed: " + e.getReason());
   }
   
5. Handle errors

   All Instagram API calls throw InstagramException. Use getReason() to respond to specific failure types.

   try {
       Profile profile = insta.getProfile("someuser");
       profile.follow();
   } catch (InstagramException e) {
       switch (e.getReason()) {
           case RATE_LIMITED, THROTTLED -> System.out.println("Slow down — rate limited");
           case CHECKPOINT_REQUIRED -> System.out.println("Instagram challenge required");
           case PRIVATE_ACCOUNT -> System.out.println("Account is private");
           case LOGIN_EXPIRED -> System.out.println("Session expired, re-login needed");
           default -> System.err.println("Error: " + e.getMessage());
       }
   }
   

JxInsta uses Instagram’s private API. Add at least a 5-second delay between requests to avoid detection. See Rate Limits for guidance.

Authentication guide

Learn more about login options, 2FA, and session reuse

Error handling

Handle every InstagramException reason code