JSON API | Behold documentation

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

How it works

We like to keep it simple. Just connect an Instagram account through our dashboard, create a feed, and we give you a JSON array of Instagram posts at a unique URL. Like this:

https://feeds.behold.so/xN3J7TZ59jIdH6IOWQ4d

Pop that into your browser or Postman.

We handle API keys, usage limits, and creating and refreshing access tokens, so you can skip the annoying stuff and get developing. As an added benefit, caching means our feeds are significantly faster than accessing Facebook's APIs directly.

Creating a feed

First, connect an account. Use the Basic API to pull posts from a single Instagram account. If you want to show a feed of public hashtag posts, connect using the Graph API.
Click "+ Add Feed" in the Behold dashboard. Choose "API", and pick a name for your feed.
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.

Refresh Rate

How often we check Instagram for new posts. On the free plan, feeds are freshed every 24 hours. On paid plans, your feed can refresh as often as once a minute.

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 API Response format

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

[
  {
    "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",
    "children": null
  },
  {
    "id": "17897966131570240",
    "mediaUrl": "https://scontent-iad3-1.cdninstagram.com/v/t51.29350-15/118766727_828605931210911_8645556774478435660_n.jpg?_nc_cat=106&ccb=1-5&_nc_sid=8ae9d6&_nc_ohc=KY4VEZCLX6EAX_hp-UQ&_nc_ht=scontent-iad3-1.cdninstagram.com&edm=ANo9K5cEAAAA&oh=00_AT-21f51jmxK4h-KOMrRFv4aeLkKHEuSrZ90Adu9dN0Egg&oe=62301104",
    "permalink": "https://www.instagram.com/p/CEuzlWihI5S/",
    "caption": "Alireza Etemadi",
    "mediaType": "IMAGE",
    "timestamp": "2020-09-04T22:26:51+0000",
    "children": null
  },
]

Basic API feeds contain the following fields:

id

The unique id of this Instagram post

mediaUrl

The image or video source

permalink

The URL of the post on Instagram

caption

The post caption

mediaType

Can be IMAGE, VIDEO, or CAROUSEL_ALBUM

thumbnailUrl

A thumbnail image for video posts

timestamp

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

children

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:

{
  "id": "18281658007027366",
  "mediaUrl": "https://scontent-mia3-2.cdninstagram.com/v/t51.29350-15/273863189_429470108967588_2655780465161783753_n.webp?stp=dst-jpg&_nc_cat=109&ccb=1-5&_nc_sid=8ae9d6&_nc_ohc=fRTzf5wboDUAX92KJ2f&_nc_ht=scontent-mia3-2.cdninstagram.com&edm=ANo9K5cEAAAA&oh=00_AT-zitiX8TINdigh2UB2QMtPuNZHJN3NdGJGlyXrf9ZM4Q&oe=622FB907",
  "permalink": "https://www.instagram.com/p/CZ7_Oh0onhM/",
  "caption": "What a beautiful place! I'll be back. The first photo is of El Peñon del Diablo — which means exactly what you're thinking. Incredible place to fly.",
  "mediaType": "CAROUSEL_ALBUM",
  "timestamp": "2022-02-14T00:18:00+0000",
  "children": [
    {
      "id": "17929624046073995",
      "mediaUrl": "https://scontent-mia3-2.cdninstagram.com/v/t51.29350-15/273863189_429470108967588_2655780465161783753_n.webp?stp=dst-jpg&_nc_cat=109&ccb=1-5&_nc_sid=8ae9d6&_nc_ohc=fRTzf5wboDUAX92KJ2f&_nc_ht=scontent-mia3-2.cdninstagram.com&edm=ANo9K5cEAAAA&oh=00_AT-zitiX8TINdigh2UB2QMtPuNZHJN3NdGJGlyXrf9ZM4Q&oe=622FB907",
      "mediaType": "IMAGE"
    },
    {
      "id": "17910334703282900",
      "mediaUrl": "https://scontent-mia3-2.cdninstagram.com/v/t51.29350-15/273841175_1068968236996980_6737857674883977687_n.webp?stp=dst-jpg&_nc_cat=103&ccb=1-5&_nc_sid=8ae9d6&_nc_ohc=f0asuaAMf2sAX8g5MK_&_nc_ht=scontent-mia3-2.cdninstagram.com&edm=ANo9K5cEAAAA&oh=00_AT92qUULlK1Ls57hz6bmUrI-Hr1Q88OWAU1J-IgDwhx5YA&oe=622F3997",
      "mediaType": "IMAGE"
    },
    {
      "id": "17911825247247889",
      "mediaUrl": "https://scontent-mia3-1.cdninstagram.com/v/t51.29350-15/273812260_372298824735432_7542596973936841896_n.webp?stp=dst-jpg&_nc_cat=100&ccb=1-5&_nc_sid=8ae9d6&_nc_ohc=KpEDlwvWFSQAX-nShDY&_nc_ht=scontent-mia3-1.cdninstagram.com&edm=ANo9K5cEAAAA&oh=00_AT-E58Xf6_bes5qmsQxCNxtP4WoAkBCbvn-OeviV55zU3Q&oe=622EE1F2",
      "mediaType": "IMAGE"
    }
  ]
}

Graph API Response format

Graph API 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
    },
    {
      "id": "17897966131570240",
      "mediaUrl": "https://scontent-iad3-1.cdninstagram.com/v/t51.29350-15/118766727_828605931210911_8645556774478435660_n.jpg?_nc_cat=106&ccb=1-5&_nc_sid=8ae9d6&_nc_ohc=KY4VEZCLX6EAX_hp-UQ&_nc_ht=scontent-iad3-1.cdninstagram.com&edm=ANo9K5cEAAAA&oh=00_AT-21f51jmxK4h-KOMrRFv4aeLkKHEuSrZ90Adu9dN0Egg&oe=62301104",
      "permalink": "https://www.instagram.com/p/CEuzlWihI5S/",
      "caption": "Alireza Etemadi",
      "mediaType": "IMAGE",
      "timestamp": "2020-09-04T22:26:51+0000",
      "commentsCount": 0,
      "likeCount": 0,
      "children": null
    },
  ]
}

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

The number of comments on this post

likeCount

The number of likes the post has recieved

hashtag (hashtag feeds only)

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. We've reached out to Meta developer support about this multiple times and so far we've only heard crickets. 🤷

id