JSON API
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. 🤷