Socialbakers API Documentation

Introduction

The Socialbakers API allows access to the data points used in Socialbakers suite. Access to the API is available on request for Socialbakers clients only.

If you are interested in the API access, please contact our support team (support@socialbakers.com).

Changelog

2018/09/10

2018/09/10

2018/09/07

2018/08/10

2018/02/22

2017/10/16

2017/08/16

2017/07/13

2017/05/04

  • new metrics insights_impressions_viral, insights_impressions_viral_frequency_distribution and insights_impressions_viral_unique added for Facebook metrics

2017/03/28

2016/11/23

2016/10/27

  • new metrics viewed_time_change and viewed_time_lifetime added for YouTube metrics

Security and authentication

API is secured with HTTPS. Authentication is made using Basic HTTP authentication with token as username and secret as password.

Token and secret can be obtained from our support team.

Basic HTTP Authorization using token and secret

If we use "Aladdin" as token and "OpenSesame" as secret, "Aladdin:OpenSesame" will produce "QWxhZGRpbjpPcGVuU2VzYW1l" when encoded with base64.

The header would then be: Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

Example request

GET /0/facebook/profiles HTTPS
Host: api.socialbakers.com
Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l
Content-Type: application/json; charset=utf-8

Limits

Rate limits are defined for account and for user:

  • Account: 1000 requests per hour
  • User: 500 requests per hour

Each metrics request is limited by maximum number of:

  • Profiles: 25
  • Metrics: 25
  • Date range: 3 months

Date range is not relative to curent date, so you are able to query historical data.

If you need to query with more profiles, metrics or date range than the limits allow, you can split it into multiple requests.

The oldest historical data you are able to request for is limited by your subscription package.

Errors

If error occurs in any endpoint, standardized error response will be returned.

Error codes

Code Endpoint Description
3 all Input validation error
4 /metrics Profiles, metrics or date range limit exceeded
5 /metrics Profiles not allowed for user
6 /metrics Start date is before history limit date
10 all Account request limit exceeded
11 all User request limit exceeded
99 all An unknown error occurred
400 all Bad request
401 all Missing authorization or invalid token
403 all Action is not permitted
404 all Resource not allowed
405 all HTTP method not allowed
500 all Internal server error
Example response
                {
  "success": false,
  "errors": [
    {
      "code": 3,
      "errors": [
        "Input validation error.",
        "Invalid metrics requested: metric1"
      ]
    },
    {
      "code": 5,
      "errors": [
        "Profiles not allowed for user.",
        "Profiles [12345] not allowed."
      ]
    }
  ]
}

Reference

Below you can find API endpoints with request and response examples.

List of connected profiles

Returns the list of connected Facebook, Instagram, Twitter, YouTube or Pinterest profiles for your account. You will need the profile ID later to call metrics endpoints.

Example request

              GET /0/{network}/profiles HTTPS
Host: api.socialbakers.com
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
Supported values for {network}: facebook, instagram, twitter, youtube, pinterest

Response fields

Name Description
id string, profile unique identifier on the social network.
name string, profile name
profile_name string, profile unique name on the social network.
picture string, profile picture on the social network.
timezone string, timezone selected for this profile in Socialbakers product.
sbks_labels array, list of account labels for given profile.
insights_enabled boolean, available for facebook and instagram networks only, true if insights metrics are available for profile.
Example response
{
  "success": true,
  "profiles": [
    {
      "id": "12345",
      "name": "Profile #1 name",
      "profile_name": "profile1name",
      "picture": "https://example.cdn.com/picture.hash.png"
      "timezone": "America/Los_Angeles",
      "insights_enabled": true
    },
    {
      "id": "54321",
      "name": "Profile #2 name",
      "picture": "https://example.cdn.com/picture.hash.png"
      "profile_name": "profile2name",
      "timezone": "Europe/Prague"
    },
    ...
  ]
}

Facebook metrics

Returns daily metrics for each requested Facebook profile.
* Metrics prefixed with insights_ can only be used for profiles that have insights_enabled property set to true in the response of the /0/facebook/profiles endpoint.

Parameters

Name Description
date_start string, the beginning of the period you want to get the data for in the format YYYY-MM-DD. The timezone is automatically selected from your account.
date_end numeric string, the end of the period you want to get the data for in the format YYYY-MM-DD, selected day will be included in the response. The timezone is automatically selected from your account.
profiles object, the list of numeric string values. Each is ID of the profile available from the /0/facebook/profiles endpoint.
metrics object, the list of metrics that will be returned in the response. Available metrics are listed in the table below.
Metrics
Name Type Example Description
comments_count integer 
100
 Number of comments on page posts.
comments_count_by_paid_status object 
{ "paid": 1, "organic": 2, "unknown": 0 }
 Number of comments on page posts by paid status (organic/paid/unknown) based on PPD.
comments_count_by_type object 
{ "video": 1, "photo": 2 }
 Number of comments on page posts by post type.
fans_change integer 
100
 Absolute change of fans count of a page.
fans_count_lifetime integer 
100
 Total number of likes (=fans) of a page.
fans_count_lifetime_by_country object 
{ "US": 10539639, "BR": 7059801 }
 Lifetime value of number of fans grouped by country.
insights_consumptions_by_type * object 
{ "photo view": 821, "other clicks": 670, "link clicks": 446, "video play": 4 }
 Number of clicks on any of your content, by type. Clicks generating stories are included in "Other Clicks." Stories generated without clicks on page content (e.g., liking the page in Timeline) are not included. Other clicks is defined as 'Clicks not on the content of the post, such as page title clicks or click to see more.
insights_consumptions_count * integer 
1965
 Number of clicks on any of your content. Clicks generating stories are included in "Other Clicks." Stories generated without clicks on page content (e.g., liking the page in Timeline) are not included. (Total Count)
insights_consumptions_unique * integer 
1650
 Number of people who clicked on any of your content. Clicks that create stories are included in "Other Clicks." Stories that are created without clicking on Page content (ex, liking the Page from timeline) are not included. (Unique Users)
insights_consumptions_unique_by_type * object 
{ "photo view": 601, "other clicks": 428, "link clicks": 210, "video play": 4 }
 Number of of people who clicked on any of your content, by type. Clicks that create stories are included in "Other Clicks." Stories that are created without clicking on Page content (ex, liking the Page from timeline) are not included. (Unique Users)
insights_engaged_users_count * integer 
1134
 Number of people who engaged with your Page. Engagement includes any click or story created. (Unique Users).
insights_fan_adds * integer 
280
 Number of new people who have liked your Page.
insights_fan_adds_by_paid_non_paid_unique * object 
{ "total": 280, "paid": 194, "unpaid": 86 }
 New likes by paid and non-paid : Number of new people who have liked your page broken down by paid and non-paid. (Unique Users)
insights_fan_adds_unique * integer 
285
 New Likes : Number of new people who have liked your Page (Unique Users)
insights_fan_removes * integer 
33
 Number of Unlikes of your Page (Total Count)
insights_fan_removes_unique * integer 
32
 Number of Unlikes of your Page (Unique Users)
insights_fans_by_like_source * object 
{ "feed_story": 69, "sponsored_story": 52, "feed_pyml": 50, "page_profile": 71, "ads": 9, "api": 5, "mobile_ads": 4, "vertex_page": 3, "timeline_like_chaining": 3, "search": 1, "timeline_collection": 1 }
 Breakdown of Number of Page likes from the most common places where people can like your Page. (Total Count)
insights_fans_by_like_source_unique * object 
{ "feed_story": 69, "sponsored_story": 52, "feed_pyml": 50, "page_profile": 71, "ads": 9, "api": 5, "mobile_ads": 4, "vertex_page": 3, "timeline_like_chaining": 3, "search": 1, "timeline_collection": 1 }
 Number of people who liked your Page, broken down by the most common places where people can like your Page. (Unique Users)
insights_fans_by_unlike_source_unique * object 
{ "normal_unfan": 20, "deactivated_fan_removal": 1 }
 Number of people who unliked your Page, broken down by the most common places where people can unlike your Page. (Unique Users)
insights_fans_city * object 
{ "São Paulo, SP, Brazil": 7073, "Mexico City, Distrito Federal, Mexico": 6622, "Istanbul, Istanbul Province, Turkey": 5061, "Bangkok, Thailand": 3714, ... }
 Aggregated location data, sorted by city, number of people who like your Page. (Unique Users)
insights_fans_gender_age_lifetime * object 
{ "M.25-34": 61893, "F.25-34": 50721, "M.35-44": 33300, "F.35-44": 22872, "M.18-24": 21956, "F.18-24": 13998, "M.45-54": 12220, "F.45-54": 8169, "M.55-64": 3426, "F.55-64": 2882, "M.65+": 2450, "F.65+": 1687, "F.13-17": 1342, "M.13-17": 1330 }
 Aggregated demographic data about the people who like your Page based on the age and gender information they provide in their user profiles. (Unique Users)
insights_fans_lifetime * integer 
23423234
 Number of people who have liked your Page. (Unique Users)
