Instagram Basic Display API: A Comprehensive Guide

Are you looking to integrate Instagram user data, profile information, images, videos, and albums into your Facebook apps? Look no further! The Instagram Basic Display API is an HTTP-based API that enables Facebook apps to access all this data seamlessly. In this article, we will guide you through the process of setting up and configuring the Instagram Basic Display API for your apps.


Before diving into the setup process, make sure you have the following prerequisites:

  • ProcessWire >= 2.7
  • A Facebook Developer account
  • Access to an Instagram user account

Creating a Facebook App

To get started, you need to create a Facebook App for the Instagram Basic Display API. Follow these simple steps:

  1. Login to your account at
  2. Go to “My Apps” and click on “Create App”.
  3. Select the app type and make sure to choose “Consumer” to access the correct product.
  4. Provide a display name for your app. Avoid using reserved words like Instagram, IG, Insta, or Facebook.
  5. Add an App Contact Email if it’s not already populated.
  6. Click “Create App” and complete the Security Check if required.
  7. Add the “Instagram Basic Display” product to your app.

Configure the Facebook App

Once you have created the Facebook App, it’s time to configure it. Follow these steps:

  1. Scroll to the bottom of the page and click “Add Platform”.
  2. Select “Website” as the platform.
  3. Enter the URL of the site where you will be using the module. If you plan to use it on multiple sites, use your company’s website.
  4. Save the changes.
See also  Introducing ProgramMatek: Revolutionizing CBDC Payments with API Innovation

Feel free to add any additional information, such as an App Icon, to enhance your app’s appearance.

Basic Display Configuration

Now that your Facebook app is ready, it’s time to configure it to access the Instagram Basic Display API. Here’s how:

  1. Create an Instagram Basic Display App within the Facebook app.
  2. Configure the required settings for the app, such as Valid OAuth Redirect URI, Deauthorize Callback URL, and Data Deletion Request URL. These URLs are essential for handling deauthorization and data deletion requests.
  3. Add the Instagram user account to the app by going to Roles > Instagram Testers. Enter the username of the account you want to add, and click “Submit”.
  4. Login to the Instagram Account through
  5. Navigate to Settings > Apps and Websites. Click the username to go to the profile and then click the “cog” icon.
  6. Click on “Tester Invites” and then click “Accept” for the app you have created.
  7. Go back to the App Dashboard and navigate to Instagram > Basic Display > User Token Generator.
  8. You should see the user account listed there. Click on “Generate Token”.
  9. If necessary, log in to the Instagram Account again or click the continue button.
  10. Authorize the app by clicking “Authorize”.
  11. Check “I Understand” and copy the generated token. Save it as you will need it later to configure the module.

Please note that these instructions were accurate as of March 2020. If you come across any changes to the Facebook Developer platform, please let us know on the Support Forum.

Module Configuration

After installing the module, follow these steps to configure it:

  1. Go to Modules > Configure > InstagramBasicDisplayApi.
  2. Add the username and generated token to “Add an Instagram User Account”.
  3. Click “Submit”.
  4. If successful, you should now see the account information in the Authorized Accounts section.
See also  API Contract Testing: Ensuring Seamless Communication between API Consumer and Producer

You can add as many accounts as you wish, as long as you have a token generated in your app. The access token will be automatically renewed within a week of expiry.


The Instagram Basic Display API provides several methods to retrieve user information, images, videos, and albums. Here are some important methods:


Use this method to retrieve a user’s profile information. It returns an associative array with fields such as username, id, account_type, and media_count.

getImages($username, $limit)

Retrieve a list of images for a user using this method. It returns a WireArray of WireData objects, each containing properties like id, type, alt, src, tags, created, and link.


This method fetches the most recent Carousel Album for a user. It returns a WireData object with properties similar to getImage(). Additionally, it includes a children property that contains a WireArray of the album’s images.

getCarouselAlbums($username, $limit)

Retrieve a list of Carousel Albums for a user using this method. It returns a WireArray of WireData objects, each with properties similar to getImage(). Each item also includes a children property with an array of the album’s images.


Fetch the most recent video for a user with this method. It returns a WireData object with properties similar to getImage(). Additionally, it includes a poster property that represents the media’s thumbnail image URL.

getVideos($username, $limit)

Retrieve a list of videos for a user using this method. It returns a WireArray of WireData objects, each with properties similar to getImage(). Each item also includes a poster property representing the media’s thumbnail image URL.

getMedia($username, $limit)

Fetch a list of media for a user using this method. You can use this method to create multi-media galleries using UIkit Grid, Cover, and Lightbox components.


Lazy loading of items can be achieved using the getMedia() method. You can return batches of items using AJAX requests. Here’s an example implementation in PHP and JavaScript:

// PHP
// Javascript

Feel free to customize the JavaScript implementation according to your preferences and libraries.

See also  Introducing the API: Your Gateway to Cyber Exposure Management

Backwards Compatibility with Instagram Feed

If you have been using the Instagram Feed module, don’t worry! This module provides backward compatibility with some of the methods provided by Instagram Feed. Here are the replicated methods:

  • getRecentMedia($username): Retrieve the most recent media published by a user.
  • getRecentMediaByTag($tag, $username): Get a list of recently tagged media.
  • setImageCount($imageCount): Set the image count.
  • getRecentComments($media): Get recent comments. (Returns a blank array since comments cannot be accessed by the Instagram Basic Display API).
  • getUserIdByUsername($username): Get the user’s ID from their username.

Upgrading to Instagram Basic Display API

If you were using Instagram Feed and want to upgrade to the Instagram Basic Display API, follow these steps:

  1. Install and set up this module.
  2. Change the module call in your code to the new module.
  3. If you had modified the default image count, use the setImageCount() method to retain the desired number.
  4. Test thoroughly before deploying the upgrade.

Please note that the Basic Display API may return slightly different data values compared to the deprecated API. However, for most use cases, the differences will be minimal, with some values now returning as null.


Here are a few additional notes to keep in mind:

  • By default, 24 media items are returned in each API call, but you can adjust this in the module configuration. It’s not recommended to return more than 10,000 items at once.
  • For methods related to Instagram Feed, like getRecentMedia(), the default is to return 4 items, matching the default in this module.
  • Some examples shown may not work on older versions of ProcessWire.

Now that you have a clear understanding of the Instagram Basic Display API and how to set it up and use it, you can start integrating Instagram user data into your Facebook apps effortlessly. For more details visit ProgramMatek.