Documentation
JSON API

JSON API

Get Instagram posts as JSON. No server-side code required. Perfect for SPAs and JAM stack.

How it works

Just connect an Instagram account through our dashboard, create a feed, and we give you Instagram posts at a unique URL. Like this: 

https://feeds.behold.so/zFgp2Jbbk23Ovf1ZUOhq

Pop that into your browser or Postman.

We handle API keys, usage limits, and creating and refreshing access tokens. We also extract and provide some useful metadata.

Creating a feed

  1. First, connect an Instagram account . Use a basic source to pull posts from a single Instagram account. If you want to show a feed of public hashtag posts, connect using an advanced source.
  2. Click + Add Feed in the Behold dashboard. Choose API, and pick a name for your feed. You can change this later.
  3. Click Create feed, and you're all set! Click on your new feed to access your feed URL, settings and a preview of the response.
guide
Basic vs. advanced sources
 guide
Hashtag feeds

Feed settings

Number of Posts

The number of Instagram posts to fetch. This is capped based on your plan. Free plans can fetch up to 6 posts.

Domain whitelist

Your feed will only function on domains listed here, or on any domain if left blank.

Subdomains are independent and wildcards are not supported. So example.com and  www.example.com must be entered separately. The protocol (e.g. https://) is ignored.

localhost is always whitelisted.

Basic source response format

Our feeds are a simple array of post objects. Like this:

[
      {
        "id": "17842915793354225",
        "mediaUrl": "https://scontent-atl3-1.cdninstagram.com/v/t51.29350-15/118702810_419649599012814_4348560261050316974_n.jpg?_nc_cat=105&ccb=1-7&_nc_sid=8ae9d6&_nc_ohc=jNxTogRUd8kAX_-wMOs&_nc_ht=scontent-atl3-1.cdninstagram.com&edm=ANo9K5cEAAAA&oh=00_AT8H1FjdsDBq3PK-a1SF_YV8PF7omHeHuaICYKg2FRiuZw&oe=634566D1",
        "permalink": "https://www.instagram.com/p/CEuzou0hKS2/",
        "caption": "Chuttersnap",
        "mediaType": "IMAGE",
        "timestamp": "2020-09-04T22:27:19+0000",
        "colorPalette": {
          "dominant": "196,104,25",
          "muted": "96,163,124",
          "vibrant": "223,110,18",
          "vibrantLight": "239,189,88",
          "mutedDark": "95,107,60",
          "vibrantDark": "13,104,69",
          "mutedLight": "154,198,159"
        },
        "dimensions": {
          "width": 1080,
          "height": 1080
        }
      },
      ...
    ]

Basic feeds contain the following fields:

id string

The unique id of this Instagram post

mediaUrl string

The image or video source

permalink string

The URL of the post on Instagram

caption string

The post caption

mediaType string

Can be IMAGE, VIDEO, or CAROUSEL_ALBUM

isReel string

Only included in video posts. true for reels. false for regular videos

thumbnailUrl string

A thumbnail image for video posts

timestamp string

The date the post was published on Instagram in ISO 8601 format.

colorPalette object

A range of colors extracted from the post, in R, G, B format. Useful for showing a meaningful placeholder color while the image loads.

dimensions object

Image height and width in pixels

children array

An array of child posts in a CAROUSEL_ALBUM. Each child contains the following fields: id, mediaUrl, and mediaType.

A post with children will look something like this:

{
  "caption": "Carousel of images",
  "timestamp": "2022-05-01T15:50:53+0000",
  "children": [
    {
      "mediaUrl": "https://scontent-atl3-1.cdninstagram.com/v/t51.29350-15/279580576_519034193110826_120328013983193336_n.webp?stp=dst-jpg&_nc_cat=107&ccb=1-7&_nc_sid=8ae9d6&_nc_ohc=w9p3xnLRyWwAX-a9h5L&_nc_ht=scontent-atl3-1.cdninstagram.com&edm=ANo9K5cEAAAA&oh=00_AT-J95wYuyoeEFqp-ZjjLgRAW4aVG_IoE3cyqKbws5FkeQ&oe=6349B667",
      "mediaType": "IMAGE",
      "id": "18022952101351619"
    },
    {
      "id": "17999460013407513",
      "mediaUrl": "https://scontent-atl3-1.cdninstagram.com/v/t51.29350-15/279518272_745312776823637_6844095085570686354_n.webp?stp=dst-jpg&_nc_cat=111&ccb=1-7&_nc_sid=8ae9d6&_nc_ohc=26n8afItV2oAX_0Is2z&_nc_oc=AQkFmZjajZVR69kkbwU4RYiMztvuDPVDjPTxVW9z0b9QrMKVPvBwb1sk4d19nXo5R4M&_nc_ht=scontent-atl3-1.cdninstagram.com&edm=ANo9K5cEAAAA&oh=00_AT95USxxOmvLrVjOv2otFA0a-F9ctdshQL3EkZP14G_yoQ&oe=6349A51C",
      "mediaType": "IMAGE"
    },
  ],
  "mediaType": "CAROUSEL_ALBUM",
  "permalink": "https://www.instagram.com/p/CdBWZsUuLYZlZOH7jnuiYKP1SYL89AxBIT46Dk0/",
  "mediaUrl": "https://scontent-atl3-1.cdninstagram.com/v/t51.29350-15/279580576_519034193110826_120328013983193336_n.webp?stp=dst-jpg&_nc_cat=107&ccb=1-7&_nc_sid=8ae9d6&_nc_ohc=w9p3xnLRyWwAX-a9h5L&_nc_ht=scontent-atl3-1.cdninstagram.com&edm=ANo9K5cEAAAA&oh=00_AT-J95wYuyoeEFqp-ZjjLgRAW4aVG_IoE3cyqKbws5FkeQ&oe=6349B667",
  "id": "17955159928744980",
  "colorPalette": {
    "dominant": "135,174,229",
    "mutedDark": "96,65,56",
    "mutedLight": "168,172,178",
    "vibrantDark": "100,40,33",
    "vibrantLight": "137,183,246",
    "muted": "92,124,167",
    "vibrant": "127,167,224"
  },
  "dimensions": {
    "height": 1440,
    "width": 1440
  }
}

Advanced source response format

Advanced source feeds return some additional metadata about the user, as well as about each post. Like this: 

{
  username: "behold.examples",
  profilePictureUrl: "https://scontent-iad3-2.xx.fbcdn.net/v/t51.0-15/119238229_436802410630400_8430262762081205354_n.jpg?_nc_cat=111&cb=48425d84-d137deea&oh=00_AT_h62nCIp_Ymor_P3QcHPw8cWg3Yo5Pkl6KMYqncO6R7Q&oe=623F36EE&_nc_sid=2801c1",
  website: "https://behold.so/",
  followersCount: 0,
  media: [
    {
      "id": "17842915793354225",
      "mediaUrl": "https://scontent-iad3-1.cdninstagram.com/v/t51.29350-15/118702810_419649599012814_4348560261050316974_n.jpg?_nc_cat=105&ccb=1-5&_nc_sid=8ae9d6&_nc_ohc=vWJyzg5aRvAAX9hARA3&_nc_ht=scontent-iad3-1.cdninstagram.com&edm=ANo9K5cEAAAA&oh=00_AT9elYCdHnwe9aIDlzQXfxp2URCPyqRSaFH8LbyANiPkxg&oe=622E9191",
      "permalink": "https://www.instagram.com/p/CEuzou0hKS2/",
      "caption": "Chuttersnap",
      "mediaType": "IMAGE",
      "timestamp": "2020-09-04T22:27:19+0000",
      "commentsCount": 0,
      "likeCount": 0,
      "children": null,
      "colorPalette": {
        "dominant": "135,174,229",
        "mutedDark": "96,65,56",
        "mutedLight": "168,172,178",
        "vibrantDark": "100,40,33",
        "vibrantLight": "137,183,246",
        "muted": "92,124,167",
        "vibrant": "127,167,224"
      },
      "dimensions": {
        "height": 1440,
        "width": 1440
      }
    },
    ...
  ]
}

As you can see, the array of posts has been moved to the media property, and username, profilePictureUrl, website and followersCount have been added. Hashtag feeds will also include a hashtags field, with an array of hashtags included in the feed.

Additionally, each Graph API post object has some additional fields:

commentsCount number

The number of comments on this post

likeCount number

The number of likes the post has recieved

hashtag string

Hashtag feeds also have the hashtag property, which lists the relevant hashtag associated with the post.

Where's the alt text?

Unfortunately Instagram provides no official way of retrieving alt text at this time.

In most cases images from Instagram are purely decorative. That means that for accessibility purposes you should usually mark them up with an empty alt tag: 

<img src="example.jpg" alt="" />

For more information, read the official WAI recommendations for decorative images.

Ready to give it a try?

Sign up for free