insights_fans_locale_lifetime * object 
{ "en_US": 94843, "en_GB": 27878, "es_LA": 27558, "pt_BR": 21176, "fr_FR": 7338, ... }
 Aggregated language data about the people who like your Page based on the default language setting selected when accessing Facebook. (Unique Users)
insights_fans_online * integer 
23423234
 Number of people who liked your Page and when they are online (Unique Users)
insights_fans_online_by_hour * object 
{ "0": 83292, "1": 78332, "2": 83660, "3": 91509, "4": 101188, "5": 108478, "6": 113041, "7": 114870, "8": 113888, "9": 110740, "10": 106890, "11": 103823, "12": 102124, "13": 99136, "14": 91921, "15": 81431, "16": 73596, "17": 70081, "18": 69155, "19": 68482, "20": 65979, "21": 66731, "22": 70748, "23": 74399 }
 Number of your fans who saw any posts on Facebook on a given day, broken down by hour of day in PST (Pacific Standard Time)
insights_impressions * integer 
23423234
 Number of impressions seen of any content associated with your Page. (Total Count)
insights_impressions_by_age_gender_unique * object 
{ "M.25-34": 32425, "M.18-24": 25498, "F.25-34": 19674, "F.18-24": 14386, "M.35-44": 11693, "F.35-44": 7029, "M.45-54": 3339, "F.45-54": 2198, "M.55-64": 1317, "M.65+": 1275, "F.55-64": 873, "F.65+": 692, "M.13-17": 31, "F.13-17": 31 }
 Total Page Reach by age and gender. (Unique Users)
insights_impressions_by_paid_non_paid * object 
{ "total": 192630, "paid": 169167, "unpaid": 23463 }
 Number of impressions seen of any content associated with your page broken down by paid and non-paid. (Total Count)
insights_impressions_by_paid_non_paid_unique * object 
{ "total": 119886, "paid": 108459, "unpaid": 11427 }
 Number of impressions seen of any content associated with your page broken down by paid and non-paid. (Unique Users)
insights_impressions_organic * integer 
23423234
 Number of times your posts were seen in News Feed or ticker or on visits to your Page. These impressions can be by people who have liked your Page and people who haven't. (Total Count)
insights_impressions_organic_unique * integer 
23423234
 Number of people who visited your Page, or saw your Page or one of its posts in news feed or ticker. These can be people who have liked your Page and people who haven't. (Unique Users)
insights_impressions_paid * integer 
23423234
 Number of impressions of a Sponsored Story or Ad pointing to your Page. (Total Count)
insights_impressions_paid_unique * integer 
23423234
 Number of people who saw a sponsored story or ad pointing to your Page. (Unique Users)
insights_impressions_unique * integer 
23423234
 Number of people who have seen any content associated with your Page. (Unique Users)
insights_impressions_viral * integer 
379
 Number of impressions of a story published by a friend about your Page. These stories include liking your Page, posting to your Page's Wall, liking, commenting on or sharing one of your Page posts, answering a Question you posted, RSVPing to one of your events, mentioning your Page, phototagging your Page or checking in at your Place. (Total Count)
insights_impressions_viral_frequency_distribution * object 
{ "1": 2053, "2": 415, "3": 120, "4": 64, "5": 29, "6-10": 30, "11-20": 10, "21+": 4 }
 Number of people your Page reached from a story published by a friend, broken down by how many times people saw stories about your Page. (Unique Users)
insights_impressions_viral_unique * integer 
379
 Number of people who saw your Page or one of its posts from a story shared by a friend. These stories include liking your Page, posting to your Page's timeline, liking, commenting on or sharing one of your Page posts, answering a question you posted, responding to one of your events, mentioning your Page, tagging your Page in a photo or checking in at your location. (Unique Users)
insights_negative_feedback * integer 
23423234
 Number of times people have given negative feedback to your Page. (Total Count)
insights_positive_feedback * integer 
23423234
 Number of times people have given positive feedback to your Page. (Total Count)
insights_posts_impressions * integer 
23423234
 Number of impressions that came from all of your posts. (Total Count)
insights_posts_impressions_by_paid_non_paid * object 
{ "total": 168616, "paid": 147501, "unpaid": 21115 }
 Number of impressions that came from all of your posts broken down by paid and non-paid. (Total Count)
insights_posts_impressions_by_paid_non_paid_unique * object 
{ "total": 115514, "paid": 105891, "unpaid": 9623 }
 Number of impressions that came from all of your posts broken down by paid and non-paid. (Unique Users)
insights_posts_impressions_frequency_distribution * object 
{ "1": 82733, "2": 25929, "3": 6863, "4": 1354, "5": 432, "6-10": 562, "11-20": 106, "21+": 19 }
 Number of people who saw your Page posts, broken down by how many times people saw your posts. (Unique Users)
insights_posts_impressions_organic_unique * integer 
23423234
 Number of people who saw your Page posts in news feed or ticker, or on your Page's timeline. (Unique Users)
insights_posts_impressions_paid * integer 
23423234
 Number of impressions of your Page posts in an Ad or Sponsored Story. (Total Count)
insights_posts_impressions_paid_unique * integer 
23423234
 Number of people who saw your Page posts in an ad or sponsored story. (Unique Users)
insights_posts_impressions_unique * integer 
23423234
 Number of people who saw any of your Page posts. (Unique Users)
insights_reach_engagement * float 
0.013763074921175114
 Number of people who engaged with your Page per Number of people who have seen any content associated with your Page. Engagement includes any click or story created. (Unique Users)
insights_reactions_count * integer 
100
 Number of reactions on any of your content.
insights_reactions_count_by_type * object 
{ "like": 319, "love": 4, "wow": 7, "haha": 0, "sorry": 0, "anger": 0 }
 Number of reactions on any of your content by type.
insights_stories * integer 
719
 Number of stories created about your Page. (Total Count)
insights_stories_by_story_type * object 
{"other": 345, "fan": 280, "page post": 90, "mention": 4, "user post": 0, "coupon": 0, "checkin": 0, "question": 0, "event": 0 }
 Number of stories about your Page by story type. (Total Count)
insights_storytellers * integer 
35
 Number of people sharing stories about your page. These stories include liking your Page, posting to your Page's timeline, liking, commenting on or sharing one of your Page posts, answering a question you posted, responding to one of your events, mentioning your Page, tagging your Page in a photo or checking in at your location. (Unique Users)
insights_storytellers_by_age_gender * object 
{ "M.18-24": 169, "M.25-34": 120, "F.18-24": 85, "F.25-34": 81, "F.35-44": 37, "M.35-44": 35, "M.45-54": 12, "M.55-64": 8, "M.65+": 7, "F.45-54": 6, "F.65+": 6, "U.25-34": 3, "F.55-64": 3, "U.35-44": 2, "F.13-17": 1 }
 Number of People Talking About the Page by user age and gender (Unique Users)
insights_storytellers_by_city * object 
{ "Dhaka, Dhaka Division, Bangladesh": 33, "Phnom Penh, Cambodia": 14, "Mexico City, Distrito Federal, Mexico": 13, "Karachi, Sindh, Pakistan": 12, "Ho Chi Minh City, Vietnam": 11, "Cairo, Cairo Governorate, Egypt": 10, ... }
 Number of People Talking About the Page by user city. (Unique Users)
insights_storytellers_by_country * object 
{ "PK": 44, "BD": 40, "IN": 30, "BR": 28, "MX": 24, ... }
 Number of People Talking About the Page by user country (Unique Users)
insights_storytellers_by_locale * object 
{ "en_US": 302, "en_GB": 99, "es_LA": 48, ... }
 Number of People Talking About the Page by user language. (Unique Users)
insights_storytellers_by_story_type * object 
{ "fan": 285, "other": 281, "page post": 32, "mention": 4, "user post": 0, "coupon": 0, "checkin": 0, "question": 0, "event": 0 }
 Number of people talking about your Page, by story type. (Unique Users)
insights_video_complete_views_30s * integer 
5
 Number of times page's videos have been viewed for more than 30 seconds
insights_video_complete_views_30s_autoplayed * integer 
5
 Number of times page's autoplayed videos have been viewed for more than 30 seconds
insights_video_complete_views_30s_click_to_play * integer 
1
 Number of times page's videos have been viewed after the user clicks on play for more than 30 seconds
insights_video_complete_views_30s_organic * integer 
5
 Number of times page's videos have been viewed for more than 30 seconds by organic reach
insights_video_complete_views_30s_repeat_views * integer 
9
 Number of times that people replay a page's videos for more than 30 seconds
insights_video_complete_views_30s_unique * integer 
62
 Number of times page's videos have been played for unique people for more than 30 seconds
insights_video_repeat_views * integer 
35
 Number of times that people replay a page's videos for more than 3 seconds
insights_video_views * integer 
6
 Number of times page's videos have been viewed for more than 3 seconds
insights_video_views_autoplayed * integer 
5
 Number of times page's autoplayed videos have been viewed for more than 3 seconds
insights_video_views_click_to_play * integer 
10
 Number of times page's videos have been viewed after the user clicks on play for more than 3 seconds
