JSON API
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/zFgp2Jbbk23Ovf1ZUOhqPop 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
- 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.
- Click + Add Feed in the Behold dashboard. Choose API, and pick a name for your feed. You can change this later.
- 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:
The unique id of this Instagram post
The image or video source
The URL of the post on Instagram
The full original post caption
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
An array of hashtags extracted from the post caption with the # removed
An array of user mentions extracted from the post caption with the @ removed
Can be IMAGE, VIDEO, or CAROUSEL_ALBUM
Only included in video posts. true for reels. false for regular videos
A thumbnail image for video posts
The date the post was published on Instagram in ISO 8601 format.
A range of colors extracted from the post, in R, G, B format. Useful for showing a meaningful placeholder color while the image loads.
Image height and width in pixels
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:
The number of comments on this post
The number of likes the post has recieved
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.