The Socialinsider Analytics API can be used to programatically retrieve data from the social profiles added to your Socialinsider account.
\nThis API is based on JSON-RPC.
\nTo get your API key please reach out to your Account Manager.
\nYou'll authenticate the calls to the Socialinsider API by providing your API key in the request header: Authorization: Bearer Never share the API key. Keep it secure.
\nAlso - make sure to set the \"Content-Type\" header to \"application/json\" Eg: Content-Type: application/json
\nProfile - this is the basic unit in Socialinsider: a social profile.
Can be one of a:
Facebook page (competitor or owned)
\nInstagram business profile (competitor or owned)
\nTwitter profile (competitor or owned)
\nYouTube channel
\nTikTok profile
\nLinkedIn business page.
\nYou can add profiles to projects to group them - for instance each client of an agency can have a project where all the profiles related to that client reside.
\nIn the Socialinsider app you can add the profiles by their social url or handle for most of the social networks (eg. https://www.facebook.com/netflix)
\nA profile contains the following info:
\nid - this is what you will use in API calls to get posts and metrics
\nname
\nprofile_type. Can be one of 'facebook_page', 'facebook_page_own', 'instagram_profile', 'instagram_profile_own', 'twitter_profile', 'twitter_profile_own', 'youtube_channel', 'linkedin_page', 'tiktok_profile'
\nprofile_added. The date when the profile was added to Socialinsider.
\nThe ids are on different platforms:
\nFacebook: the name is the page id that the Facebook API returns ex: 1427239247394
\nInstagram: the name is the instagram username ex: netflix
\nTwitter: the name is the id_str field that the Twitter API returns ex: 584372
\nLinkedIn: the name is the business page id returned by the LinkedIn API
\nYouTube: the name is the channel id
\nTikTok: the name is the username of the profile ex: washingtonpost
\nThe names are on different platforms:
\nFacebook: the name is either the field name or username or global_brand_page_name
\nInstagram: the name is the Instagram username ex: netflix
\nTwitter: the name is the name of the profile returned by the Twitter ex: netflix
\nLinkedIn: the name is the business page name returned by the LinkedIn API
\nYouTube: the name is the channel title
\nTikTok: the name is the username of the profile ex: washingtonpost
\nProject - a logical way of grouping related profiles.
\nPost - these are the social posts that a profile publishes and that we retrieve.
\nCampaign (tag) - You can assign to each post one (or more) campaigns or tags.
This way you can group several logically related posts ie. 'black friday' posts and report on their performance.
Brand - another way of grouping social profiles that belong to the same company, within a project.
\nFor instance, if your client is Netflix and you add the client's 5 social profiles (facebook, instagram, twitter, youtube and tiktok) to a project with the name 'Streaming services'.
Then you can add some of its competitors like Hulu and HBO and their social profiles and group them into their respective brands.
The project structure will look like this:
\nProject: \n{\n \"projectname\": \"Streaming services\"\n \"profiles\": [\n {\n \"id\": \"134983140934\",\n \"name\": 'netflix',\n ...\n },\n {\n \"name\": \"hulu\",\n ...\n }\n ...\n ],\n \"brands\": [\n {\n \"brandname\": \"netflix\",\n \"profiles\": [] \n }\n ...\n ]\n}\n\nThe date object has the fields:
\n{\n start: [timestamp milliseconds],\n end: [timestamp milliseconds],\n timezone: [IANA Timezone]\n}\n\nThe dates (start and end) should be sent as a unix timestamp - in milliseconds (Eg: 1524830695000)
\nThe timezones should be sent in IANA formatconsole.log(Intl.DateTimeFormat().resolvedOptions().timeZone)
More info on timezones:
\nTwitter API does not allow to get tweets, only tweet IDS and you need to hydrate the tweets on your end
\nFollowers evolution is not available for history periods. Only for Facebook pages that are authorised is this available
\nInstagram limitations: All engagement is organic
\nInstagram limitations: Stories are only available after an Instagram business profile was authorised
\nParams: None
\nPossible error reasons
\nThe answer is an array with Projects. Each project has the following structure:
\nprojectname - Name of the project for which you want the list of brands
\nprofiles [array] - the profiles in the project
\nid: String - the profile id
\nname: String - the profile name
\nprofile_type: String - the profile type
\nprofile_added: Date - the date the profile was added in this format: 2021-07-19T07:17:42.779Z
\nParams:
\nsocialinsider_api.get_profiles call for which you want the list of brandsResponse:
\nThe response contains an array of brands with the following structure:
\nbrandname : String - the name of the brand
\nprofiles [array] - the profiles in the project
\nid: String - the profile id
\nname: String - the profile name
\nprofile_type: String - the profile type
\nprofile_added: Date - the date the profile was added in this format: 2021-07-19T07:17:42.779Z
\nParams:
\nResponse
\nParams:
\nid: string - mandatory - a profile id returned by calling socialinsider_api.get_profiles.
profile_type: string - mandatory - the profile type returned by calling socialinsider_api.get_profiles.
date: - mandatory - Object defining the time range to get the posts from
\nstart: [timestamp]
\nend: [timestamp]
\ntimezone: [IANA Timezone]
\nprojectname : - mandatory - Name of the project received from the socialinsider_api.get_profiles call for which you want the list of posts
from: int - optional, defaults to 0. Where to start post fetching from - we can only return a maximum of 50 posts at a time and this is used for paging.
\nsize: int - optional, defaults to 50. How many posts should be retrieved per request - maximum is 50, numbers larger than 50 will default to 50.
\ncampaign_name: string - optional - the name of the campaign returned by calling socialinsider_api.get_campaigns. Use this to get only the posts tagged under this campaign.
Possible error reasons:
\nthe requested profile id doesn't exist in the profiles the user monitors
\ndata incomplete from Facebook - especially if getting posts for a very long period
\ninternal errors
\nData from Twitter is dehydrated and won't contain any user or tweet information.
\nResponse:
\nposts : [Array] : Array containg the posts info:
\nParams:
\nid: string - mandatory - a profile id return by calling socialinsider_api.get_profiles.
date: - mandatory - Object defining the time range to get the posts from
\nstart: [timestamp]
\nend: [timestamp]
\ntimezone: [IANA Timezone]
\nprofile_type: string - mandatory - the profile id returned by calling socialinsider_api.get_profiles.
Possible error reasons
\nprofile does not exist
\nprofile not yet scanned
\ninternal errors probably due to database issues
\nThe response will contain a metrics field that will be an array of day Objects.
\nEach Object will contain data for the specific day mentioned in the day field:
Params:
\nsocialinsider_api.profile_search.Possible error reasons
\ninternal error
\nsearch_string empty
\nthis function does not work for this api key: API_KEY_TEST
The answer is an object with the following structure:
\nAfter you call the add_profile API call the profile is scheduled to refresh the data.
Usually the data for the last year is ready in less than 10 minutes but sometimes it may take longer depending on the system load.
Params:
\nprofile_url: string - mandatory - a profile url returned by calling socialinsider_api.profile_search.
profile_type: string - mandatory - the profile type returned by calling socialinsider_api.profile_search.
projectname - mandatory - Name of the project received from the socialinsider_api.get_profiles call for which you want the list of brands
history_refresh_months: int - optional, defaults to 12 months. How much past posts, in months, to retrieve
\nPossible error reasons
\ninternal error
\nthis function does not work for this api key: API_KEY_TEST
Params:
\nid: string - mandatory - a profile id return by calling socialinsider_api.get_profiles.
profile_type: string - mandatory - the profile id returned by calling socialinsider_api.get_profiles.
projectname - mandatory - Name of the project received from the socialinsider_api.get_profiles call for which you want the list of brands
Possible error reasons
\ninternal error
\nthis function does not work for this api key: API_KEY_TEST
The response is the success status or the error description
\n","auth":{"type":"apikey","apikey":{"value":"Limitations:
\nthis api function call only works for instagram business accounts that are authorised (not for competitions account)
\nthis api function call does not return stories from the history period when the account was not authorised
\nParams:
\nid: string - mandatory - a profile id returned by calling socialinsider_api.get_profiles.
profile_type: string - mandatory - the profile type returned by calling socialinsider_api.get_profiles.
date: - mandatory - Object defining the time range to get the stories from
\nstart: [timestamp]
\nend: [timestamp]
\ntimezone: [IANA Timezone]
\nfrom: int - optional, defaults to 0. Where to start story fetching from - we can only return a maximum of 50 stories at a time and this is used for paging.
\nsize: int - optional, defaults to 50. How many stories should be retrieved per request - maximum is 50, numbers larger than 50 will default to 50.
\nPossible error reasons:
\nthe requested profile id doesn't exist in the profiles the user monitors
\nwrong profile type
\ninternal errors
\nDefault version if you are using the legacy Socialinsider API
\n","_postman_id":"a2c80123-cb18-41e7-9824-bc4961db9796","auth":{"type":"apikey","apikey":{"value":"Params: None
\nPossible error reasons
\nThe answer is an array with Projects. Each project has the following structure:
\nprojectname - Name of the project for which you want the list of brands
\nprofiles [array] - the profiles in the project
\nid: String - the profile id
\nname: String - the profile name
\nprofile_type: String - the profile type
\nprofile_added: Date - the date the profile was added in this format: 2021-07-19T07:17:42.779Z
\nParams:
\nsocialinsider_api.get_profiles call for which you want the list of brandsResponse:
\nThe response contains an array of brands with the following structure:
\nbrandname : String - the name of the brand
\nprofiles [array] - the profiles in the project
\nid: String - the profile id
\nname: String - the profile name
\nprofile_type: String - the profile type
\nprofile_added: Date - the date the profile was added in this format: 2021-07-19T07:17:42.779Z
\nParams:
\nResponse
\nid: string - mandatory - a profile id returned by calling socialinsider_api.get_profiles.
profile_type: string - mandatory - the profile type returned by calling socialinsider_api.get_profiles.
date: - mandatory - Object defining the time range to get the posts from
\nstart: [timestamp]
\nend: [timestamp]
\ntimezone: [IANA Timezone]
\nprojectname : - mandatory - Name of the project received from the socialinsider_api.get_profiles call for which you want the list of posts
from: int - optional, defaults to 0. Where to start post fetching from - we can only return a maximum of 50 posts at a time and this is used for paging.
\nsize: int - optional, defaults to 50. How many posts should be retrieved per request - maximum is 50, numbers larger than 50 will default to 50.
\ncampaign_name: string - optional - the name of the campaign returned by calling socialinsider_api.get_campaigns. Use this to get only the posts tagged under this campaign.
Possible error reasons:
\nthe requested profile id doesn't exist in the profiles the user monitors
\ndata incomplete from Facebook - especially if getting posts for a very long period
\ninternal errors
\nData from Twitter is dehydrated and won't contain any user or tweet information.
\nposts : [Array] : Array containg the posts info:
\nParams:
\nid: string - mandatory - a profile id return by calling socialinsider_api.get_profiles.
date: - mandatory - Object defining the time range to get the posts from
\nstart: [timestamp]
\nend: [timestamp]
\ntimezone: [IANA Timezone]
\nprofile_type: string - mandatory - the profile id returned by calling socialinsider_api.get_profiles.
projectname: string - mandatory - Name of the project received from the socialinsider_api.get_profiles call for which you want the list of brands
Possible error reasons
\nprofile does not exist
\nprofile not yet scanned
\nproject name is missing or incorrect
\ninternal errors probably due to database issues
\nThe response will contain a metrics field that will be an array of day Objects.
\nEach Object will contain data for the specific day mentioned in the day field:
Params:
\nsocialinsider_api.profile_search.Possible error reasons
\ninternal error
\nsearch_string empty
\nthis function does not work for this api key: API_KEY_TEST
The answer is an object with the following structure:
\nAfter you call the add_profile API call the profile is scheduled to refresh the data.
Usually the data for the last year is ready in less than 10 minutes but sometimes it may take longer depending on the system load.
Params:
\nprofile_url: string - mandatory - a profile url returned by calling socialinsider_api.profile_search.
profile_type: string - mandatory - the profile type returned by calling socialinsider_api.profile_search.
projectname - mandatory - Name of the project received from the socialinsider_api.get_profiles call for which you want the list of brands
history_refresh_months: int - optional, defaults to 12 months. How much past posts, in months, to retrieve
\nPossible error reasons
\ninternal error
\nthis function does not work for this api key: API_KEY_TEST
Params:
\nid: string - mandatory - a profile id return by calling socialinsider_api.get_profiles.
profile_type: string - mandatory - the profile id returned by calling socialinsider_api.get_profiles.
projectname - mandatory - Name of the project received from the socialinsider_api.get_profiles call for which you want the list of brands
Possible error reasons
\ninternal error
\nthis function does not work for this api key: API_KEY_TEST
The response is the success status or the error description
\n","auth":{"type":"apikey","apikey":{"value":"Limitations:
\nthis api function call only works for instagram business accounts that are authorised (not for competitions account)
\nthis api function call does not return stories from the history period when the account was not authorised
\nParams:
\nid: string - mandatory - a profile id returned by calling socialinsider_api.get_profiles.
profile_type: string - mandatory - the profile type returned by calling socialinsider_api.get_profiles.
date: - mandatory - Object defining the time range to get the stories from
\nstart: [timestamp]
\nend: [timestamp]
\ntimezone: [IANA Timezone]
\nfrom: int - optional, defaults to 0. Where to start story fetching from - we can only return a maximum of 50 stories at a time and this is used for paging.
\nsize: int - optional, defaults to 50. How many stories should be retrieved per request - maximum is 50, numbers larger than 50 will default to 50.
\nPossible error reasons:
\nthe requested profile id doesn't exist in the profiles the user monitors
\nwrong profile type
\ninternal errors
\nVersioned URLs: https://app.socialinsider.io/api/v1 and https://app.socialinsider.io/api/v2 are now available for querying data, the original URL is still available and will default to the v1 API (for now)
The get_profile_data endpoint now requires the projectname parameter and the data returned has a different format
The get_posts endpoint has a more consistent response across all platforms
Params: None
\nPossible error reasons
\nThe answer is an array with Projects. Each project has the following structure:
\nprojectname - Name of the project for which you want the list of brands
\nprofiles [array] - the profiles in the project
\nid: String - the profile id
\nname: String - the profile name
\nprofile_type: String - the profile type
\nprofile_added: Date - the date the profile was added in this format: 2021-07-19T07:17:42.779Z
\nParams:
\nsocialinsider_api.get_profiles call for which you want the list of brandsResponse:
\nThe response contains an array of brands with the following structure:
\nbrandname : String - the name of the brand
\nprofiles [array] - the profiles in the project
\nid: String - the profile id
\nname: String - the profile name
\nprofile_type: String - the profile type
\nprofile_added: Date - the date the profile was added in this format: 2021-07-19T07:17:42.779Z
\nParams:
\nResponse
\nid: string - mandatory - a profile id returned by calling socialinsider_api.get_profiles.
profile_type: string - mandatory - the profile type returned by calling socialinsider_api.get_profiles.
date: - mandatory - Object defining the time range to get the posts from
\nstart: [timestamp]
\nend: [timestamp]
\ntimezone: [IANA Timezone]
\nprojectname : - mandatory - Name of the project received from the socialinsider_api.get_profiles call for which you want the list of posts
from: int - optional, defaults to 0. Where to start post fetching from - we can only return a maximum of 50 posts at a time and this is used for paging.
\nsize: int - optional, defaults to 50. How many posts should be retrieved per request - maximum is 50, numbers larger than 50 will default to 50.
\ncampaign_name: string - optional - the name of the campaign returned by calling socialinsider_api.get_campaigns. Use this to get only the posts tagged under this campaign.
Possible error reasons:
\nthe requested profile id doesn't exist in the profiles the user monitors
\ndata incomplete from Facebook - especially if getting posts for a very long period
\ninternal errors
\nData from Twitter is dehydrated and won't contain any user or tweet information.
\nposts : [Array] : Array containg the posts info:
\nParams:
\nid: string - mandatory - a profile id return by calling socialinsider_api.get_profiles.
date: - mandatory - Object defining the time range to get the posts from
\nstart: [timestamp]
\nend: [timestamp]
\ntimezone: [IANA Timezone]
\nprofile_type: string - mandatory - the profile id returned by calling socialinsider_api.get_profiles.
projectname: string - mandatory - Name of the project received from the socialinsider_api.get_profiles call for which you want the list of brands
Possible error reasons
\nprofile does not exist
\nprofile not yet scanned
\nproject name is missing or incorrect
\ninternal errors probably due to database issues
\nThe response will contain a metrics field that will be an array of day Objects.
\nEach Object will contain data for the specific day mentioned in the day field:
Params:
\nsocialinsider_api.profile_search.Possible error reasons
\ninternal error
\nsearch_string empty
\nthis function does not work for this api key: API_KEY_TEST
The answer is an object with the following structure:
\nAfter you call the add_profile API call the profile is scheduled to refresh the data.
Usually the data for the last year is ready in less than 10 minutes but sometimes it may take longer depending on the system load.
Params:
\nprofile_url: string - mandatory - a profile url returned by calling socialinsider_api.profile_search.
profile_type: string - mandatory - the profile type returned by calling socialinsider_api.profile_search.
projectname - mandatory - Name of the project received from the socialinsider_api.get_profiles call for which you want the list of brands
history_refresh_months: int - optional, defaults to 12 months. How much past posts, in months, to retrieve
\nPossible error reasons
\ninternal error
\nthis function does not work for this api key: API_KEY_TEST
Params:
\nid: string - mandatory - a profile id return by calling socialinsider_api.get_profiles.
profile_type: string - mandatory - the profile id returned by calling socialinsider_api.get_profiles.
projectname - mandatory - Name of the project received from the socialinsider_api.get_profiles call for which you want the list of brands
Possible error reasons
\ninternal error
\nthis function does not work for this api key: API_KEY_TEST
The response is the success status or the error description
\n","auth":{"type":"apikey","apikey":{"value":"Limitations:
\nthis api function call only works for instagram business accounts that are authorised (not for competitions account)
\nthis api function call does not return stories from the history period when the account was not authorised
\nParams:
\nid: string - mandatory - a profile id returned by calling socialinsider_api.get_profiles.
profile_type: string - mandatory - the profile type returned by calling socialinsider_api.get_profiles.
date: - mandatory - Object defining the time range to get the stories from
\nstart: [timestamp]
\nend: [timestamp]
\ntimezone: [IANA Timezone]
\nfrom: int - optional, defaults to 0. Where to start story fetching from - we can only return a maximum of 50 stories at a time and this is used for paging.
\nsize: int - optional, defaults to 50. How many stories should be retrieved per request - maximum is 50, numbers larger than 50 will default to 50.
\nPossible error reasons:
\nthe requested profile id doesn't exist in the profiles the user monitors
\nwrong profile type
\ninternal errors
\n