insights_video_views_organic * integer 
0
 Number of times page's videos have been viewed for more than 3 seconds by organic reach
insights_video_views_paid * integer 
44
 Number of times page's promoted videos have been viewed for more than 3 seconds
insights_video_views_unique * integer 
55
 Number of times page's videos have been played for unique people for more than 3 seconds
insights_views * integer 
379
 Page views (Total Count)
interactions_count integer 
100
 Number of interactions on page posts.
interactions_count_by_paid_status object 
{ "paid": 1, "organic": 2, "unknown": 0 }
 Number of interactions on page posts by paid status (organic/paid/unknown) based on PPD.
interactions_count_by_type object 
{ "video": 1, "photo": 2 }
 Number of interactions on page posts by post type.
interactions_per_1000_fans float 
1.94042765739004
 Number of interactions per thousand fans.
interactions_per_1000_fans_by_type object 
{ "photo": 0.94042765739004, "video": 0.001426624803003 }
 Number of interactions per thousand fans by type.
page_posts_by_app object 
{ "web": 1, "Socialbakers": 2 }
 Number of page posts by application via it was posted (any facebook app is "web").
page_posts_count integer 
100
 Number of page posts.
page_posts_count_by_paid_status object 
{ "paid": 1, "organic": 2, "unknown": 0 }
 Number of page posts by paid status (organic/paid/unknown) based on PPD.
page_posts_count_by_type object 
{ "video": 1, "photo": 2 }
 Number of page posts by post type.
reactions_count integer 
100
 Number of reactions on page posts.
reactions_count_by_paid_status object 
{ "paid": 1, "organic": 2, "unknown": 0 }
 Number of reactions on page posts by paid status (organic/paid/unknown) based on PPD.
reactions_count_by_reaction_type object 
{ "love": 1, "haha": 2, "like": 3, "sorry": 4, "anger": 5, "wow": 6 }
 Number of reactions on page posts by reaction type (like, love, haha, etc...).
reactions_count_by_type object 
{ "video": 1, "photo": 2 }
 Number of reactions on page posts by post type.
shares_count integer 
100
 Number of shares on page posts.
shares_count_by_paid_status object 
{ "paid": 1, "organic": 2, "unknown": 0 }
 Number of shares on page posts by paid status (organic/paid/unknown) based on PPD.
shares_count_by_type object 
{ "video": 1, "photo": 2 }
 Number of shares on page posts by post type.
user_posts_average_response_time integer 
100
 Average reponse time (mins) of responded user posts.
user_posts_by_app object 
{ "web": 1, "Socialbakers": 2 }
 Number of user posts by application via it was posted (any facebook app is "web").
user_posts_count integer 
100
 Number of user posts.
user_posts_responded_by_time object 
{ "Under 10 mins": 0, "10 - 30 mins": 0, "30 - 60 mins": 0, "60 - 90 mins": 0, "90 mins - 2 hours": 0, "2 - 4 hours": 0, "4 - 6 hours": 0, "6 - 12 hours": 0, "12 - 24 hours": 0, "24 - 48 hours": 0, "48 - 72 hours": 0, "More than 72 hours": 0 }
 Number of responded user posts by response time category.
user_posts_responded_count integer 
100
 Number of user posts that are responded (at least 1 page comment).
user_posts_response_rate float 
1.94042765739004
 Ratio of user posts and responded user posts.
user_questions_average_response_time integer 
100
 Average reponse time (mins) of responded user questions.
user_questions_count integer 
100
 Number of user posts that are marked as a question.
user_questions_responded_by_time object 
{ "Under 10 mins": 0, "10 - 30 mins": 0, "30 - 60 mins": 0, "60 - 90 mins": 0, "90 mins - 2 hours": 0, "2 - 4 hours": 0, "4 - 6 hours": 0, "6 - 12 hours": 0, "12 - 24 hours": 0, "24 - 48 hours": 0, "48 - 72 hours": 0, "More than 72 hours": 0 }
 Number of responded user questions by response time category.
user_questions_responded_count integer 
100
 Number of user posts that are marked as a question and that are responded (at least 1 page comment).
user_questions_response_rate float 
1.94042765739004
 Ratio of user questions and responded user questions.

Example request

POST /0/facebook/metrics HTTPS
Host: api.socialbakers.com
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "date_start": "2016-01-01",
  "date_end": "2016-01-02",
  "profiles": ["12345", "54321"],
  "metrics": ["fans_count_lifetime", "fans_change", ...]
}

Example response

{
  "success": true,
  "profiles": [
    {
      "id": "12345",
      "data": [
        {
          "date": "2016-01-01 00:00:00",
          "fans_count_lifetime": 123456,
          "fans_change": 123,
          ...
        },
        {
          "date": "2016-01-02 00:00:00",
          "fans_count_lifetime": 654321,
          "fans_change": 654,
          ...
        }
      ]
    },
    {
    "id": "54321",
    "data": [
      {
        "date": "2016-01-01 00:00:00",
        "fans_count_lifetime": 111222,
        "fans_change": 1122,
        ...
      },
      {
        "date": "2016-01-02 00:00:00",
        "fans_count_lifetime": 222111,
        "fans_change": 2211,
        ...
      }
    ]
    }
  ]
}

Instagram metrics

Returns daily metrics for each requested Instagram profile.
* Metrics prefixed with insights_ can only be used for profiles that have insights_enabled property set to true in the response of the /0/instagram/profiles endpoint.

Parameters

Name Description
date_start string, the beginning of the period you want to get the data for in the format YYYY-MM-DD. The timezone is automatically selected from your account.
date_end numeric string, the end of the period you want to get the data for in the format YYYY-MM-DD, selected day will be included in the response. The timezone is automatically selected from your account.
profiles The list of numeric string values. Each is ID of the profile available from the /0/instagram/profiles endpoint.
metrics The list of metrics that will be returned in the response. Available metrics are listed in the table below.
Metrics
Name Type Example Description
comments_count integer 
100
 Number of comments of profile posts.
comments_count_by_post_image_filter object 
{ "Normal": 1, "Clarendon": 2 }
 Number of comments of profile posts by used image filter of that post.
comments_count_by_post_type object 
{ "image": 1, "video": 2 }
 Number of comments of profile posts by post type.
comments_count_by_post_video_filter object 
{ "Normal": 1 }
 Number of comments of profile posts by used video filter of that post.
followers_change integer 
100
 Absolute change of followers count lifetime.
followers_count_lifetime integer 
100
 Followers count - lifetime value.
following_change integer 
100
 Absolute change of following count lifetime.
following_count_lifetime integer 
100
 Following count - lifetime value.
insights_followers_by_city_by_day * object 
{ "Dhaka, Dhaka Division, Bangladesh": 33, "Phnom Penh, Cambodia": 14, "Mexico City, Distrito Federal, Mexico": 13, ... }
 The cities of the Business Account's followers.
insights_followers_by_country_by_day * object 
{ "PK": 44, "BD": 40, "IN": 30, "BR": 28, "MX": 24, ... }
 The countries of the Business Account's followers.
insights_followers_by_gender_by_age_by_day * object 
{ "M.18-24": 169, "M.25-34": 120, "F.18-24": 85, "F.25-34": 81, "F.35-44": 37, "M.35-44": 35, "M.45-54": 12, "M.55-64": 8, "M.65+": 7, "F.45-54": 6, "F.65+": 6, "U.25-34": 3, "F.55-64": 3, "U.35-44": 2, "F.13-17": 1 }
 The gender and age distribution of the Business Account's followers.
insights_followers_by_locale_by_day * object 
{ "en_US": 302, "en_GB": 99, "es_LA": 48, ... }
 The number of followers broken down by language preferences.
insights_post_engagement_by_day * integer 
100
 Total number of likes and comments on the posts.
insights_post_engagement_by_type_by_day * object 
{ "video": 100, "carousel_album": 100, "carousel": 100, "image": 100 }
 Total engagement (likes and comments) broken down by post type (video, carousel album, carousel, image).
insights_post_impressions_by_day * integer 
100
 The number of times posts have been seen.
insights_post_impressions_by_type_by_day * object 
{ "video": 100, "carousel_album": 100, "carousel": 100, "image": 100 }
 The number of times posts have been seen, broken down by post type.
insights_post_interactions_by_day * integer 
100
 The number of Likes, Comments and Saves posts received. The data source of this chart is different from the post_engagement. As a result, the number of interactions may vary.
insights_post_interactions_by_int_type_by_day * object 
{ "like": 100, "saved": 100, "comment": 100 }
 The number of Likes, Comments and Saves posts received, broken down by the type of Interactions. The data source of this chart is different from the post_engagement. As a result, the number of interactions may vary.
insights_post_saved_by_day * integer 
100
 Total number of saves on the posts.
insights_post_saved_by_type_by_day * object 
{ "video": 100, "carousel_album": 100, "carousel": 100, "image": 100 }
 Total number of saves broken down by post type (video, carousel album, carousel, image).
