Sources reference

✨ Link copied

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.

✨ Link copied

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"
        ]
      }
    ]
  }
}

✨ Link copied

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"
  }
}

✨ Link copied

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"
  }
}