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.

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.

Allowed post types

This setting lets you choose which post types to include in your feed, from among images, videos , reels and albums.

Caption must include

Only posts that contain at least one of the text snippets you add here will be included in your feed. This is case-sensitive and can include spaces.

Caption may not include

Only posts that do not contain any of the text snippets you add here will be included in your feed. This is case-sensitive and can include spaces.

Hashtag feeds can take a few minutes to preload when combined with this setting.

Domain whitelist

This option blocks feed requests that do not originate from one of the whitelisted domains. If you leave this blank, all requests are allowed.

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": "Photo by Chuttersnap on @unsplash ---- #photography #leica #photooftheday",
        "prunedCaption": "Photo by Chuttersnap on @unsplash",
        "hashtags": [
          'photography',
          'leica',
          'photooftheday'
        ],
        "mentions":[
          'unsplash'
        ],
        "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 full original post caption

prunedCaption string

The post caption with hashtags removed. We also try to remove trailing separators and whitespace. This is a new feature that relies on regex, so please let us know if you notice any weird behavior: support@behold.so

hashtags array

An array of hashtags extracted from the post caption with the # removed

mentions array

An array of user mentions extracted from the post caption with the @ removed

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