insights_post_video_views_by_day * integer 
100
 The number of times videos have been viewed.
insights_post_video_views_by_type_by_day * object 
{ "video": 100, "carousel_album": 100, "carousel": 100, "image": 100 }
 The number of times videos have been viewed, broken down by video type.
insights_profile_all_clicks_by_day * integer 
100
 The number of times user clicked on a specific contact on your Business Account's profile.
insights_profile_email_contacts_by_day * integer 
100
 Total number of taps on the email link in the Business Account's profile.
insights_profile_get_directions_clicks_by_day * integer 
100
 Total number of taps on the directions link in the Business Account's profile.
insights_profile_impressions_by_day * integer 
100
 Total number of times the Business Account's media objects (i.e. posts, stories and promotions) have been viewed. Does not include profile views.
insights_profile_impressions_unique_by_day * integer 
100
 Unique Impressions (Reach) refers to the number of different people who see your post. One person can see your post 5 times but is only counted once toward Reach.
insights_profile_phone_call_clicks_by_day * integer 
100
 Total number of taps on the call link in the Business Account's profile.
insights_profile_text_message_clicks_by_day * integer 
100
 Total number of taps on the text message link in the Business Account's profile.
insights_profile_views_by_day * integer 
100
 Total number of unique users who have viewed the Business Account's profile.
insights_profile_website_clicks_by_day * integer 
100
 Total number of taps on the website link in the Business Account's profile.
interactions_count integer 
100
 Number of interactions (likes and comments) of profile posts.
interactions_count_by_post_image_filter object 
{ "Normal": 1, "Clarendon": 2 }
 Number of interactions of profile posts by used image filter of that post.
interactions_count_by_post_type object 
{ "image": 1, "video": 2 }
 Number of interactions of profile posts by post type.
interactions_count_by_post_video_filter object 
{ "Normal": 1 }
 Number of interactions of profile posts by used video filter of that post.
interactions_per_1000_followers float 
11.94042765739004
 Number of interactions (likes and comments) per thousand followers.
interactions_per_1000_followers_by_image_filter object 
{ "Normal": 11.94042765739004, "Clarendon": 12.94042765739004 }
 Number of interactions (likes and comments) per thousand followers by used image filter.
interactions_per_1000_followers_by_type object 
{ "image": 10.94042765739004, "video": 11.94042765739004 }
 Number of interactions (likes and comments) per thousand followers by used post type.
interactions_per_1000_followers_by_video_filter object 
{ "Normal": 10.94042765739004 }
 Number of interactions (likes and comments) per thousand followers by used video filter.
likes_count integer 
100
 Number of likes of profile posts.
likes_count_by_post_image_filter object 
{ "Normal": 1, "Clarendon": 2 }
 Number of likes of profile posts by used image filter of that post.
likes_count_by_post_type object 
{ "image": 1, "video": 2 }
 Number of likes of profile posts by post type.
likes_count_by_post_video_filter object 
{ "Normal": 1 }
 Number of likes of profile posts by used video filter of that post.
posts_count integer 
100
 Number of profile posts.
posts_count_by_image_filter object 
{ "Normal": 1, "Clarendon": 2 }
 Number of profile posts by used image filter of that post.
posts_count_by_type object 
{ "image": 1, "video": 2 }
 Number of profile posts by post type.
posts_count_by_video_filter object 
{ "Normal": 1 }
 Number of profile posts by used video filter of that post.

Example request

POST /0/instagram/metrics HTTPS
Host: api.socialbakers.com
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "date_start": "2016-01-01",
  "date_end": "2016-01-02",
  "profiles": ["12345", "54321"],
  "metrics": ["followers_count_lifetime", "followers_change", ...]
}

Example response

{
  "success": true,
  "profiles": [
    {
      "id": "12345",
      "data": [
        {
          "date": "2016-01-01 00:00:00",
          "followers_count_lifetime": 123456,
          "followers_change": 123,
          ...
        },
        {
          "date": "2016-01-02 00:00:00",
          "followers_count_lifetime": 654321,
          "followers_change": 654,
          ...
        }
      ]
    },
    {
      "id": "54321",
      "data": [
        {
          "date": "2016-01-01 00:00:00",
          "followers_count_lifetime": 111222,
          "followers_change": 1122,
          ...
        },
        {
          "date": "2016-01-02 00:00:00",
          "followers_count_lifetime": 222111,
          "followers_change": 2211,
          ...
        }
      ]
    }
  ]
}

Twitter metrics

Returns daily metrics for each requested Twitter profile.

Parameters

Name Description
date_start string, the beginning of the period you want to get the data for in the format YYYY-MM-DD. The timezone is automatically selected from your account.
date_end numeric string, the end of the period you want to get the data for in the format YYYY-MM-DD, selected day will be included in the response. The timezone is automatically selected from your account.
profiles The list of numeric string values. Each is ID of the profile available from the /0/twitter/profiles endpoint.
metrics The list of metrics that will be returned in the response. Available metrics are listed in the table below.
Metrics
Name Type Example Description
ff_ratio float 
97.1443812233286
 Absolute change of following count lifetime.
followers_change integer 
100
 Absolute change of followers count lifetime.
followers_count_lifetime integer 
100
 Followers count - lifetime value.
following_change integer 
100
 Absolute change of following count lifetime.
following_count_lifetime integer 
100
 Following count - lifetime value.
incoming_count integer 
100
 Number of all incoming activities (mentions + retweets + replies) created by others mentioning this profile.
incoming_questions_average_response_time float 
12.34
 Average reponse time (mins) of responded user questions.
incoming_questions_count integer 
100
 Number of user tweets that are also marked as a question.
incoming_questions_responded_by_time object 
{ "Under 10 mins": 0, "10 - 30 mins": 0, "30 - 60 mins": 0, "60 - 90 mins": 0, "90 mins - 2 hours": 0, "2 - 4 hours": 0, "4 - 6 hours": 0, "6 - 12 hours": 0, "12 - 24 hours": 0, "24 - 48 hours": 0, "48 - 72 hours": 0, "More than 72 hours": 0 }
 Number of responded user questions by response time category.
incoming_questions_responded_count integer 
100
 Number of user tweets that are marked as a question and that are responded (profile reply).
incoming_questions_response_rate float 
0.02409638554216
 Ratio of user questions and responded user questions.
incoming_replies_count integer 
100
 Number of retweets made by others.
incoming_retweets_count integer 
100
 Number of replies made by others.
incoming_tweets_average_response_time float 
12.34
 Average reponse time (mins) of responded user tweets.
incoming_tweets_count integer 
100
 Number of user tweets. User tweet is considered any incoming activity (mention, reply), exluding retweets.
incoming_tweets_responded_by_time object 
{ "Under 10 mins": 0, "10 - 30 mins": 0, "30 - 60 mins": 0, "60 - 90 mins": 0, "90 mins - 2 hours": 0, "2 - 4 hours": 0, "4 - 6 hours": 0, "6 - 12 hours": 0, "12 - 24 hours": 0, "24 - 48 hours": 0, "48 - 72 hours": 0, "More than 72 hours": 0 }
 Number of responded user tweets by response time category.
incoming_tweets_responded_count integer 
100
 Number of user tweets that are responded (profile reply).
incoming_tweets_response_rate float 
0.02409638554216
 Ratio of user tweets and responded user tweets.
interactions_count integer 
100
 Number of interactions on profile tweets and replies.
interactions_per_1000_followers float 
1.55379654060392
 Number of interactions per thousand followers.
likes_count integer 
100
 Number of likes on profile tweets and replies.
listed_change integer 
100
 Absolute change of listed count lifetime.
listed_count_lifetime integer 
100
 Listed count - lifetime value (how many times profile has been listed).
profile_activities_by_app object 
{ "twitter-web-client": 1, "tweetdeck": 2 }
 Number of all activities posted by profile by application via it was posted.
profile_activities_count integer 
100
 Number of all activities (tweets + retweets + replies) created by the profile.
profile_replies_count integer 
100
 Number of replies made by profile.
profile_retweets_count integer 
100
 Number of retweets made by profile.
profile_tweets_count integer 
100
 Number of tweets made by profile.
replies_count integer 
100
 Number of replies on profile tweets and replies.
retweets_count integer 
100
 Number of retweets on profile tweets and replies.

Example request

POST /0/twitter/metrics HTTPS
Host: api.socialbakers.com
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "date_start": "2016-01-01",
  "date_end": "2016-01-02",
  "profiles": ["12345", "54321"],
  "metrics": ["followers_count_lifetime", "followers_change", ...]
}

Example response

{
  "success": true,
  "profiles": [
    {
      "id": "12345",
      "data": [
        {
          "date": "2016-01-01 00:00:00",
          "followers_count_lifetime": 123456,
          "followers_change": 123,
          ...
        },
        {
          "date": "2016-01-02 00:00:00",
          "followers_count_lifetime": 654321,
          "followers_change": 654,
          ...
        }
      ]
    },
    {
      "id": "54321",
      "data": [
        {
          "date": "2016-01-01 00:00:00",
          "followers_count_lifetime": 111222,
          "followers_change": 1122,
          ...
        },
        {
          "date": "2016-01-02 00:00:00",
          "followers_count_lifetime": 222111,
          "followers_change": 2211,
          ...
        }
      ]
    }
  ]
}

