A source represents a connection to Instagram. There are two types of sources: Basic and Advanced. Advanced sources may have one or more associated Instagram accounts. To learn more see Basic vs Advanced Sources.
You cannot create a source directly. Instead, a source is added to your account when a user visits your unique auth link and authorizes Behold to access their Instagram account.
The source object
Shared attributes
These attributes are common to both Basic and Advanced sources.
id string
Unique source ID.
For a Basic source, this ID is the same as the underlying Instagram Account ID. Because of this, it is possible for a Basic source and an associatedAccount within an Advanced source to share the same ID.
customId nullable string
This is a custom ID you can define. It’s useful for associating Behold sources with entities in your DB. customId is added during the auth process and cannot be changed. See connecting to instagram.
type enum
The type of source. One of instagramBasic or instagramAdvanced.
label string
A label for this source. For basic sources this is the Instagram username. For advanced sources, it is either the name of the connected Facebook business portfolio or user.
expiresOn nullable timestamp
Advanced sources connected through a Facebook user need to be manually reauthorized every three months. This field contains the expiration date,in the form of a UNIX timestamp. For other sources this will be null.
needsReauth boolean
If this source has been disconnected from Instagram for any reason (i.e. its access token was invalidated), this will be true.
Basic attributes
Basic sources have all shared attributes plus the following:
username string
The Instagram username.
name nullable string
The name field set in Instagram.
website nullable string
The website field set in Instagram.
biography nullable string
The biography field set in Instagram.
profilePicture nullable string
The Instagram profile picture saved as a 500 x 500 .webp image.
followsCount integer
The number of other accounts this account is following.
followersCount integer
The number of followers this account has.
mediaCount integer
The total number of posts this account has published.
Advanced attributes
Advanced sources have all shared attributes plus an associatedAccounts field:
associatedAccounts array of AssociatedAccounts
This contains an array of associated accounts. These are Instagram accounts attached to this source that can be used to create feeds. Associated accounts share all attributes with Basic sources except type, expiresOn, and needsReauth. In addition to their shared attributes, associated accounts have a recentlyQueriedHashtags field.
Show child attributes Hide child attributes
recentlyQueriedHashtags array of strings
This lists the hashtag queries made on behalf of this account over the past 7 days. Each Instagram account may only access up to 30 hashtags in a 7 day window.
Retrieve a source
GET /sources/:sourceId
Parameters
Accepts no parameters.
Return value
Returns a JSON object containing all fields for a single source.
Example request
curl https://api.behold.so/v1/sources/122098019756544079 \-H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN'{ "data": { "id": "122098019756544079", "customId": "some_unique_id", "type": "instagramBasic", "label": "u.i.ball", "needsReauth": false, "expiresOn": null, "username": "u.i.ball", "name": "UI Ball", "website": "https://uiball.com/ldrs", "biography": "Useful things for devs.", "profilePicture": "https://cdn2-dev.behold.pictures/DTA3oeYySObcTfR3swjtVD5JYbC2/17841452707186857/profile.webp", "followsCount": 2, "followersCount": 102, "mediaCount": 3, }}{ "data": { "id": "122098019756544079", "customId": "some_unique_id", "type": "instagramAdvanced", "label": "Behold", "needsReauth": false, "expiresOn": null, "associatedAccounts": [ { "id": "17841429465705030", "username": "behold.social", "label": "behold.social", "biography": "Fetch Instagram posts with your front-end JavaScript. No server-side code. No expiring tokens or app reviews. No worries.", "profilePicture": "https://cdn2-dev.behold.pictures/DTA3oeYySObcTfR3swjtVD5JYbC2/17841429465705030/profile.webp", "name": "Behold", "website": "https://behold.so/", "mediaCount": 74, "followersCount": 64, "followsCount": 2, "recentlyQueriedHashtags": [ "castles" ] } ] }}List all sources
Returns all available sources, sorted by label in ascending alphabetical order.
GET /sources
Parameters
limit integer
Limits the number of responses. Limit can range between 1 and 100. The default is 10.
fields comma-delimited string
Specifies a subset of fields to return. Set to all to return all fields. The default is id.
associatedAccounts_fields comma-delimited string
Specifies a subset of associated account subfields to return. Set to all to return all subfields. The default is id. When this parameter is set, associatedAccounts will always be returned even if not listed in fields.
cursor string
See pagination.
Return value
Returns an array of all available sources.
Example request
curl -G https://api.behold.so/v1/sources \-H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN'\-d limit=2 \-d fields="customId,type,label,website,followersCount,associatedAccounts" \-d associatedAccounts_fields="label,website,followersCount"{ "data": [ { "id": "122098019756544079", "customId": "some_unique_id", "type": "instagramAdvanced", "label": "Behold", "associatedAccounts": [ { "id": "17841429465705030", "label": "behold.social", "website": "https://behold.so/", "followersCount": 64 } ] }, { "id": "17841429465705030", "customId": null, "type": "instagramBasic", "label": "behold.social", "website": "https://behold.so/", "followersCount": 64 } ], "cursors": { "before": null, "after": "bmV4dDpiZWhvbGQuc29jaWFsOjE3ODQxNDI5NDY1NzA1MDMw" }}Delete a source
DELETE /sources/:sourceId
Deletes a single source. This will also delete any feeds using this source.
Parameters
Accepts no parameters.
Return value
Returns a JSON object containing the id and label of the source.
Example request
curl -X DELETE https://api.behold.so/v1/sources/122098019756544079 \-H "Authorization: Bearer YOUR_API_ACCESS_TOKEN"{ "data": { "id": "122098019756544079", "label": "Behold" }}