YouTube metrics

Returns daily metrics for each requested YouTube profile.

Parameters

Name Description
date_start string, the beginning of the period you want to get the data for in the format YYYY-MM-DD. The timezone is automatically selected from your account.
date_end numeric string, the end of the period you want to get the data for in the format YYYY-MM-DD, selected day will be included in the response. The timezone is automatically selected from your account.
profiles The list of string values. Each is ID of the profile available from the /0/youtube/profiles endpoint.
metrics The list of metrics that will be returned in the response. Available metrics are listed in the table below.
Metrics
Name Type Example Description
comments_change integer 
100
 Absolute change of comments count on uploaded videos.
dislikes_change integer 
100
 Absolute change of dislikes count on uploaded videos.
interaction_change integer 
100
 Absolute change of interactions (likes + dislikes + comments) count on uploaded videos.
interactions_per_1000_subscribers float 
23.56734832691981
 Number of interactions per thousand subscribers.
likes_change integer 
100
 Absolute change of likes count on uploaded videos.
subscribers_change integer 
100
 Absolute change of subscribers count lifetime.
subscribers_count_lifetime integer 
100
 Subscribers count - lifetime value.
video_change integer 
100
 Absolute change of videos count lifetime.
video_count_lifetime integer 
100
 Video count - lifetime value.
viewed_time_change integer 
100
 Absolute change of viewed time (in seconds) lifetime. Viewed time for each video is number of views multiplied by length of the video.
viewed_time_lifetime integer 
100
 Viewed time (in seconds) of all uploaded videos - lifetime value. Viewed time for each video is number of views multiplied by length of the video.
views_change integer 
100
 Absolute change of views count lifetime.
views_count_lifetime integer 
100
 Views count of all uploaded videos - lifetime value.

Example request

POST /0/youtube/metrics HTTPS
Host: api.socialbakers.com
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "date_start": "2016-01-01",
  "date_end": "2016-01-02",
  "profiles": ["profile1", "profile2"],
  "metrics": ["subscribers_count_lifetime", "subscribers_change", ...]
}

Example response

{
  "success": true,
  "profiles": [
    {
      "id": "profile1",
      "data": [
        {
          "date": "2016-01-01 00:00:00",
          "subscribers_count_lifetime": 123456,
          "subscribers_change": 123,
          ...
        },
        {
          "date": "2016-01-02 00:00:00",
          "subscribers_count_lifetime": 654321,
          "subscribers_change": 654,
          ...
        }
      ]
    },
    {
      "id": "profile2",
      "data": [
        {
          "date": "2016-01-01 00:00:00",
          "subscribers_count_lifetime": 111222,
          "subscribers_change": 1122,
          ...
        },
        {
          "date": "2016-01-02 00:00:00",
          "subscribers_count_lifetime": 222111,
          "subscribers_change": 2211,
          ...
        }
      ]
    }
  ]
}

Pinterest metrics

Returns daily metrics for each requested Pinterest profile.

Parameters

Name Description
date_start string, the beginning of the period you want to get the data for in the format YYYY-MM-DD. The timezone is automatically selected from your account.
date_end numeric string, the end of the period you want to get the data for in the format YYYY-MM-DD, selected day will be included in the response. The timezone is automatically selected from your account.
profiles The list of string values. Each is ID of the profile available from the /0/pinterest/profiles endpoint.
metrics The list of metrics that will be returned in the response. Available metrics are listed in the table below.
Metrics
Name Type Example Description
boards_change integer 
100
 Absolute change of boards count lifetime.
boards_count_lifetime integer 
100
 Boards count - lifetime value.
comments_count integer 
100
 Number of comments on profile pins.
followers_change integer 
100
 Absolute change of followers count lifetime.
followers_count_lifetime integer 
100
 Followers count - lifetime value.
following_change integer 
100
 Absolute change of following count lifetime.
following_count_lifetime integer 
100
 Following count - lifetime value.
interactions_count integer 
100
 Number of interactions on profile pins.
likes_count integer 
100
 Number of likes on profile pins.
pins_change integer 
100
 Absolute change of pins count lifetime.
pins_count_lifetime integer 
100
 Pins count - lifetime value
repin_count integer 
100
 Number of repins on profile pins.

Example request

POST /0/pinterest/metrics HTTPS
Host: api.socialbakers.com
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "date_start": "2016-01-01",
  "date_end": "2016-01-02",
  "profiles": ["12345", "54321"],
  "metrics": ["pins_change", "boards_change", ...]
}

Example response

{
  "success": true,
  "profiles": [
    {
      "id": "12345",
      "data": [
        {
          "date": "2016-01-01 00:00:00",
          "pins_change": 123,
          "boards_change": 12,
          ...
        },
        {
          "date": "2016-01-02 00:00:00",
          "pins_change": 23,
          "boards_change": 10
          ...
        }
      ]
    },
    {
      "id": "54321",
      "data": [
        {
          "date": "2016-01-01 00:00:00",
          "pins_change": 50,
          "boards_change": 7,
          ...
        },
        {
          "date": "2016-01-02 00:00:00",
          "pins_change": 43,
          "boards_change": 11,
          ...
        }
      ]
    }
  ]
}

Facebook page posts metrics

Returns post metrics for each requested Facebook profile.
* Metrics prefixed with insights_ can only be used for profiles that have insights_enabled property set to true in the response of the /0/facebook/profiles endpoint.

Parameters

Name Description
profile string, the value is ID of the profile available from the /0/facebook/profiles endpoint.
date_start string, the beginning of the period you want to get the data for in the format YYYY-MM-DD. The timezone is automatically selected from your account.
date_end numeric string, the end of the period you want to get the data for in the format YYYY-MM-DD, selected day will be included in the response. The timezone is automatically selected from your account.
fields array, the list of fields that will be returned in the response. Available fields are listed in the table below.
limit integer, (optional). The number of post results per page. Default value is 25.
after string, (optional). Pagination cursor. Points to the end of the page that has been returned.
Fields
Name Type Example Description
attachments array 
[{ "title": "Know Where You Stand on Social Media", "description": "Get a free customized report that will provide you with detailed data insights showing you where you stand vereses your competition on Facebook. Try it now! ", "url": "https://goo.gl/AtTi93", "image_url": "https://external.xx.fbcdn.net/safe_image.php?d=AQCXbmZ491Pwd29M&url=https%3A%2F%2Fcdn.socialbakers.com%2Fwww%2Fstorage%2Fmicrosites%2Fkyn%2FOG-KYN.jpg"}]
 Array of objects containing details about post attachments. Fields: title, description, url, image_url.
author_id string 
164929129743
 Facebook page post author profile id.
comments_count integer 
100
 Facebook post comments count.
created datetime 
2016-10-24T16:15:04+00:00
 Facebook post created time.
id string 
164929129743_10154702368914744
 Facebook post id.
insights_consumptions * integer 
100
 The number of times people clicked on anywhere in your posts without generating a story
insights_consumptions_by_type * object 
{"photo view": 368, "other clicks": 186, "link clicks": 1, "video play": 0},
 The number of times people clicked on anywhere in your posts without generating a story, broken-down by consumption type.
insights_consumptions_by_type_unique * object 
{"photo view": 4, "other clicks": 15, "link clicks": 46, "video play": 0},
 The number of people who clicked anywhere in your post without generating a story, broken-down by consumption type.
insights_consumptions_unique * integer 
100
 The number of people who clicked anywhere in your post without generating a story
insights_engaged_fan * integer 
100
 People who have liked your page and engaged with your post.
insights_engaged_users * integer 
100
 The number of people who clicked anywhere in your posts
insights_engagement_rate * float 
0.0378
 Reach shows you how many people were exposed to your content and Reach Engagement Rate shows you how many of those reached people actually interacted with it.
insights_fan_reach * integer 
100
 Post reach by people who like your page.
insights_impressions * integer 
100
 The number of impressions for your Page post
insights_impressions_by_paid_non_paid * object 
{ 'paid': 0, 'unpaid': 7655, 'total': 7655 }
 The number of impressions for your Page post, broken down by total, paid, and non-paid
insights_impressions_by_paid_non_paid_unique * object 
{ 'paid': 0, 'unpaid': 7655, 'total': 7655 }
 The number of people who saw your Page post, broken down by total, paid, and non-paid
insights_impressions_fan * integer 
100
 The number of impressions for your Page post by people who have liked your Page
insights_impressions_fan_paid * integer 
100
 The number of impressions for your Page post by people who like your Page in an Ad or Sponsored Story
insights_impressions_fan_paid_unique * integer 
100
 The number of people who have like your Page and saw your Page post in an Ad or Sponsored Story
insights_impressions_fan_unique * integer 
100
 The number of people who have like your Page who saw your Page post
insights_impressions_organic * integer 
100
 The number of impressions of your post in Newsfeed, Ticker, or on your Page's Wall
insights_impressions_organic_unique * integer 
100
 The number of people who saw your post in their Newsfeed or Ticker or on your Page's Wall
insights_impressions_paid * integer 
100
 The number of impressions for your Page post in an Ad or Sponsored Story
insights_impressions_paid_unique * integer 
100
 The number of people who saw your Page post in an Ad or Sponsored Story
insights_impressions_unique * integer 
100
 The number of people who saw your Page post
insights_negative_feedback * integer 
100
 The number of times people took a negative action in your post (e.g. hid it)
insights_negative_feedback_unique * integer 
100
 The number of people who took a negative action in your post (e.g., hid it)
insights_reactions_by_type_total * object 
{"like": 8, "love": 0, "wow": 0, "haha": 0, "sorry": 0, "anger": 0}
 Daily total post reactions of a page by type
insights_reactions_like_total * integer 
100
 Percentage of viewers at each interval where the video started playing automatically. Video length is divided into short buckets. Each key in response represents a bucket. Values are percent of people saw the video in that bucket
insights_stories * integer 
100
 The number of stories created about your Page (Stories)
insights_story_adds * integer 
100
 The number of stories generated about your Page post.
insights_storytellers * integer 
100
 The number of people sharing stories about your page ('People Talking About This' / PTAT). These stories include liking your Page, posting to your Page's Wall, liking, commenting on or sharing one of your Page posts, answering a Question you posted, RSVPing to one of your events, mentioning your Page, phototagging your Page or checking in at your Place
insights_video_avg_time_watched * integer 
100
 The average length of time (in milliseconds) people spent viewing your video
insights_video_complete_views_30s * integer 
100
 Total number of times page's videos have been viewed for more than 30 seconds
insights_video_complete_views_30s_autoplayed * integer 
100
 Total number of times page's autoplayed videos have been viewed to the end, or viewed for more than 30 seconds
insights_video_complete_views_30s_clicked_to_play * integer 
100
 Total number of times page's videos have been viewed to the end, or viewed after the user clicks on play for more than 30 seconds
insights_video_complete_views_30s_organic * integer 
100
 Total number of times page's videos have been viewed to the end, or viewed for more than 30 seconds by organic reach
insights_video_complete_views_30s_paid * integer 
100
 Total number of times page's promoted videos have been viewed to the end, or for more than 30 seconds
insights_video_complete_views_30s_unique * integer 
100
 Total number of times page's videos have been played for unique people to the end, or viewed for more than 30 seconds
insights_video_complete_views_organic * integer 
100
 The number of times your video was organically viewed from the beginning to 95% of its length
insights_video_complete_views_organic_unique * integer 
100
 The number of people who viewed your video organically from the beginning to 95% of its length
insights_video_complete_views_paid * integer 
100
 The number of times your video was viewed via paid impression from the beginning to 95% of its length
insights_video_complete_views_paid_unique * integer 
100
 The number of people who viewed your video via paid impression from the beginning to 95% of its length
insights_video_retention_graph * object 
[0.6680000000000001, 1, 0.9683999999999999, 0.8257000000000001, 0.7319000000000001, 0.6640000000000001]
 Percentage of viewers at each interval. Video length is divided into short buckets. Each key in response represents a bucket. Values are percent of people saw the video in that bucket
insights_video_retention_graph_autoplayed * object 
[0.6680000000000001, 1, 0.9683999999999999, 0.8257000000000001, 0.7319000000000001, 0.6640000000000001]
 Percentage of viewers at each interval where the video started playing automatically. Video length is divided into short buckets. Each key in response represents a bucket. Values are percent of people saw the video in that bucket
insights_video_view_time * integer 
100
 The total number of milliseconds your video was watched, including replays and views less than 3 seconds.
insights_video_view_time_organic * integer 
100
 Total time (in milliseconds) video has been viewed without paid promotion
insights_video_view_time_paid * integer 
100
 Total time (in milliseconds) video has been viewed with paid promotion
insights_video_views * integer 
100
 The number of times your video was watched for an aggregate of at least 3 seconds, or for nearly its total length, whichever happened first.
insights_video_views_autoplayed * integer 
100
 Number of times your video started automatically playing and people viewed it for more than 3 seconds
insights_video_views_clicked_to_play * integer 
100
 Number of times people clicked to play your video and viewed it more than 3 seconds
insights_video_views_organic * integer 
100
 The number of times your video was organically viewed for 3 seconds or more
insights_video_views_organic_unique * integer 
100
 The number of people who viewed at least 3 seconds of your video organically
insights_video_views_paid * integer 
100
 The number of times your video was viewed via paid impression for 3 seconds or more
insights_video_views_paid_unique * integer 
100
 The number of people who viewed at least 3 seconds of your video via paid impression
insights_video_views_unique * integer 
100
 The number of distinct people who viewed your video at least once.
interactions_count integer 
100
 Facebook post interaction count.
is_published boolean 
true
 Is post published
message string 
A free tool that delivers a custom benchmark report, in minutes, so you can easily understand how well you are using social media to nurture customer relationships. Do you know your numbers?
 Facebook post contents.
page_id string 
164929129743
 Facebook page id for the published post.
paid_status string 
paid|organic|unknown
 Indicates whether the post was organic, paid or unknown based on PPD algorithm.
reactions object 
{"like": 548, "love": 2, "wow": 2, "haha": 0, "sorry": 0, "anger": 0}
 Object containing Facebook post reactions number.
reactions_count integer 
100
 Facebook post reactions count.
sbks_labels array 
["label 1", "label 2"]
 Array of post labels for given post and account
shares_count integer 
100
 Facebook post share count.
story string 
Socialbakers published a note
 Text from stories not intentionally generated by users, such as those generated when two people become friends, or when someone else posts on the person's wall.
type string 
photo|status|link|video|offer|note|poll|unknown
 Facebook post type.
universal_video_id string 
164929129743_10156499215049744
 The publishers asset management code for this video. Only available in case the post type is a video.
url string 
https://www.facebook.com/permalink.php?story_fbid=10154702368914744&id=164929129743
 Link to facebook post.
video_id string 
10156498782054744
 The id of the video object.
video_length float 
125.481
 Duration of the video in seconds. Only available in case the post type is a video.

Response

Name Description
success Status of the response. Possible values are true or false.
data object containing the following properties:
  • posts: array, containing post metric data
  • next: string, pagination cursor. Used for pagination over posts data.
  • remaining: integer, number of remaining items, counting from current page, until end of posts data.

Example request

POST /0/facebook/page/posts HTTPS
Host: api.socialbakers.com
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "profile": "164929129743",
  "date_start": "2010-01-01",
  "date_end": "2016-10-25",
  "fields": [
    "id",
    "created",
    "message",
    "comments_count",
    "shares_count",
    "reactions_count",
    "interactions_count",
    "url",
    "author_id",
    "page_id",
    "attachments",
    "type",
    "reactions",
    "story",
    "insights_impressions",
    "insights_impressions_paid",
    "insights_engaged_users",
    "insights_video_avg_time_watched",
    "insights_engagement_rate",
    "insights_consumptions_by_type",
    "insights_consumptions_by_type_unique",
    "universal_video_id",
    "video_id",
    "paid_status",
    "video_length"
  ],
  "limit": 5
}

Example response

{
  "success": true,
  "data": {
    "posts": [
      {
        "id": "164929129743_10154736430664744",
        "created": "2016-11-04T13:00:08+00:00",
        "message": "Brainstorming on your social media content? This tool will help ↓",
        "comments_count": 10,
        "shares_count": 20,
        "reactions_count": 70,
        "interactions_count": 100,
        "url": "https://www.facebook.com/socialbakers/posts/10154736430664744",
        "author_id": "164929129743",
        "page_id": "164929129743",
        "attachments": [
          {
              "title": "Looking to Get Inspired For Your Next Campaign or Post?",
              "description": "Coming up with ideas for new posts and campaigns is a challenge for every marketer...",
              "url": "https://goo.gl/28ZEjD",
              "image_url": "https://external.xx.fbcdn.net/safe_image.php?d=AQDCqVXSjdGWUTu5&url=https%3A%2F%2Fwww.facebook.com%2Fads%2Fimage%2F%3Fd%3DAQJAeqUrvHG_eEQJrlnw0oLjbP7j0uio9f72hrlJ-8VWCVEc2tV_wkWj3XOLkWrB3R0KYlA09NYIwj1KGgpqOkDtsYkAg49xZVltN_OQloQpjk0smGZC9CwkDTZn9XbotqP5G6MYA8bEjlnhgdc84Exm"
          }
        ],
        "type": "link",
        "reactions": {
          "like": 10,
          "love": 20,
          "wow": 30,
          "haha": 5,
          "sorry": 3,
          "anger": 2
        },
        "story": "Socialbakers published a note",
        "insights_impressions": 3583,
        "insights_impressions_paid": 496,
        "insights_engaged_users": 50,
        "insights_video_avg_time_watched": 60000,
        "video_id": "1072177562941323",
        "paid_status": "organic",
        "video_length": 125.481,
        "universal_video_id": "164929129743_10154736430664744",
        "insights_consumptions_by_type": {
          "other clicks": 381,
          "link clicks": 48,
          "video play": 530
        },
        "insights_consumptions_by_type_unique": {
          "other clicks": 302,
          "link clicks": 43,
          "video play": 506
        },
        "insights_engagement_rate": 0.017567734751948533
      }, ...
    ],
    "next": "eyJjdXJzb3IiOlt7ImZpZWxkIjoiY3JlYXRlZF90aW1lIiwidmFsdWUiOiIyMDE2LTEwLTI1VDEzOjAwOjA2LjAwMFoiLCJvcmRlciI6ImRlc2MifV0sImlkcyI6WyIxNjQ5MjkxMjk3NDNfMTAxNTQ3MDUwODA3Mzk3NDQiXX0=",
    "remaining": 3276
  }
}

Instagram profile posts metrics

Returns post metrics for each requested Instagram profile.
* Metrics prefixed with insights_ can only be used for profiles that have insights_enabled property set to true in the response of the /0/instagram/profiles endpoint.

Parameters

Name Description
profile string, the value is ID of the profile available from the /0/instagram/profiles endpoint.
date_start string, the beginning of the period you want to get the data for in the format YYYY-MM-DD. The timezone is automatically selected from your account.
date_end numeric string, the end of the period you want to get the data for in the format YYYY-MM-DD, selected day will be included in the response. The timezone is automatically selected from your account.
fields array, the list of fields that will be returned in the response. Available fields are listed in the table below.
limit integer, (optional). The number of post results per page. Default value is 25.
after string, (optional). Pagination cursor. Points to the end of the page that has been returned.
Fields
Name Type Example Description
attachments array 
[{ "images": [{
				"url": "https://external.xx.fbcdn.net/safe_image.php?d=AQCXbmZ491Pwd29M&url=https%3A%2F%2Fcdn.socialbakers.com%2Fwww%2Fstorage%2Fmicrosites%2Fkyn%2FOG-KYN.jpg"
			]},
			"videos": [],
			"indices": []
		}]
 Array of objects containing details about post attachments. Fields: url, type, width, height
author_id string 
490402220
 Author profile ID.
comment_count integer 
100
 Total number of comments on the media object.
created datetime 
2016-10-24T16:15:04+00:00
 Instagram media created time.
id string 
17966172199068623_490402220
 Instagram media ID.
insights_engagement * integer 
100
 Total number of likes and comments on the media object.
insights_impressions * integer 
100
 Total number of times the media object has been seen.
insights_reach * integer 
100
 Total number of unique accounts that have seen the media object.
insights_saved * integer 
100
 Total number of unique accounts that have saved the media object.
insights_video_views * integer 
100
 (Videos only) Total number of times the video has been seen. Returns 0 for videos in carousel albums.
interaction_count integer 
100
 Total number of interactions on the media object.
like_count integer 
100
 Total number of likes on the media object.
message string 
A first instagram post
 Instagram media contents.
type string 
carousel|image|video|carousel_album
 Media post type.

Response

Name Description
success Status of the response. Possible values are true or false.
data object containing the following properties:
  • posts: array, containing post metric data
  • next: string, pagination cursor. Used for pagination over posts data.
  • remaining: integer, number of remaining items, counting from current page, until end of posts data.

Example request

POST /0/instagram/profile/posts HTTPS
Host: api.socialbakers.com
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "profile": "490402220",
  "date_start": "2018-06-01",
  "date_end": "2018-08-31",
  "fields": [
    "interaction_count",
    "comment_count",
    "like_count",
    "insights_engagement",
    "insights_saved",
    "insights_reach",
    "insights_video_views",
    "insights_impressions",
    "id",
    "author_id",
    "created",
    "type",
    "message",
    "attachments"
  ]
  "limit": 5
}

Example response

{
  "success": true,
  "data": {
    "posts": [
      {
        "id": "17966172199068623_490402220",
        "created": "2018-08-23T09:59:27+00:00",
        "message": "Stuck in a rut with your Instagram marketing? Don’t sweat it 🙅‍♀️. Freshen up your content with these tips for insta success 💥! See link in bio to unlock the full list 📝",
        "comment_count": 9,
        "like_count": 86,
        "author_id": "490402220",
        "type": "video",
        "interaction_count": 95,
        "profile_id": "490402220",
        "attachments": [
          {
            "images": [],
            "videos": [
              {
                "url": "https://scontent.xx.fbcdn.net/v/t50.2886-16/39076708_281043816045474_2574583738604191744_n.mp4?_nc_cat=0&oh=2d1efdd181ee7d18d1be98d22afdb900&oe=5BF734E0"
              }
            ]
          }
        ],
        "insights_engagement": 148,
        "insights_saved": 52,
        "insights_reach": 3094,
        "insights_video_views": 923,
        "insights_impressions": 4178
      }
    ],
    "next": "eyJjdXJzb3IiOlt7ImZpZWxkIjoiY3JlYXRlZF90aW1lIiwidmFsdWUiOiIyMDE4LTA2LTI4VDEyOjM4OjM0KzAwOjAwIiwib3JkZXIiOiJkZXNjIn1dLCJpZHMiOlsiMTc4OTM5NTExNjIyMTY0NjRfNDkwNDAyMjIwIl19=",
    "remaining": 15
  }
}

Twitter tweets metrics

Returns tweets metrics for each requested Twitter profile.

Parameters

Name Description
profile string, the value is ID of the profile available from the /0/twitter/profiles endpoint.
date_start string, the beginning of the period you want to get the data for in the format YYYY-MM-DD. The timezone is automatically selected from your account.
date_end numeric string, the end of the period you want to get the data for in the format YYYY-MM-DD, selected day will be included in the response. The timezone is automatically selected from your account.
fields array, the list of fields that will be returned in the response. Available fields are listed in the table below.
limit integer, (optional). The number of post results per page. Default value is 25.
after string, (optional). Pagination cursor. Points to the end of the page that has been returned.
Fields
Name Type Example Description
attachments array 
'attachments': [
{
  'url': 'https://t.co/zj4QKZ9oLr'
  'display_url': 'en.wikipedia.org/wiki/Let_3'
  'expanded_url': 'https://en.wikipedia.org/wiki/Let_3'
  'indices': [ 0, 23 ]
}
{
  'url': 'https://t.co/TydZGpShh8'
  'display_url': 'pic.twitter.com/TydZGpShh8'
  'expanded_url': 'https://twitter.com/aljinovicante/status/838708864761671680/video/1'
  'indices': [ 42, 65 ]
  'image':
    'width': 320
    'height': 224
    'url': 'http://pbs.twimg.com/ext_tw_video_thumb/838708091659116544/pu/img/yrYiZy7QwfT5wVQn.jpg:small'
  'images': [
    {
      'width': 320
      'height': 224
      'url': 'http://pbs.twimg.com/ext_tw_video_thumb/838708091659116544/pu/img/yrYiZy7QwfT5wVQn.jpg:small'
    }
    {
      'width': 320
      'height': 224
      'url': 'http://pbs.twimg.com/ext_tw_video_thumb/838708091659116544/pu/img/yrYiZy7QwfT5wVQn.jpg:medium'
    }
    {
      'width': 320
      'height': 224
      'url': 'http://pbs.twimg.com/ext_tw_video_thumb/838708091659116544/pu/img/yrYiZy7QwfT5wVQn.jpg:large'
    }
    {
      'width': 150
      'height': 150
      'url': 'http://pbs.twimg.com/ext_tw_video_thumb/838708091659116544/pu/img/yrYiZy7QwfT5wVQn.jpg:thumb'
    }
  ]
}
]
 Array of objects containing details about post attachments.
author_id string 
100004577
 Tweet author profile id.
coordinates object 
{'coordinates': [ 16.449281999999997, 43.523876 ]}
 Represents the geographic location of this Tweet as reported by the user or client application. The inner coordinates array is formatted as geoJSON (longitude first, then latitude).
created datetime 
2016-10-24T16:15:04+00:00
 Tweet created time.
entities object 
{
'entities':
  'hashtags': [ {
    'indices': [ 10, 14 ]
    'text': 'bla'
  } ]
  'tags': [ {
    'id': '1964904343'
    'indices': [ 15, 26 ]
    'name': 'Jurica Grgicevic'
    'text': 'jgrgicevic'
    'type': 'user'
  } ]
}
 Entities provide metadata and additional contextual information about content posted on Twitter.
favorite_count integer 
100
 Number of times tweet was liked (favorited).
id string 
833759796105007104
 Tweet id.
in_reply_to_user_id string 
719525790308765697
 If the represented Tweet is a reply, this field will contain the integer representation of the original Tweet’s author ID.
interactions_count integer 
100
 Number of interactions.
language string 
en
 Indicates a BCP 47 language identifier corresponding to the machine-detected language of the Tweet text.
mentions array 
[ '1964904343' ]
 List of Twitter profile ids mentioned.
message string 
A free tool that delivers a custom benchmark report, in minutes, so you can easily understand how well you are using social media to nurture customer relationships. Do you know your numbers?
 Tweet content.
replies_count integer 
100
 Number of replies.
retweeted_user_id string 
719525790308765697
 If the represented Tweet is a retweet, this field will contain the integer representation of the original Tweet’s author ID.
shares_count integer 
100
 Number of shares.
source object 
{
  "name": 'Twitter Ads',
  "id": '<a href="https://ads.twitter.com" rel="nofollow">Twitter Ads</a>'
}
 id: HTML-formatted string linking to utility used to create the tweet; name: name of the utility
type string 
array
 List of tweet types.

Response

Name Description
success Status of the response. Possible values are true or false.
data object containing the following properties:
  • posts: array, containing post metric data
  • next: string, pagination cursor. Used for pagination over posts data.
  • remaining: integer, number of remaining items, counting from current page, until end of posts data.

Example request

POST /0/twitter/profile/tweets HTTPS
Host: api.socialbakers.com
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "profile": "1964904343",
  "date_start": "2016-01-01",
  "date_end": "2017-01-01",
  "fields": [
    "id",
    "author_id",
    "coordinates",
    "created",
    "entities",
    "favorite_count",
    "message",
    "source",
    "language",
    "retweeted_user_id",
    "type"
  ],
  "limit": 5
}

Example response

{
  "success": true,
  "data": {
    "posts": [
      {
        "source": {
          "name": "Twitter Web Client",
          "id": "Twitter Web Client"
        },
        "language": "en",
        "id": "689427258210004992",
        "created": "2016-01-19T12:40:41+00:00",
        "favorite_count": 2,
        "message": "How to Get More Value From Social Ads https://t.co/67C7Tm3fZx via @socialbakers",
        "entities": {
          "tags": [
            {
              "id": "78569316",
              "indices": [ 66, 79 ],
              "name": "Socialbakers",
              "text": "socialbakers",
              "type": "user"
            }
          ]
        },
        "author_id": "1964904343",
        "type": [
          "photo",
          "link"
        ]
      }
    ],
    "remaining": 0
  }
}

YouTube profile video metrics

Returns post metrics for each requested YouTube profile.

Parameters

Name Description
profile string, the value is ID of the profile available from the /0/youtube/profiles endpoint.
date_start string, the beginning of the period you want to get the data for in the format YYYY-MM-DD. The timezone is automatically selected from your account.
date_end numeric string, the end of the period you want to get the data for in the format YYYY-MM-DD, selected day will be included in the response. The timezone is automatically selected from your account.
fields array, the list of fields that will be returned in the response. Available fields are listed in the table below.
limit integer, (optional). The number of post results per page. Default value is 25.
after string, (optional). Pagination cursor. Points to the end of the page that has been returned.
Fields
Name Type Example Description
author_id string 
UCA6AG33Zac0xi6f9VMTxkFQ
 The ID that YouTube uses to uniquely identify the channel that the video was uploaded to.
comment_count integer 
100
 The number of comments for the video.
created datetime 
2018-09-03T16:15:04+00:00
 The date and time when the uploaded video file was created.
dislike_count integer 
100
 The number of users who have indicated that they disliked the video.
duration integer 
100
 The length of the video [s].
id string 
UCA6AG33Zac0xi6f9VMTxkFQ
 The ID that YouTube uses to uniquely identify the video.
interactions_count integer 
100
 The sum of Likes, Dislikes and Comments.
like_count integer 
100
 The number of users who have indicated that they liked the video.
message string 
Get caught up on the most important social media news of the week!\nBeginner-friendly guide to Influencer Marketing: http://goo.gl/aTWHRV
 The video's description.
published_time datetime 
2018-08-03T12:30:05+00:00
 The date and time when the video was published.
video_view_time integer 
100
 The number of time the video has been viewed multiplied by duration [s].
view_count integer 
100
 The number of times the video has been viewed.

Response

Name Description
success Status of the response. Possible values are true or false.
data object containing the following properties:
  • posts: array, containing post metric data
  • next: string, pagination cursor. Used for pagination over posts data.
  • remaining: integer, number of remaining items, counting from current page, until end of posts data.

Example request

POST /0/youtube/profile/videos HTTPS
Host: api.socialbakers.com
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "profile": "UCA6AG33Zac0xi6f9VMTxkFQ",
  "date_start": "2018-06-01",
  "date_end": "2018-08-31",
  "fields": [
    "id",
    "created",
    "message",
    "author_id",
    "comment_count",
    "duration",
    "video_view_time",
    "published_time",
    "dislike_count",
    "view_count",
    "like_count",
    "interactions_count"
  ]
  "limit": 5
}

Example response

{
  "success": true,
  "data": {
    "posts": [
      {
        "id": "6Ol7dJtKcq0",
        "created": "2018-06-15T14:41:32.000Z",
        "message": "Get caught up on the most important social media news of the week!\nBeginner-friendly guide to Influencer Marketing: http://goo.gl/aTWHRV",
        "author_id": "UCA6AG33Zac0xi6f9VMTxkFQ",
        "comment_count": 0,
        "like_count": 6,
        "duration": 114,
        "video_view_time": 41040,
        "published_time": "2018-06-15T14:41:32.000Z",
        "dislike_count": 0,
        "view_count": 360,
        "interactions_count": 6
      },
    ],
    "next": "eyJjdXJzb3IiOlt7ImZpZWxkIjoiY3JlYXRlZF90aW1lIiwidmFsdWUiOiIyMDE4LTA2LTI4VDEyOjM4OjM0KzAwOjAwIiwib3JkZXIiOiJkZXNjIn1dLCJpZHMiOlsiMTc4OTM5NTExNjIyMTY0NjRfNDkwNDAyMjIwIl19=",
    "remaining": 15
  }
}

Tableau Web Data Connector (WDC)

Introduction

Tableau is a business intelligence (BI) tool that can be used to create reports, charts, graphs and dashboards using different data sources.
Official documentation for Tableau Web Data Connector is available here: http://onlinehelp.tableau.com/current/pro/desktop/en-us/help.htm#examples_web_data_connector.html .

Socialbakers API is available as a data source for Tableau using a Web Data Connector.
The Socialbakers Web Data Connector is available at this address: https://api.socialbakers.com/tableau-wdc.

The same API authentication (token and secret) is used for the Tableau Web Data Connector, as described in Security and Authentication section.

Available metrics

Network Metrics
Facebook metrics all metrics except metrics prefixed with "insights_"
Instagram metrics all metrics except metrics prefixed with "insights_"
Twitter metrics all metrics
YouTube metrics all metrics
Pinterest metrics all metrics

Community

Currently only content labeling endpoints are available for Community.

Content Labeling

Add or remove labels to content in Community.

Requires labeling user permissions:

  • Edit Global Labels
  • Global Post Labeling

Currently supports the following networks: facebook, and twitter.

Caveats:

  • If the provided label does not exist, a global label will be created in the account.
  • Labeled content must exist in Community at the time of the API call.
  • The updates are immediately propagated into feeds.

Methods

PUT
Add labels to content
DELETE
Remove labels from content

Parameters

Name Description
content_ids array of network specific content IDs (status ID for Twitter, see below for Facebook content IDs). (required)
labels array of label names (strings) to add to content. (required)
Facebook Content IDs
Direct Messages
To label direct message conversation, prefix the conversation ID (e.g. t_100022491363476) with page ID and dash.
Example: Given page ID 558021681218098 and conversation ID t_100022491363476, the resulting content ID will be: 558021681218098-t_1200750755
Posts
To label specific page's post, prefix the post ID with page ID.
Example: Given page ID 164929129743 and post ID 10156439716079744, the resulting content ID is: 164929129743_10156439716079744
Post Comments
To label specific comment to a post, prefix the comment ID with post ID.
Example: Given post ID 10156439716079744 and comment ID 10156440099689744, the resulting content ID will be: 10156439716079744_10156440099689744.

Note: You can verify post and comment IDs by inserting them as path to Facebook URL. For example facebook.com/10156439716079744_10156440099689744 redirects to the comment. These composite IDs are compatible with Graph API too.

Response

Name Description
success Status of the response. Possible values are true or false.
data object containing the contents object of responses per individual contents.

Example request


        PUT /0/community/{network}/labels HTTPS
        Host: api.socialbakers.com
        Authorization: Basic base64_encoded_auth
        Content-Type: application/json; charset=utf-8

        {
            "content_ids": [
              // Facebook conversation ID
              "754387418054186-t_100022491363476",
              // Facebook page post ID
              "849715935050458_1520511894637588",
              // Twitter status ID
              "885811987728416769"
            ],
            "labels": ["my label"],
        }

Example response

{
            "success": true,
            "data": {
              "contents": {
                "754387418054186-t_100022491363476": {
                    "status": "ok"
                },
                "849715935050458_1520511894637588": {
                    "status": "ok"
                },
                "885811987728416769": {
                    "status": "ok"
                }
              }
            }
        }