Socialbakers API Documentation

Introduction

The Socialbakers REST 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).

Security and authentication

The API is secured with HTTPS. Authentication is made using Basic HTTP Authorization by token and secret. The authorization is sent in the HTTP headers.

The token and secret are linked to a specific user of a Socialbakers Suite account. Get in touch with our Support team at support@socialbakers.com to get yours.

Basic HTTP Authorization using token and secret

Basic HTTP Authorization uses a token and secret with a colon between them encoded to base64 format.

Example: if we use "Aladdin" as a token and "OpenSesame" as a secret, then "Aladdin:OpenSesame" produces "QWxhZGRpbjpPcGVuU2VzYW1l" when encoded to base64 format.

The parameter in the HTTP header would be then: Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

Example request

GET /3/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 all Profiles, metrics or date range limit exceeded
5 all Profiles not allowed for user
6 all Start date is before history limit date
7 all Profiles do not have insights enabled
8 all Labels used for filtering do not exists
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 header, invalid secret or 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 [164929129743] not allowed."
      ]
    }
  ]
}

Reference Data

Lists of values allowed to be used by other endpoints as data sources or filters.

List of Connected Profiles

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

Example request

              GET /3/{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, linkedin, pinterest, vkontakte

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.
profile_labels array, list of labels assigned to a given profile in the account.
insights_enabled boolean, available for facebook and instagram networks only, true if insights metrics are available for profile.
Example response
{
  "success": true,
  "profiles": [
    {
      "id": "164929129743",
      "name": "Profile #1 name",
      "profile_name": "profile1name",
      "picture": "https://example.cdn.com/picture.hash.png"
      "timezone": "America/Los_Angeles",
      "insights_enabled": true
    },
    {
      "id": "477018229123929",
      "name": "Profile #2 name",
      "picture": "https://example.cdn.com/picture.hash.png"
      "profile_name": "profile2name",
      "timezone": "Europe/Prague"
    },
    ...
  ]
}

List of Post Labels

Post labels are used to label content (posts, videos) across multiple platforms in Suite. The endpoint returns the list of all global post labels available in your account. These labels are identified by name and ID.

You can use the post label IDs to filter the posts or the results of the aggregated post metrics.

Example request

              GET /3/post/labels HTTPS
Host: api.socialbakers.com
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

Response fields

Name Description
id string, post label unique identifier
name string, post label name
Example response
{
  "success": true,
  "data": [
    {
      "id": "5d879004a44a4cbcb13e",
      "name": "Post Label 1"
    },
    {
      "id": "ffc196eb056b42fd9b03",
      "name": "Post Label 2"
    },
    ...
  ]
}

List of Profile Labels

Profile labels are used to label profiles across multiple platforms in Suite. The endpoint returns the list of all global profile labels available in your account. These labels are identified by name and ID.

Example request

            GET /3/profile/labels HTTPS
                Host: api.socialbakers.com
                Authorization: Basic base64_encoded_auth
                Content-Type: application/json; charset=utf-8

Response fields

Name Description
id string, profile label unique identifier
name string, profile label name
profiles array, information about profile tagged with the specific profile label
Example response
{
    "success": true,
    "data": [
        {
            "id": "5d879004a44a4cbcb13e",
            "name": "Profile Label 1",
            "profiles": [
                {
                    "name": "Profile 1",
                    "platform": "facebook"
                },
                {
                    "name": "Profile 2",
                    "platform": "twitter"
                }
            ]
        },
        {
            "id": "ffc196eb056b42fd9b03",
            "name": "Profile Label 2",
            "profiles": [],
        },
        ...
    ]
}

Profile Metrics

Profile metrics endpoints return daily values for the specified set of metrics and profiles.

Profile metrics attribute data to the profile/page, focusing on when engagement happened, regardless if a post was published during the analyzed date range or not. Data is aggregated by when it happened, and it is not related to a specific piece of content.

Aggregation is the type of calculation used for grouping values of a specific metric.

Facebook Metrics

Returns daily metrics for each requested Facebook profile.

Parameters

Name Description
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. The response uses a timezone assigned to a profile in Suite settings of the account. The last day will be also included in the response.
profiles object, the list of string values. Each is ID of the profile available from the /3/facebook/profiles endpoint.
metrics array, the list of metrics that will be returned in the response. Available metrics are listed in the table below.
dimensions array of {type: dimensionType} objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimension types for each metric in the table below. Dimensions marked with an asterisk* must be last, and only one such dimension can be used.
Basic Metrics
Name Dimensions Aggregation Metric description
fans_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of fans count of a page. No data available for FB pages that is part of the Global Page Structure and does not have insights connected.
fans_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of likes (=fans) of a page. No data available for FB pages that is part of the Global Page Structure and does not have insights connected.
Insights Metrics

Metrics prefixed with insights_ can only be used for profiles that have insights_enabled property set to true in the response of the /3/facebook/profiles endpoint.

Name Dimensions Aggregation Metric description
insights_activity date.day,
date.month,
date.week,
profile,
profile_label,
activity_type* 		sum Number of activities created about your Page. (Total Count)
insights_activity_unique date.day,
date.month,
date.week,
profile,
profile_label,
activity_type*,
gender_age*,
city*,
country*,
locale* 		avg The number of activities created about your Page. (Unique Users).
insights_engaged_users date.day,
date.month,
date.week,
profile,
profile_label 		avg Number of people who engaged with your Page. Engagement includes any click or story created. (Unique Users).
insights_fan_adds date.day,
date.month,
date.week,
profile,
profile_label,
like_source* 		sum Number of new people who have liked your Page.
insights_fan_adds_unique date.day,
date.month,
date.week,
profile,
profile_label,
like_source* 		avg New Likes : Number of new people who have liked your Page (Unique Users)
insights_fan_removes date.day,
date.month,
date.week,
profile,
profile_label 		sum Number of Unlikes of your Page (Total Count)
insights_fan_removes_unique date.day,
date.month,
date.week,
profile,
profile_label,
unlike_source* 		avg Number of Unlikes of your Page (Unique Users).
insights_fans_lifetime date.day,
date.month,
date.week,
profile,
profile_label,
country*,
city*,
locale*,
gender_age* 		avg The total number of people who have liked your Page. (Unique Users)
insights_fans_online date.day,
date.month,
date.week,
profile,
profile_label,
hour_of_day* 		sum Number of fans who saw any posts on a given day.
insights_impressions date.day,
date.month,
date.week,
profile,
profile_label,
activity_type*,
post_attribution* 		sum Total number of times any content associated with your page has been seen
insights_negative_feedback date.day,
date.month,
date.week,
profile,
profile_label 		sum The number of times people have given negative feedback to your Page. (Total Count).
insights_positive_feedback date.day,
date.month,
date.week,
profile,
profile_label,
positive_feedback_type* 		sum The number of times people have given positive feedback to your Page. (Total Count).
insights_post_clicks date.day,
date.month,
date.week,
profile,
profile_label,
click_type* 		sum The number of clicks on any of your content. Clicks generating stories are included in 'Other Clicks.'
insights_post_clicks_unique date.day,
date.month,
date.week,
profile,
profile_label,
click_type* 		avg The 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_post_impressions date.day,
date.month,
date.week,
profile,
profile_label,
post_attribution* 		sum The total number of impressions that came from all of your posts.
insights_post_reach date.day,
date.month,
date.week,
profile,
profile_label,
post_attribution*,
frequency_distribution* 		avg The number of people who saw any of your Page posts. (Unique Users). Note: The sum of each breakdown from the dimension frequency_distribution will not equal the total of insights_post_reach metric.
insights_reach date.day,
date.month,
date.week,
profile,
profile_label,
gender_age*,
post_attribution* 		avg The number of people who have seen any content associated with your Page. (Unique Users)
insights_reach_28_days date.day,
date.month,
date.week,
profile,
profile_label,
gender_age* 		avg The number of people who have seen any content associated with your Page in the past 28 days. (Unique Users)
insights_reach_7_days date.day,
date.month,
date.week,
profile,
profile_label,
gender_age* 		avg The number of people who have seen any content associated with your Page in the past 7 days. (Unique Users)
insights_reach_engagement date.day,
date.month,
date.week,
profile,
profile_label 		avg The total number of people who engaged with your Page per the number of people who have seen any content associated with your Page. Engagement includes any click or story created. (Unique Users)
insights_reactions date.day,
date.month,
date.week,
profile,
profile_label,
reaction_type* 		sum The number of reactions on any of your content
insights_video_complete_views_30s date.day,
date.month,
date.week,
profile,
profile_label,
play_type*,
post_attribution* 		sum Total number of times page's videos have been played for more than 30 seconds
insights_video_complete_views_30s_repeat_views date.day,
date.month,
date.week,
profile,
profile_label 		sum Number of times that people replay a page's videos for more than 30 seconds.
insights_video_complete_views_30s_unique date.day,
date.month,
date.week,
profile,
profile_label 		avg Number of times page's videos have been played for unique people for more than 30 seconds.
insights_video_repeat_views date.day,
date.month,
date.week,
profile,
profile_label 		sum Total number of times that people replay a page's videos for more than 3 seconds
insights_video_views date.day,
date.month,
date.week,
profile,
profile_label,
play_type*,
post_attribution* 		sum Total number of times page's videos have been played for more than 3 seconds
insights_video_views_unique date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of times page's videos have been played for unique people for more than 3 seconds
insights_views date.day,
date.month,
date.week,
profile,
profile_label 		sum The number of times a Page's profile has been viewed by logged in and logged out people.

Example request

POST /3/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": [
	"164929129743"
  ],
  "metrics": ["fans_lifetime"],
  "dimensions": [
  {
	"type": "date.day"
  }
  ]}

Example response


{
  "success": true,
  "header": [{
  "type": "date.day",
  "rows": [
	"2016-01-01",
	"2016-01-02"
  ]},
  {
  "type": "metric",
  "rows": [
	"fans_lifetime"
  ]
  }
  ],
  "data": [
  [
	209119
  ],
  [
	209171
  ]
  ]
}

Instagram Metrics

Returns daily metrics for each requested Instagram profile.

Parameters

Name Description
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. The response uses a timezone assigned to a profile in Suite settings of the account. The last day will be also included in the response.
profiles The list of string values. Each is ID of the profile available from the /3/instagram/profiles endpoint.
metrics The list of metrics that will be returned in the response. Available metrics are listed in the table below.
dimensions array of {type: dimensionType} objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimension types for each metric in the table below. Dimensions marked with an asterisk* must be last, and only one such dimension can be used.
Basic Metrics
Name Dimensions Aggregation Metric description
followers_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of followers count lifetime.
followers_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of followed-by of a user by day. Number is aggregated to the midnight of profile timezone.
following_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of follows of a user by day. Number is aggregated to the midnight of profile timezone.
following_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of people profile follows.
Insights Metrics

Metrics prefixed with insights_ can only be used for profiles that have insights_enabled property set to true in the response of the /3/instagram/profiles endpoint.

Name Dimensions Aggregation Metric description
insights_followers date.day,
date.month,
date.week,
profile,
profile_label,
country*,
locale*,
city*,
gender_age* 		avg Total number of followed-by of a user by day. Total value from this metric may not equal the value from dimension.
insights_impressions date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of times your posts and stories were viewed.
insights_impressions_28_days date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of times your posts and stories were viewed in past 28 days.
insights_impressions_7_days date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of times your posts and stories were viewed in the past 7 days.
insights_profile_clicks date.day,
date.month,
date.week,
profile,
profile_label,
click_target* 		sum The number of times user clicked on any contact links on your Business Account's profile.
insights_profile_views date.day,
date.month,
date.week,
profile,
profile_label 		avg The number of unique accounts who've visited your business profile.
insights_reach date.day,
date.month,
date.week,
profile,
profile_label 		avg Number of unique accounts who viewed your posts and stories.
insights_reach_28_days date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of people who have viewed any of your posts and stories in the past 28 days.
insights_reach_7_days date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of people who have viewed any of your posts and stories in the past 7 days.

Example request

POST /3/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": ["4108894671", "337453282"],
  "metrics": ["followers_change"],
  "dimensions": [
    {
      "type": "date.day"
    }
  ]
}

Example response


{
  "success":true,
  "header":[
      {
        "type":"date.day",
        "rows":[
            "2016-01-01",
            "2016-01-02"
        ]
      },
      {
        "type":"metric",
        "rows":[
            "followers_change"
        ]
      }
  ],
  "data":[
      [
        209119
      ],
      [
        209171
      ]
  ]
}

Twitter Metrics

Returns daily metrics for each requested Twitter profile.

Parameters

Name Description
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. The response uses a timezone assigned to a profile in Suite settings of the account. The last day will be also included in the response.
profiles The list of string values. Each is ID of the profile available from the /3/twitter/profiles endpoint.
metrics The list of metrics that will be returned in the response. Available metrics are listed in the table below.
dimensions array of {type: dimensionType} objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimension types for each metric in the table below. Dimensions marked with an asterisk* must be last, and only one such dimension can be used.
Basic Metrics
Name Dimensions Aggregation Metric description
ff_ratio date.day,
date.month,
date.week,
profile,
profile_label 		avg Ratio of total followers and total following aggregated by day.
followers_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of followers (=fans) of a profile. Number is aggregated by day.
followers_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of followers (=fans) of a profile. Number is aggregated by day.
following_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of how many people profile follows. Number is aggregated by day.
following_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of how many people profile follows
listed_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of on how many lists profile appears.
listed_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total count of on how many lists profile appears.

Example request

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

{
  "date_start": "2020-05-10",
	"date_end": "2020-05-18",
	"profiles": [ "78569316" ],
	"metrics": [ "ff_ratio" ],
	"dimensions": [
		{ "type": "profile" },
		{ "type": "date.day" }
	]
}

Example response


{
  "success": true,
  "header": [
    {
      "type": "profile",
      "rows": [
        "78569316"
      ]
    },
    {
      "type": "date.day",
      "rows": [
        "2020-05-10",
        "2020-05-11",
        "2020-05-12",
        "2020-05-13",
        "2020-05-14",
        "2020-05-15",
        "2020-05-16",
        "2020-05-17",
        "2020-05-18"
      ]
    },
    {
      "type": "metric",
      "rows": [
        "ff_ratio"
      ]
    }
  ],
  "data": [
    [
      [
        95.75070224719101
      ],
      [
        95.7436797752809
      ],
      [
        95.19622905027933
      ],
      [
        95.12351709699931
      ],
      [
        95.12072575017446
      ],
      [
        95.11235170969994
      ],
      [
        95.10118632240057
      ],
      [
        95.0907187718074
      ],
      [
        95.07327285415212
      ]
    ]
  ]
}

YouTube Metrics

Returns daily metrics for each requested YouTube profile.

Parameters

Name Description
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. The response uses a timezone assigned to a profile in Suite settings of the account. The last day will be also included in the response.
profiles The list of string values. Each is ID of the profile available from the /3/youtube/profiles endpoint.
metrics The list of metrics that will be returned in the response. Available metrics are listed in the table below.
dimensions array of {type: dimensionType} objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimension types for each metric in the table below. Dimensions marked with an asterisk* must be last, and only one such dimension can be used.
Metrics
Name Dimensions Aggregation Metric Description
interaction_change date.day,
date.month,
date.week,
profile,
profile_label,
interaction_type* 		sum Daily growth of interactions on all uploaded videos by the channel on a given day. Number is aggregated by day to the midnight of UTC timezone.
interactions_per_1k_fans date.day,
date.month,
date.week,
profile,
profile_label 		sum Daily growth of interactions per 1000 fans on all uploaded videos by the channel on a given day. Number is aggregated by day to the midnight of UTC timezone.
subscribers_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of subscribers count lifetime.
subscribers_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of subscribers of the channel.
video_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of uploaded videos by the channel on a given day. Number is aggregated by day to the UTC midnight.
viewed_time_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute daily growth of viewed time. Number is aggregated by day to the midnight of UTC. All values are provided in seconds.
views_change date.day,
date.month,
date.week,
profile,
profile_label 		sum This is the absolute daily growth of views. Number is aggregated by day to the midnight of UTC timezone.

Example request

POST /3/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": [
		"UCA6AG33Zac0xi6f9VMTxkFQ",
		"UCCAg0pGh47apFzefcJN6x3w"
	],
	"metrics": ["subscribers_change"],
	"dimensions": [{
		"type": "date.day"
	}]
}

Example response

{
      "success": true,
      "header": [
          {
              "type": "date.day",
              "rows": [
                  "2016-01-01",
                  "2016-01-02"
              ]
          },
          {
              "type": "metric",
              "rows": [
                  "subscribers_change"
              ]
          }
      ],
      "data": [
          [
              -3
          ],
          [
              1
          ]
      ]
  }

LinkedIn Metrics

Returns daily metrics for each requested LinkedIn profile.

Parameters

Name Description
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. The response uses a timezone assigned to a profile in Suite settings of the account. The last day will be also included in the response.
profiles The list of string values. Each is ID of the profile available from the /3/linkedin/profiles endpoint.
metrics The list of metrics that will be returned in the response. Available metrics are listed in the table below.
dimensions array of {type: dimensionType} objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimension types for each metric in the table below. Dimensions marked with an asterisk* must be last, and only one such dimension can be used.
Metrics
Name Dimensions Aggregation Metric Description
followers_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of followers of a company by day. Number is aggregated to the midnight of selected timezone.
followers_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of followers of a company by day. Number is aggregated to the midnight of selected timezone.

Example request

POST /3/linkedin/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": [
          "urn:li:organization:14846557"
      ],
      "metrics": ["followers_change"],
      "dimensions": [{
          "type": "date.day"
      }]
  }

Example response

{
        "success": true,
        "header": [
            {
                "type": "date.day",
                "rows": [
                    "2016-01-01",
                    "2016-01-02"
                ]
            },
            {
                "type": "metric",
                "rows": [
                    "followers_change"
                ]
            }
        ],
        "data": [
            [
                2
            ],
            [
                1
            ]
        ]
    }

Pinterest Metrics

Returns daily metrics for each requested Pinterest profile.

Parameters

Name Description
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. The response uses a timezone assigned to a profile in Suite settings of the account. The last day will be also included in the response.
profiles The list of string values. Each is ID of the profile available from the /3/pinterest/profiles endpoint.
metrics The list of metrics that will be returned in the response. Available metrics are listed in the table below.
dimensions array of {type: dimensionType} objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimension types for each metric in the table below. Dimensions marked with an asterisk* must be last, and only one such dimension can be used.
Metrics
Name Dimensions Aggregation Metric description
boards_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of number of profile boards. Number is aggregated by day.
boards_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of boards of the profile.
followers_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of followers of a profile.
followers_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of followers of the profile. Number is aggregated by day.
following_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of followed profiles. Number is aggregated by day.
following_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of followed profiles.
pins_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of pins of the profile.

Example request

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

{
  "date_start": "2020-05-10",
	"date_end": "2020-05-18",
	"profiles": [ "376684093741466051" ],
	"metrics": [ "boards_change" ],
	"dimensions": [
		{ "type": "profile" },
		{ "type": "date.day" }
	]
}

Example response


      {
        "success": true,
        "header": [
            {
                "type": "profile",
                "rows": [
                    "376684093741466051"
                ]
            },
            {
                "type": "date.day",
                "rows": [
                    "2020-05-10",
                    "2020-05-11",
                    "2020-05-12",
                    "2020-05-13",
                    "2020-05-14",
                    "2020-05-15",
                    "2020-05-16",
                    "2020-05-17",
                    "2020-05-18"
                ]
            },
            {
                "type": "metric",
                "rows": [
                    "boards_change"
                ]
            }
        ],
        "data": [
            [
                [
                    0
                ],
                [
                    0
                ],
                [
                    0
                ],
                [
                    0
                ],
                [
                    0
                ],
                [
                    0
                ],
                [
                    0
                ],
                [
                    0
                ],
                [
                    0
                ]
            ]
        ]
    }

Posts

The endpoints in this section return a list of posts/videos/tweets, accompanied by the fields you specify. It can be an attribute of the post (text, created time, author, id, paid status) or metric (Number of comments, Number of Likes).

Facebook Page Posts Metrics

Returns a set of posts created during the specified date range for each requested Facebook profile. Facebook posts endpoint returns lifetime values of the metrics.

Parameters

Name Description
profiles array, list of profile IDs of the profiles available from the /3/facebook/profiles endpoint.
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. Your request is transformed using the time zone assigned to a profile in the Suite settings of your account. The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct timezone using the timezone of each individual profile from the /3/facebook/profiles endpoint. The last day will be also included in the response.
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 results per page. The default value is 10 and the maximal value is 500.
after string, (optional). Pagination cursor. Points to the end of the page that has been returned.
sort You can sort the results by specifying a field and sorting order in the sort object: "field": "created_time" and "order": "desc". See the list of fields allowed for sorting.
filter You can filter results by providing the filter parameter with field and value. See the list of fields allowed for filtering.
Basic 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", "type": "photo"}]
 Details about post attachments.
author object 
{ "id": "164929129743", "name": "Socialbakers", "url": "https://www.facebook.com/socialbakers"}]
 Author details of the post.
comments integer 
15
 Total number of comments.
comments_sentiment object 
{ "positive": 4, "neutral": 5, "negative": 1 }
 Total sentiment for the comments of the post. Sum of sentiment breakdown might not equal the total comments. There would be comments which sentiment are either unassigned or undetected. For stories, this value is undefined since users can not comment on them.
content string 
Today is #InternationalBeerDayđŸ»
 Content of the Facebook post.
content_type string 
post|shared
 Content type of the Facebook post.
created_time datetime 
2016-10-24T16:15:04+00:00
 Date and time the post was created in Facebook.
deleted boolean 
true
 Describes if the post has been deleted on Facebook.
grade string 
C
 Grade score of the post.
hidden boolean 
false
 Describes if the post has been hidden from Facebook.
id string 
164929129743_10154702368914744
 Facebook post id.
interactions integer 
32
 Sum of reactions, comments and shares.
interactions_per_1k_fans float 
0.12
 Interaction count for every 1000 fans.
media_type string 
status|link|video|note|poll|carousel|animated_gif|album|offer|photo
 Type of Facebook post.
origin string 
User-Generated Content|Brand's Content
 Source of post.
page object 
{ "id": "164929129743", "name": "Socialbakers", "url": "https://www.facebook.com/socialbakers" }
 Information about the Facebook page.
post_attribution object 
{ "status": "paid", "type": "ppd" }
 Type of post whether it's organic or paid. For posts from a profile with insights connected, data comes directly from Facebook. For the rest of the posts, the attribution is based on Socialbakers Paid Post Detection algorithm.
post_labels array 
[{ "id": "2a8545bcc98b48d1a0c4", "name": "label A"}]
 Post labels assigned to the post.
published boolean 
true
 Describes if the post is published.
reactions integer 
15
 Total number of reactions.
reactions_by_type object 
{"like": 8, "love": 0, "wow": 0, "haha": 0, "sorry": 0, "anger": 0}
 Breakdown of reactions.
sentiment string 
neutral
 Facebook page post sentiment.
shares integer 
15
 Number of times the post has been shared.
spam boolean 
false
 Describes if the post has been marked as spam.
universal_video_id integer 
15
 The publishers asset management code for this video. Only available in case the post type is a video.
url string 
https://www.facebook.com/657747477695267/posts/2037994753003859
 Link to the Facebook post.
video object 
{"id": "4200898453277020", "length": 16, "crosspost": false, "crosspostable": false, "live": false, "shared": false}
 Details about the post's video.
Insights Fields

Metrics prefixed with insights_ can only be used for profiles that have insights_enabled property set to true in the response of the /3/facebook/profiles endpoint.

Name Type Example Description
insights_engaged_users integer 
100
 The number of people who clicked anywhere in your posts
insights_impressions integer 
100
 The number of impressions for your post.
insights_impressions_by_post_attribution object 
{ "paid": 0, "organic": 34, "viral": 10 }
 The number of impressions broken down by post attribution.
insights_interactions integer 
100
 Sum of reactions, comments and shares.
insights_interactions_by_interaction_type object 
{ "comment": 0, "like": 5, "share": 3 }
 Count of reactions, comments and shares.
insights_negative_feedback_unique integer 
20
 The number of people who took a negative action in your post (hid it, for example)
insights_post_clicks string 
12
 The number of times people clicked on anywhere in your posts without generating an activity.
insights_post_clicks_by_clicks_type object 
{ "link_clicks": null, "button_clicks": 4, "other_clicks": 22, "photo_views": null, "video_plays": 6 }
 The number of times people clicked on anywhere in your posts without generating an activity.
insights_post_clicks_unique integer 
10
 The number of people who clicked anywhere in your post without generating an activity.
insights_reach integer 
100
 The number of people who saw your post.
insights_reach_by_post_attribution object 
{ "paid": 100, "organic": 0, "viral": 0 }
 The number of people who saw your post.
insights_reach_engagement_rate float 
0.34
 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_reactions integer 
100
 Total reactions.
insights_reactions_by_type object 
{ "anger": 1, "haha": null, "like": 3, "love": 10, "sorry": null, "wow": 1 }
 Breakdown of reactions.
insights_video_view_time intager 
2657
 The total number of seconds your video was watched, including replays and views less than 3 seconds.
insights_video_view_time_average float 
125.7
 Facebook page post sentiment.
insights_video_view_time_by_distribution object 
{ "owned": 234, "shared": 125 }
 The total number of seconds your video was watched, including replays and views less than 3 seconds.
insights_video_view_time_by_post_attribution object 
{ "organic": 12, "paid": 5 }
 The total number of seconds your video was watched, including replays and views less than 3 seconds.
insights_video_views integer 
35
 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_10s integer 
125
 The number of times your video has been viewed for more than 10 seconds.
insights_video_views_10s_by_play_type object 
{ "autoplayed": 5, "click_to_play": 5 }
 The number of times your video has been viewed for more than 10 seconds.
insights_video_views_10s_by_post_attribution object 
{ "organic": 5, "paid": 10 }
 The number of times your video has been viewed for more than 10 seconds.
insights_video_views_10s_by_sound object 
{ "on": 10, "off": 4 }
 The number of times your video has been viewed for more than 10 seconds.
insights_video_views_10s_unique integer 
20
 The number of people who have watched your video for at least 10 seconds.
insights_video_views_30s integer 
30
 The number of times your video has been viewed for more than 30 seconds.
insights_video_views_30s_by_play_type object 
{ "autoplayed": 12, "click_to_play": 2 }
 The number of times your video has been viewed for more than 30 seconds.
insights_video_views_30s_by_post_attribution object 
{ "organic": 12, "paid: 4" }
 The number of times your video has been viewed for more than 30 seconds.
insights_video_views_30s_unique integer 
30
 The number of people who have watched your video for at least 30 seconds.
insights_video_views_average_completion float 
350.34
 The average number of times your video has been viewed for about 95% of its length.
insights_video_views_by_play_type object 
{ "autoplayed": 10, "click_to_play": 2 }
 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_by_post_attribution object 
{ "organic": 10, "paid": 2 }
 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_by_sound object 
{ "on": 12, "off": 5 }
 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_complete integer 
10
 The number of times your video has been viewed for about 95% of its length.
insights_video_views_complete_by_post_attribution object 
{ "organic": 12, "paid": 4 }
 The number of times your video has been viewed for about 95% of its length.
insights_video_views_complete_unique integer 
12
 The number of people who have watched your video for about 95% of its length.
insights_video_views_complete_unique_by_post_attribution object 
{ "organic": 12, "paid": 5 }
 The number of people who have watched your video for about 95% of its length.
insights_video_views_distribution object 
{ "owned": 5, "shared": 10 }
 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_unique integer 
13
 The number of people who have watched your video for at least 3 seconds.
insights_video_views_unique_by_post_attribution object 
{ "organic": 12, "paid": 5 }
 The number of people who have watched your video for at least 3 seconds.

Fields that might be used to sort Facebook posts:
Basic Fields
  • comments
  • created_time
  • interactions
  • interactions_per_1k_fans
  • reactions
  • reactions_by_type.anger
  • reactions_by_type.haha
  • reactions_by_type.like
  • reactions_by_type.love
  • reactions_by_type.sorry
  • reactions_by_type.wow
  • shares
Insights Fields
  • insights_engaged_users
  • insights_post_clicks
  • insights_reach_by_post_attribution.organic
  • insights_reach_by_post_attribution.paid
  • insights_reach_engagement_rate
  • insights_video_view_time_average
  • insights_video_views_10s
  • insights_video_views_by_post_attribution.organic
  • insights_video_views_by_post_attribution.paid

Fields that might be used to filter Facebook posts:
Basic Fields
  • content_type - ["post", "shared"]
  • grade - ["A+", "A", "B", "C", "D"]
  • media_type - ["status", "link", "video", "note", "poll", "offer", "photo", "carousel"]
  • origin - ["User-Generated Content", "Brand's Content"]
  • post_attribution - ["organic", "paid"]
  • post_labels - This field supports advanced post filters.
  • video_type - ["crosspost", "crosspostable", "live", "shared"]

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 /3/facebook/page/posts HTTPS
Host: api.socialbakers.com
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "profiles": ["164929129743", "543567853435"],
  "date_start": "2017-07-01",
  "date_end": "2017-10-25",
  "fields": [
    "id",
    "created_time",
    "message",
    "comments",
    "shares",
    "reactions",
    "interactions",
    "url",
    "author_id",
    "page_id",
    "attachments",
    "type",
    "reactions_by_type",
    "story",
    "insights_impressions",
    "insights_impressions_paid",
    "insights_paid_status",
    "insights_engaged_users",
    "insights_video_avg_time_watched",
    "insights_engagement_rate",
    "insights_post_clicks_by_type",
    "insights_post_clicks_by_type_unique",
    "universal_video_id",
    "video_id",
    "ppd_status",
    "video_length",
    "post_labels"
  ],
  "sort": [{
    "field": "created_time",
    "order": "desc"
  }],
  "filter": [{
    "field": "type",
    "value": ["video"]
  }, {
    "field": "insights_paid_status",
    "value": "paid",
  }, {
    "match_any": [{
      "field": "post_labels",
      "value": [
        "fa14dde7e4f041e3a646",
        "890c135d9cee4cf89b42"
      ]
    }]
  }],
  "limit": 5
}

Example response

{
  "success": true,
  "data": {
    "posts": [
      {
        "id": "164929129743_10154736430664744",
        "created_time": "2016-11-04T13:00:08+00:00",
        "message": "Brainstorming on your social media content? This tool will help ↓",
        "comments": 10,
        "shares": 20,
        "reactions": 70,
        "interactions": 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_by_type": {
          "like": 10,
          "love": 20,
          "wow": 30,
          "haha": 5,
          "sorry": 3,
          "anger": 2
        },
        "post_labels": [{
          "id": "fa14dde7e4f041e3a646",
          "name": "Post Label 1"
        }],
        "story": "Socialbakers published a note",
        "insights_impressions": 3583,
        "insights_impressions_paid": 496,
        "insights_paid_status": "paid",
        "insights_engaged_users": 50,
        "insights_video_avg_time_watched": 60000,
        "video_id": "1072177562941323",
        "ppd_status": "organic",
        "video_length": 125.481,
        "universal_video_id": "164929129743_10154736430664744",
        "insights_post_clicks_by_type": {
          "other clicks": 381,
          "link clicks": 48,
          "video play": 530
        },
        "insights_post_clicks_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 a set of posts created during the specified date range for each requested Instagram profile. Instagram posts endpoint returns lifetime values of the metrics.

Parameters

Name Description
profiles array, list of profile IDs of the profiles available from the /3/instagram/profiles endpoint.
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. Your request is transformed using the time zone assigned to a profile in the Suite settings of your account. The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct timezone using the timezone of each individual profile from the /3/instagram/profiles endpoint. The last day will be also included in the response.
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 results per page. The default value is 10 and the maximal value is 500.
after string, (optional). Pagination cursor. Points to the end of the page that has been returned.
sort You can sort the results by specifying a field and sorting order in the sort object: "field": "created_time" and "order": "desc". See the list of fields allowed for sorting.
filter You can filter results by providing the filter parameter with field and value. See the list of fields allowed for filtering.
Basic Fields
Name Type Example Description
attachments array 
[{ "image_url": "https://scontent-sea1-1.cdninstagram.com/v/t51.2885-15/65870902_147436403025286_4108244888990266821_n.jpg?_nc_cat=109&_nc_sid=8ae9d6&_nc_ohc=DJ0kCnsbf5QAX_acZuB&_nc_ht=scontent-sea1-1.cdninstagram.com&oh=bd44242c1ef473f8efff17f285dc5c86&oe=5F003D93", "type": "photo" }]
 Details about post attachments.
author object 
{"id": "490402220", "name": "Socialbakers", "url": "https://instagram.com/socialbakers"}
 Author details of the post.
comments integer 
15
 Total number of comments.
comments_sentiment object 
{ "positive": 1, "neutral": 5, "negative": 1 }
 Total sentiment for the comments of the post. Sum of sentiment breakdown might not equal the total comments. There would be comments which sentiment are either unassigned or undetected. For stories, this value is undefined since users can not comment on them.
content string 
Do you know which age groups and genders are most likely to follow a brand page on 📾#Instagram?
 Content of the Instagram post.
content_type string 
post|story
 Content type of the Instagram post.
created_time datetime 
2016-10-24T16:15:04+00:00
 Date and time the post was created in Instagram.
grade string 
C
 Grade score of the post.
id string 
17966172199068623_490402220
 Instagram post or story id.
interactions integer 
10
 Sum of reactions, comments and shares.
interactions_per_1k_fans float 
0.12
 Interaction count for every 1000 fans.
likes integer 
45
 Total number of likes.
media_type string 
video|photo|carousel
 Type of Instagram post.
page object 
{ "id": "490402220", "name": "Socialbakers", "url": "https://instagram.com/socialbakers" }
 Information about the Instagram profile.
post_attribution object 
{ "status": "organic", "type": "insights" }
 Type of post whether it's organic or paid. For posts from a profile with insights connected, data comes directly from Instagram. For the rest of the posts, the attribution is based on Socialbakers Paid Post Detection algorithm.
post_labels array 
[{ "id": "2a8545bcc98b48d1a0c4", "name": "label A"}]
 Post labels assigned to the post.
sentiment string 
neutral
 Instagram post sentiment.
url string 
https://instagram.com/stories/socialbakers/2342286418084049209
 Link to the Instagram post.
Insights Fields

Metrics prefixed with insights_ can only be used for profiles that have insights_enabled property set to true in the response of the /3/instagram/profiles endpoint.

Name Type Example Description
insights_engagement integer 
100
 Number of likes, saves and comments on your post.
insights_engagement_by_engagement_type object 
{ "comments": 0, "likes": 5, "saves": 10 }
 Breakdown of insights_engagement.
insights_impressions integer 
100
 The number of impressions for your post.
insights_reach integer 
100
 Number of people who saw your post.
insights_saves integer 
12
 Number of unique accounts that saved your post.
insights_story_completion_rate float 
0.42
 The percentage of times a story impression was not interrupted by an exit, tap back, or tap forward.
insights_story_exits integer 
15
 The number of times users exited your story.
insights_story_replies integer 
1
 The number of times users replied to your story.
insights_story_taps_back integer 
87
 The number of times users clicked back to return to the previous story.
insights_story_taps_forward integer 
11
 The number of times users clicked forward to skip to the next story.
insights_video_views integer 
768
 Total number of times your video has been seen. This will return 0 for videos in carousel albums.

Fields that might be used to sort Instagram posts:
Basic Fields
  • comments
  • created_time
  • interactions
  • interactions_per_1k_fans
  • likes
Insights Fields
  • insights_impressions
  • insights_reach
  • insights_saves
  • insights_story_completion_rate
  • insights_story_exits
  • insights_story_taps_back
  • insights_story_taps_forward
  • insights_video_views

Fields that might be used to filter Instagram posts:
Basic Fields
  • content_type - ["post", "story"]
  • grade - ["A+", "A", "B", "C", "D"]
  • media_type - ["video", "photo", "carousel"]
  • post_attribution - ["organic", "paid"]
  • post_labels - This field supports advanced post filters.

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 /3/instagram/profile/posts HTTPS
Host: api.socialbakers.com
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "profiles": ["490402220", "55674325"],
  "date_start": "2018-06-01",
  "date_end": "2018-08-31",
  "fields": [
    "interactions",
    "comments",
    "likes",
    "insights_engagement",
    "insights_saved",
    "insights_reach",
    "insights_video_views",
    "insights_impressions",
    "id",
    "author_id",
    "created_time",
    "type",
    "message",
    "attachments",
    "post_labels",
    "url"
  ],
  "sort": [{
    "field": "created_time",
    "order": "desc"
  }],
  "filter": [{
    "field": "type",
    "value": ["image"]
  }, {
    "match_any": [{
      "field": "post_labels",
      "value": [
        "fa14dde7e4f041e3a646",
        "890c135d9cee4cf89b42"
      ]
    }]
  }],
  "limit": 5
}

Example response

{
  "success": true,
  "data": {
    "posts": [
      {
        "id": "17966172199068623_490402220",
        "created_time": "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 📝",
        "comments": 9,
        "likes": 86,
        "author_id": "490402220",
        "type": "video",
        "interactions": 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"
              }
            ]
          }
        ],
        "post_labels": [{
          "id": "890c135d9cee4cf89b42",
          "name": "Post Label 1"
        }],
        "insights_engagement": 148,
        "insights_saved": 52,
        "insights_reach": 3094,
        "insights_video_views": 923,
        "insights_impressions": 4178,
        "url": "https://www.instagram.com/p/Bk4f5J_gypJ/"
      }
    ],
    "next": "eyJjdXJzb3IiOlt7ImZpZWxkIjoiY3JlYXRlZF90aW1lIiwidmFsdWUiOiIyMDE4LTA2LTI4VDEyOjM4OjM0KzAwOjAwIiwib3JkZXIiOiJkZXNjIn1dLCJpZHMiOlsiMTc4OTM5NTExNjIyMTY0NjRfNDkwNDAyMjIwIl19=",
    "remaining": 15
  }
}

YouTube Profile Video Metrics

Returns a set of videos created during the specified date range for each requested YouTube channels. YouTube videos endpoint returns lifetime values of the metrics.

Parameters

Name Description
profiles array, list of profile IDs of the profiles available from the /3/youtube/profiles endpoint.
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. Your request is transformed using the time zone assigned to a profile in the Suite settings of your account. The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct timezone using the timezone of each individual profile from the /3/youtube/profiles endpoint. The last day will be also included in the response.
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 results per page. The default value is 10 and the maximal value is 500.
after string, (optional). Pagination cursor. Points to the end of the page that has been returned.
sort You can sort the results by specifying a field and sorting order in the sort object: "field": "created_time" and "order": "desc". See the list of fields allowed for sorting.
filter You can filter results by providing the filter parameter with field and value. See the list of fields allowed for filtering.
Basic Fields
Name Type Example Description
author object 
{"id": "UCA6AG33Zac0xi6f9VMTxkFQ","name": "Socialbakers","url": "https://www.youtube.com/channel/UCA6AG33Zac0xi6f9VMTxkFQ"}
 Author details of the video.
channel object 
{"id": "UCA6AG33Zac0xi6f9VMTxkFQ","name": "Socialbakers","url": "https://www.youtube.com/channel/UCA6AG33Zac0xi6f9VMTxkFQ"}
 Information about the Youtube channel.
comments integer 
42
 Total number of comments.
created_time datetime 
2018-09-03T16:15:04+00:00
 Date and time the video was uploaded on Youtube.
description string 
Today is #InternationalBeerDayđŸ»
 Description of the Youtube video.
dislikes integer 
42
 Number of dislikes for the video.
duration integer 
42
 Length of the video in seconds.
id string 
UCA6AG33Zac0xi6f9VMTxkFQ
 Youtube video id.
interactions integer 
42
 Sum of reactions, comments and shares.
interactions_per_1k_fans float 
42.42
 Interaction count for every 1000 subscribers.
likes integer 
42
 Number of likes for the video.
media_type string 
video
 Type of Youtube video.
post_labels array 
[{ "id": "2a8545bcc98b48d1a0c4", "name": "label A"}]
 Post labels assigned to the video.
url string 
https://www.youtube.com/watch?v=9AVkNQ0kDTA
 Link to the Youtube video.
video_view_time integer 
42
 Number of times the video has been viewed multiplied by the duration in seconds.
video_views integer 
42
 Number of times the video has been viewed.

Fields that might be used to sort YouTube profile video:
Basic Fields
  • comments
  • created_time
  • dislikes
  • duration
  • interactions
  • interactions_per_1k_fans
  • likes
  • video_view_time
  • video_views

Fields that might be used to filter YouTube profile video:
Basic Fields

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 /3/youtube/profile/videos HTTPS
Host: api.socialbakers.com
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "profiles": ["UCA6AG33Zac0xi6f9VMTxkFQ"],
  "date_start": "2018-06-01",
  "date_end": "2018-08-31",
  "fields": [
    "author",
    "created_time",
  ],
  "sort": [{
    "field": "created_time",
    "order": "desc"
  }],
  "limit": 5
}

Example response

{
  "success": true,
  "data": {
    "posts": [
      {
        "author": {
          "id": "UCA6AG33Zac0xi6f9VMTxkFQ",
          "name": "Socialbakers",
          "url": "https://www.youtube.com/channel/UCA6AG33Zac0xi6f9VMTxkFQ",
        },
        "created_time": "2019-04-08T14:36:03+00:00"
      },
    ],
  }
}

Twitter Tweets Metrics

Returns tweets metrics for each requested Twitter profile.

According to the Twitter Developer Policies, the Socialbakers API no longer provides details regarding the individual Tweets. Tweet IDs, Author ID, Created Time, and Post Labels assigned in Socialbakers Suite can be still requested for manual analysis.

Parameters

Name Description
profiles array, list of profile IDs of the profiles available from the /3/twitter/profiles endpoint.
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. Your request is transformed using the time zone assigned to a profile in the Suite settings of your account. The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct timezone using the timezone of each individual profile from the /3/twitter/profiles endpoint. The last day will be also included in the response.
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 results per page. The default value is 10 and the maximal value is 500.
after string, (optional). Pagination cursor. Points to the end of the page that has been returned.
filter You can filter results by providing the filter parameter with field and value. See the list of fields allowed for filtering.
Basic Fields
Name Type Example Description
id string 
164929129743_10154702368914744
 Twitter tweet id.
origin string 
User-Generated Content|Brand's Content
 Source of post.
post_labels array 
[{"id": 78569316, "name": "Label Name"}]
 Post labels assigned to the post.
profile object 
{"id": 78569316}
 Information about the Twitter profile.

Fields that might be used to filter Twitter posts:
Basic Fields
  • content_type - ["post", "shared", "reply"]
  • media_type - ["status", "link", "video", "photo", "animated_gif"]
  • origin - ["User-Generated Content", "Brand's Content"]
  • post_labels - This field supports advanced post filters.

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 /3/twitter/profile/tweets HTTPS
Host: api.socialbakers.com
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "profiles": ["78569316"],
  "date_start": "2020-07-20",
  "date_end": "2020-07-23",
  "fields": ["id"],
  "limit": 1
}

Example response


{
  "success": true,
  "data": {
    "posts": [
        {
            "id": "123"
        }
    ],
    "next": "eyJxdWVyeSI6eyJmZWVkVHlwZSI6InVzZXJGZWVkIiwiZmllbGRzIjpbImNyZWF0ZWRUaW1lIiwib3JpZ2luIiwiYXV0aG9ySWQiLCJwcm9maWxlSWQiLCJtb25pdG9yZWRQcm9maWxlSWQiLCJzdG9yYWdlVHlwZSJdLCJmaWx0ZXJzIjpbeyJ0eXBlIjoib3IiLCJmaWx0ZXJzIjpbeyJ0eXBlIjoiYW5kIiwiZmlsdGVycyI6W3sidHlwZSI6ImNyZWF0ZWRUaW1lIiwicmFuZ2UiOnsiZnJvbSI6IjIwMjAtMDctMjBUMDA6MDA6MDBaIiwidG8iOiIyMDIwLTA3LTIzVDIzOjU5OjU5WiJ9fSx7InR5cGUiOiJwcm9maWxlSWQiLCJwcm9maWxlcyI6W3sicHJvZmlsZUlkIjpbIjc4NTY5MzE2Il0sIm5ldHdvcmsiOiJ0d2l0dGVyIn1dfV19XX0seyJ0eXBlIjoibmV0d29yayIsInZhbHVlIjpbImZhY2Vib29rIiwidHdpdHRlciIsInBpbnRlcmVzdCIsImluc3RhZ3JhbSIsInlvdXR1YmUiLCJ2a29udGFrdGUiLCJsaW5rZWRpbiJdfV0sImxpbWl0Ijo1LCJhY2NvdW50SWQiOiIxNzIxOTYiLCJ1c2VySWQiOiJkMTk2MTA4NyIsInRvZ2dsZXMiOlsiQ09NTVVOSVRZX1NFVF9ET05FX0FGVEVSX1JFUExZIiwiQ09OVEVOVF9TRU5USU1FTlQiLCJBTkFMWVRJQ1NfTU9EVUxFIiwiQVVESUVOQ0VTX1RFQVNJTkciLCJQVUJMSVNIX01PRFVMRSIsIlRPS0VOX0ZMT1ciLCJBRFNfQkVOQ0hNQVJLUyIsIkxJTktFRElOX0NPTU1VTklUWSIsIkFVVE9NQVRFRF9TRU5USU1FTlRfQUNDRVBURUQiLCJBVVRPTUFURURfU0VOVElNRU5UIiwiQURfQUNDT1VOVFNfUk9MRVNfUEVSTUlTU0lPTlMiLCJBUFBST1ZBTF9GTE9XIiwiQVVUT0xBQkVMSU5HIiwiREFTSEJPQVJEX09NTklfV0lER0VUUyIsIkZJTEVTVEFDS19GVUxMIiwiSU5TVEFHUkFNX0FEU19QVUJfQ09NIiwiSU5TVEFHUkFNX1ZJREVPX1BVQkxJU0hJTkciLCJMSU5LRURJTl9QVUJMSVNISU5HIiwiTU9CSUxFX0NPTU1VTklUWV9NT0RVTEUiLCJDT05URU5UX0hVQl9NT0RVTEUiLCJSVUxFX0JBU0VEX0xBQkVMSU5HIiwiQ09OVEVOVF9IVUJfQ09MTEVDVElPTlMiLCJQQUlEX01PRFVMRSIsIlBVQkxJU0hFUl9FWFRFUk5BTCIsIlRXX0lOU0lHSFRTIiwiQ09NTVVOSVRZX01PRFVMRSIsIkFEU19CRU5DSE1BUktTX0ZVTExfQUNDRVNTIiwiQkVOQ0hNQVJLU19NVUxUSUNPTVBBUkUiLCJDQU1QQUlHTl9WSUVXIiwiQ09OVEVOVF9TRUFSQ0hfUFJPIiwiREFTSEJPQVJEX01PRFVMRSIsIkdPT0dMRV9BTkFMWVRJQ1MiLCJMSVNURU5JTkciLCJMSVZFX1ZJREVPX01FVFJJQ1MiLCJQQUlEX1BPU1RfREVURUNUSU9OIiwiUEFJRF9QT1NUX0RFVEVDVElPTl9JRyIsIlBPU1RfQk9PU1RJTkciLCJQUklNRVRJTUUiLCJWSURFT19CRU5DSE1BUktTX0ZVTExfQUNDRVNTIiwiQlVTSU5FU1NfVE9HR0xFX1BVQkxJU0hFUl9JR19VU0VSU19UQUdHSU5HIiwiSU5GTFVFTkNFUlNfTU9EVUxFIiwiUEVSTUlTU0lPTlNfQllfU0VDVElPTlMiLCJCVVNJTkVTU19UT0dHTEVfU1RPUklFU19TQ0hFRFVMSU5HIiwiQlVTSU5FU1NfVE9HR0xFX0FTVFVURV9JTlRFR1JBVElPTiIsIkJVU0lORVNTX1RPR0dMRV9MSU5LRURJTl9UQVJHRVRJTkciLCJCVVNJTkVTU19UT0dHTEVfUFVCTElTSEVSX0lHX0xPQ0FUSU9OX1RBR0dJTkciLCJDT05URU5UX1BSRURJQ1RJT04iLCJDT05URU5UX1BSRURJQ1RJT05fSUciLCJQVUJMSVNIRVJfRkJfU0NIRURVTElORyIsIkJVU0lORVNTX1RPR0dMRV9JR19PUkdBTklDX1BBSURfUkVNT1ZBTF9JTlRFUklNIiwiQlVTSU5FU1NfVE9HR0xFX0lHX09SR0FOSUNfUEFJRF9SRU1PVkFMX0ZJTkFMIiwiQkVUQV9NT0JJTEVfQ09NTVVOSVRZX01PRFVMRSIsIkFVRElFTkNFU19NT0RVTEUiLCJCVVNJTkVTU19UT0dHTEVfQ09NTVVOSVRZX1JFUE9SVElORyIsIlNVSVRFX0FEUyIsIkJVU0lORVNTX1RPR0dMRV9QQUlEX1NUT1JFRF9EQVRBIiwiQlVTSU5FU1NfVE9HR0xFX1BSSU9SSVRZX1NDT1JFIiwiSU5GTFVFTkNFUlNfRlVMTF9BQ0NFU1MiXSwicHJvZmlsZXMiOlt7InByb2ZpbGVJZCI6WyI3ODU2OTMxNiJdLCJuZXR3b3JrIjoidHdpdHRlciIsInRpbWV6b25lIjoiVVRDIiwiaW5zaWdodHMiOnRydWUsIm1hbmFnZWQiOmZhbHNlLCJpbnN0YWdyYW1Ub2tlbiI6ZmFsc2UsImlzQXV0b1NlbnRpbWVudEVuYWJsZWQiOnRydWUsImluZmx1ZW5jZXJJbnNpZ2h0cyI6ZmFsc2V9XSwiY3JlYXRlZFRpbWUiOnsiZnJvbSI6IjIwMjAtMDctMjBUMDA6MDA6MDBaIiwidG8iOiIyMDIwLTA3LTIzVDIzOjU5OjU5WiJ9LCJzb3J0IjpbeyJ0eXBlIjoiY3JlYXRlZFRpbWUiLCJvcmRlciI6ImRlc2MifV19LCJjdXJzb3IiOnsic29ydCI6W3sidHlwZSI6ImNyZWF0ZWRUaW1lIiwidmFsdWUiOjE1OTU1MzA5MDMwMDAsIm9yZGVyIjoiZGVzYyJ9XSwibGFzdFNvcnRIYXNoIjoiKzkwMDU2MDM3MjM4Mzc5OTIiLCJpZHMiOlsiMTI4NjM3NTk2MDY4Njg3NDYzMCJdfSwidG90YWwiOjE2MCwic2Nyb2xsQ291bnQiOjEsInNjcm9sbGVkQ291bnQiOjV9",
    "remaining": 155
  }
}

Linkedin Profile Posts Metrics

Returns a set of posts created during the specified date range for each requested Linkedin profile. Linkedin posts endpoint returns lifetime values of the metrics.

Parameters

Name Description
profiles array, list of profile IDs of the profiles available from the /3/linkedin/profiles endpoint.
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. Your request is transformed using the time zone assigned to a profile in the Suite settings of your account. The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct timezone using the timezone of each individual profile from the /3/linkedin/profiles endpoint. The last day will be also included in the response.
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 results per page. The default value is 10 and the maximal value is 500.
after string, (optional). Pagination cursor. Points to the end of the page that has been returned.
sort You can sort the results by specifying a field and sorting order in the sort object: "field": "created_time" and "order": "desc". See the list of fields allowed for sorting.
Basic Fields
Name Type Example Description
attachments array 
[{ "title": "Struggling to find the content creation tools you need?", "description": "Check out our comprehensive list, and bookmark to keep these awesome tools right at your fingertips!", "url": "https://bit.ly/3bVufCv", "image_url": "https://external-sea1-1.xx.fbcdn.net/safe_image.php?d=AQD1V87mrnL6mHgJ&url=https%3A%2F%2Fsbks-builder.s3.amazonaws.com%2Fngysh9o0e9.jpg&_nc_hash=AQA1efZXH6wQ_JHo", "type":"link" }]
 Details about post attachments.
author object 
{ "id": "urn:li:organization:2056516", "name": "Socialbakers", "url": "https://linkedin.com/company/socialbakers-com" }
 Author details of the post.
comments integer 
5
 Total number of comments.
content string 
To #TikTok or not to TikTok, that is the question.
 Content of the LinkedIn post.
content_type string 
post
 Content type of the LinkedIn post.
created_time datetime 
2016-10-24T16:15:04+00:00
 Date and time the post was created in LinkedIn.
id string 
urn:li:share:6643188663637422080
 LinkedIn post id.
interactions integer 
20
 Sum of reactions, comments and shares.
interactions_per_1k_fans float 
0.37
 Interaction count for every 1000 fans.
media_type float 
link|photo|video|status
 Type of LinkedIn post.
page object 
{ "id": "urn:li:organization:2056516", "name": "Socialbakers", "url": "https://linkedin.com/company/socialbakers-com" }
 Information about the LinkedIn page.
post_labels array 
[{ "id": "2a8545bcc98b48d1a0c4", "name": "label A"}]
 Post labels assigned to the post.
reactions integer 
15
 Total number of reactions.
url string 
https://www.linkedin.com/feed/update/urn:li:share:6643188663637422080/
 Link to the LinkedIn post.

Fields that might be used to sort Linkedin posts:
Basic Fields
  • comments
  • created_time
  • interactions
  • interactions_per_1k_fans
  • reactions

Fields that might be used to filter Linkedin posts:
Basic Fields
  • media_type - ["status", "link", "video", "photo", "album", "carousel"]
  • post_labels - This field supports advanced post filters.

Example request

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

{
  "profiles": ["urn:li:organization:2056516"],
  "date_start": "2020-01-15",
  "date_end": "2020-01-17",
  "fields": ["content", "created_time"],
  "sort": [{
    "field": "created_time",
    "order": "asc"
  }],
  "limit": 5
}

Example response

{
      "success": true,
      "data": {
          "posts": [
              {
                  "content": "Today in our 🍕 lunch and learn 🧠session Mathias Durand gave our #Socialbakers team some tips on how they can strengthen their habits and willpower to accomplish their 2020 goals 🙌. \n\nThe secret? Creating small milestones and increasing the desired goal over time little by little 😉.  #InsideSocialbakers",
                  "created_time": "2020-01-15T15:04:55+00:00"
              },
              {
                  "content": "Get everything you need to start the New Year of with a BANG đŸ’„. ",
                  "created_time": "2020-01-15T18:00:01+00:00"
              },
              {
                  "content": "#SocialMedia đŸ’» and link building are often looked at separately from a business perspective. But the reality is, they actually go hand ✋ in hand ✋.\n\nđŸ“Č Learn how to refine your backlink strategy here: http://bit.ly/3a64VZy",
                  "created_time": "2020-01-16T13:00:09+00:00"
              },
              {
                  "content": "We had the pleasure of speaking with remarkable digital #marketers đŸ’» and CMOs about their ambitions đŸ’Ș for 2020. \n\nâŹ‡ïž Here's what they had to say... ",
                  "created_time": "2020-01-16T17:00:01+00:00"
              },
              {
                  "content": "Discover how Bath & Body Works 🛁experienced a massive increase in #socialmedia engagement and skyrocketed 🚀their sales revenue for two major annual campaigns!\n\nâžĄïžUnlock the full study here: http://bit.ly/370f1t6 \n\n#socialbakers #socialmediaengagement #marketing ",
                  "created_time": "2020-01-17T09:37:58+00:00"
              }
          ],
          "next": "eyJxdWVyeSI6eyJmZWVkVHlwZSI6InVzZXJGZWVkIiwiZmllbGRzIjpbIm1lc3NhZ2UiLCJjcmVhdGVkVGltZSIsIm9yaWdpbiIsImF1dGhvcklkIiwicHJvZmlsZUlkIiwibW9uaXRvcmVkUHJvZmlsZUlkIiwic3RvcmFnZVR5cGUiXSwiZmlsdGVycyI6W3sidHlwZSI6Im9yIiwiZmlsdGVycyI6W3sidHlwZSI6ImFuZCIsImZpbHRlcnMiOlt7InR5cGUiOiJjcmVhdGVkVGltZSIsInJhbmdlIjp7ImZyb20iOiIyMDIwLTAxLTE1VDAwOjAwOjAwWiIsInRvIjoiMjAyMC0wMS0xN1QyMzo1OTo1OVoifX0seyJ0eXBlIjoicHJvZmlsZUlkIiwicHJvZmlsZXMiOlt7InByb2ZpbGVJZCI6WyJ1cm46bGk6b3JnYW5pemF0aW9uOjIwNTY1MTYiXSwibmV0d29yayI6ImxpbmtlZGluIn1dfV19XX0seyJ0eXBlIjoibmV0d29yayIsInZhbHVlIjpbImZhY2Vib29rIiwidHdpdHRlciIsInBpbnRlcmVzdCIsImluc3RhZ3JhbSIsInlvdXR1YmUiLCJ2a29udGFrdGUiLCJsaW5rZWRpbiJdfV0sInNvcnQiOlt7InR5cGUiOiJjcmVhdGVkVGltZSIsIm9yZGVyIjoiYXNjIn1dLCJsaW1pdCI6NSwiYWNjb3VudElkIjoiMTcyMTk2IiwidXNlcklkIjoiZDE5NjEwODciLCJ0b2dnbGVzIjpbIkNPTU1VTklUWV9TRVRfRE9ORV9BRlRFUl9SRVBMWSIsIkFOQUxZVElDU19NT0RVTEUiLCJBVURJRU5DRVNfVEVBU0lORyIsIlBVQkxJU0hfTU9EVUxFIiwiVE9LRU5fRkxPVyIsIkFEU19CRU5DSE1BUktTIiwiTElOS0VESU5fQ09NTVVOSVRZIiwiQVVUT01BVEVEX1NFTlRJTUVOVF9BQ0NFUFRFRCIsIkFEX0FDQ09VTlRTX1JPTEVTX1BFUk1JU1NJT05TIiwiQVBQUk9WQUxfRkxPVyIsIkFVVE9MQUJFTElORyIsIkRBU0hCT0FSRF9PTU5JX1dJREdFVFMiLCJGSUxFU1RBQ0tfRlVMTCIsIklOU1RBR1JBTV9BRFNfUFVCX0NPTSIsIklOU1RBR1JBTV9WSURFT19QVUJMSVNISU5HIiwiTElOS0VESU5fUFVCTElTSElORyIsIk1PQklMRV9DT01NVU5JVFlfTU9EVUxFIiwiQ09OVEVOVF9IVUJfTU9EVUxFIiwiUlVMRV9CQVNFRF9MQUJFTElORyIsIkNPTlRFTlRfSFVCX0NPTExFQ1RJT05TIiwiUEFJRF9NT0RVTEUiLCJQVUJMSVNIRVJfRVhURVJOQUwiLCJUV19JTlNJR0hUUyIsIkNPTU1VTklUWV9NT0RVTEUiLCJBRFNfQkVOQ0hNQVJLU19GVUxMX0FDQ0VTUyIsIkJFTkNITUFSS1NfTVVMVElDT01QQVJFIiwiQ0FNUEFJR05fVklFVyIsIkNPTlRFTlRfU0VBUkNIX1BSTyIsIkRBU0hCT0FSRF9NT0RVTEUiLCJHT09HTEVfQU5BTFlUSUNTIiwiTElTVEVOSU5HIiwiTElWRV9WSURFT19NRVRSSUNTIiwiUEFJRF9QT1NUX0RFVEVDVElPTiIsIlBBSURfUE9TVF9ERVRFQ1RJT05fSUciLCJQT1NUX0JPT1NUSU5HIiwiUFJJTUVUSU1FIiwiVklERU9fQkVOQ0hNQVJLU19GVUxMX0FDQ0VTUyIsIkJVU0lORVNTX1RPR0dMRV9QVUJMSVNIRVJfSUdfVVNFUlNfVEFHR0lORyIsIklORkxVRU5DRVJTX01PRFVMRSIsIlBFUk1JU1NJT05TX0JZX1NFQ1RJT05TIiwiQlVTSU5FU1NfVE9HR0xFX1NUT1JJRVNfU0NIRURVTElORyIsIkJVU0lORVNTX1RPR0dMRV9BU1RVVEVfSU5URUdSQVRJT04iLCJCVVNJTkVTU19UT0dHTEVfTElOS0VESU5fVEFSR0VUSU5HIiwiQlVTSU5FU1NfVE9HR0xFX1BVQkxJU0hFUl9JR19MT0NBVElPTl9UQUdHSU5HIiwiQ09OVEVOVF9QUkVESUNUSU9OIiwiQ09OVEVOVF9QUkVESUNUSU9OX0lHIiwiUFVCTElTSEVSX0ZCX1NDSEVEVUxJTkciLCJCVVNJTkVTU19UT0dHTEVfUFVCTElDX0RBU0hCT0FSRCIsIkNPTlRFTlRfU0VOVElNRU5UIiwiQVVUT01BVEVEX1NFTlRJTUVOVCIsIkJVU0lORVNTX1RPR0dMRV9PUkdBTklDX0FOQUxZVElDUyIsIkJVU0lORVNTX1RPR0dMRV9MSVNURU5JTkdfTU9EVUxFIiwiQlVTSU5FU1NfVE9HR0xFX0lHX09SR0FOSUNfUEFJRF9SRU1PVkFMX0lOVEVSSU0iLCJCVVNJTkVTU19UT0dHTEVfSUdfT1JHQU5JQ19QQUlEX1JFTU9WQUxfRklOQUwiLCJCRVRBX01PQklMRV9DT01NVU5JVFlfTU9EVUxFIiwiQVVESUVOQ0VTX01PRFVMRSIsIkJVU0lORVNTX1RPR0dMRV9DT01NVU5JVFlfUkVQT1JUSU5HIiwiU1VJVEVfQURTIiwiQlVTSU5FU1NfVE9HR0xFX1BBSURfU1RPUkVEX0RBVEEiLCJCVVNJTkVTU19UT0dHTEVfUFJJT1JJVFlfU0NPUkUiLCJJTkZMVUVOQ0VSU19GVUxMX0FDQ0VTUyJdLCJwcm9maWxlcyI6W3sicHJvZmlsZUlkIjpbInVybjpsaTpvcmdhbml6YXRpb246MjA1NjUxNiJdLCJuZXR3b3JrIjoibGlua2VkaW4iLCJ0aW1lem9uZSI6IlVUQyIsImluc2lnaHRzIjpmYWxzZSwibWFuYWdlZCI6ZmFsc2UsImluc3RhZ3JhbVRva2VuIjpmYWxzZSwiaXNBdXRvU2VudGltZW50RW5hYmxlZCI6dHJ1ZSwiaW5mbHVlbmNlckluc2lnaHRzIjpmYWxzZX1dLCJjcmVhdGVkVGltZSI6eyJmcm9tIjoiMjAyMC0wMS0xNVQwMDowMDowMFoiLCJ0byI6IjIwMjAtMDEtMTdUMjM6NTk6NTlaIn19LCJjdXJzb3IiOnsic29ydCI6W3sidHlwZSI6ImNyZWF0ZWRUaW1lIiwidmFsdWUiOjE1NzkyNTM4NzgwMDAsIm9yZGVyIjoiYXNjIn1dLCJsYXN0U29ydEhhc2giOiItMDAwMTU3OTI1Mzg3ODAwMCIsImlkcyI6WyJ1cm46bGk6dWdjUG9zdDo2NjIzODcwODYwMjQ5ODMzNDcyIl19LCJ0b3RhbCI6OCwic2Nyb2xsQ291bnQiOjEsInNjcm9sbGVkQ291bnQiOjV9",
          "remaining": 3
      }
  }

Pinterest Profile Posts Metrics

Returns a set of posts created during the specified date range for each requested Pinterest profile. Pinterest posts endpoint returns lifetime values of the metrics.

Parameters

Name Description
profiles array, list of profile IDs of the profiles available from the /3/pinterest/profiles endpoint.
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. Your request is transformed using the time zone assigned to a profile in the Suite settings of your account. The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct timezone using the timezone of each individual profile from the /3/pinterest/profiles endpoint. The last day will be also included in the response.
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 results per page. The default value is 10 and the maximal value is 500.
after string, (optional). Pagination cursor. Points to the end of the page that has been returned.
sort You can sort the results by specifying a field and sorting order in the sort object: "field": "created_time" and "order": "desc". See the list of fields allowed for sorting.
Basic Fields
Name Type Example Description
attachments array 
[{ "image_url": "https://i.pinimg.com/600x/19/43/9d/19439d8e299609ebfe93e5b9e8cdf991.jpg", "type":"photo" }]
 Details about post attachments.
author object 
{ "id": "376684093741466051", "name": "Socialbakers", "url": "http://pinterest.com/socialbakers" }
 Author details of the post.
comments integer 
2
 Total number of comments.
content string 
#Video đŸ“č is still one of the most engaging content formats on #socialmedia.
 Content of the Pinterest post.
content_type string 
post
 Content type of the Pinterest post.
created_time datetime 
2020-06-18T10:11:50+00:00
 Date and time the post was created in Pinterest.
id string 
376684093741466051_376683956338863337
 Pinterest post id.
interactions integer 
4
 Sum of comments and shares.
interactions_per_1k_fans float 
0.01
 Interaction count for every 1000 fans.
media_type string 
photo
 Type of Pinterest post.
post_labels array 
[{ "id": "5ee90e5126a3494b81ff", "name": "454" }]
 Post labels assigned to the post.
profile object 
{ "id": "376684093741466051", "name": "Socialbakers", "url": "http://pinterest.com/socialbakers" }
 Information about the Pinterest profile.
shares integer 
2
 Number of times the post has been shared.
url string 
https://www.pinterest.com/pin/376683956338863337/
 Link to the Pinterest post.

Fields that might be used to sort Pinterest posts:
Basic Fields
  • comments
  • created_time
  • interactions
  • interactions_per_1k_fans
  • shares

Fields that might be used to filter Pinterest posts:
Basic Fields

Example request


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

{
  "profiles": ["376684093741466051"],
  "date_start": "2020-06-10",
  "date_end": "2020-07-18",
  "fields": ["attachments"],
  "sort": [{
    "field": "created_time",
    "order": "desc"
  }],
  "limit": 5
}

Example response


{
  "success": true,
  "data": {
    "posts": [
      {
        "attachments": [
          {
            "image_url": "https://i.pinimg.com/600x/ec/fc/14/ecfc14c0e0457290a52fbfe2b7260abd.jpg",
            "type": "photo"
          }
        ]
      },
      {
        "attachments": [
          {
            "image_url": "https://i.pinimg.com/600x/f9/22/92/f92292a71c310e234367f561ce177284.jpg",
            "type": "photo"
          }
        ]
      },
      {
        "attachments": [
          {
            "image_url": "https://i.pinimg.com/600x/96/90/d8/9690d8a4a5495181870ce7fc58d9508e.jpg",
            "type": "photo"
          }
        ]
      },
      {
        "attachments": [
          {
            "image_url": "https://i.pinimg.com/600x/85/18/a1/8518a1670f67c82d87f65ae58a45c1b1.jpg",
            "type": "photo"
          }
        ]
      },
      {
        "attachments": [
          {
            "image_url": "https://i.pinimg.com/600x/43/16/cb/4316cba530e935255d99f41247c1c7b9.jpg",
            "type": "photo"
          }
        ]
      }
    ],
    "next": "eyJxdWVyeSI6eyJmZWVkVHlwZSI6InVzZXJGZWVkIiwiZmllbGRzIjpbImF0dGFjaG1lbnRzIiwib3JpZ2luIiwiYXV0aG9ySWQiLCJwcm9maWxlSWQiLCJtb25pdG9yZWRQcm9maWxlSWQiLCJzdG9yYWdlVHlwZSJdLCJmaWx0ZXJzIjpbeyJ0eXBlIjoib3IiLCJmaWx0ZXJzIjpbeyJ0eXBlIjoiYW5kIiwiZmlsdGVycyI6W3sidHlwZSI6ImNyZWF0ZWRUaW1lIiwicmFuZ2UiOnsiZnJvbSI6IjIwMjAtMDYtMTBUMDA6MDA6MDBaIiwidG8iOiIyMDIwLTA3LTE4VDIzOjU5OjU5WiJ9fSx7InR5cGUiOiJwcm9maWxlSWQiLCJwcm9maWxlcyI6W3sicHJvZmlsZUlkIjpbIjM3NjY4NDA5Mzc0MTQ2NjA1MSJdLCJuZXR3b3JrIjoicGludGVyZXN0In1dfV19XX0seyJ0eXBlIjoibmV0d29yayIsInZhbHVlIjpbImZhY2Vib29rIiwidHdpdHRlciIsInBpbnRlcmVzdCIsImluc3RhZ3JhbSIsInlvdXR1YmUiLCJ2a29udGFrdGUiLCJsaW5rZWRpbiJdfV0sImxpbWl0Ijo1LCJhY2NvdW50SWQiOiIxNzIxOTYiLCJ1c2VySWQiOiJkMTk2MTA4NyIsInRvZ2dsZXMiOlsiQ09NTVVOSVRZX1NFVF9ET05FX0FGVEVSX1JFUExZIiwiQ09OVEVOVF9TRU5USU1FTlQiLCJBTkFMWVRJQ1NfTU9EVUxFIiwiQVVESUVOQ0VTX1RFQVNJTkciLCJQVUJMSVNIX01PRFVMRSIsIlRPS0VOX0ZMT1ciLCJBRFNfQkVOQ0hNQVJLUyIsIkxJTktFRElOX0NPTU1VTklUWSIsIkFVVE9NQVRFRF9TRU5USU1FTlRfQUNDRVBURUQiLCJBVVRPTUFURURfU0VOVElNRU5UIiwiQURfQUNDT1VOVFNfUk9MRVNfUEVSTUlTU0lPTlMiLCJBUFBST1ZBTF9GTE9XIiwiQVVUT0xBQkVMSU5HIiwiREFTSEJPQVJEX09NTklfV0lER0VUUyIsIkZJTEVTVEFDS19GVUxMIiwiSU5TVEFHUkFNX0FEU19QVUJfQ09NIiwiSU5TVEFHUkFNX1ZJREVPX1BVQkxJU0hJTkciLCJMSU5LRURJTl9QVUJMSVNISU5HIiwiTU9CSUxFX0NPTU1VTklUWV9NT0RVTEUiLCJDT05URU5UX0hVQl9NT0RVTEUiLCJSVUxFX0JBU0VEX0xBQkVMSU5HIiwiQ09OVEVOVF9IVUJfQ09MTEVDVElPTlMiLCJQQUlEX01PRFVMRSIsIlBVQkxJU0hFUl9FWFRFUk5BTCIsIlRXX0lOU0lHSFRTIiwiQ09NTVVOSVRZX01PRFVMRSIsIkFEU19CRU5DSE1BUktTX0ZVTExfQUNDRVNTIiwiQkVOQ0hNQVJLU19NVUxUSUNPTVBBUkUiLCJDQU1QQUlHTl9WSUVXIiwiQ09OVEVOVF9TRUFSQ0hfUFJPIiwiREFTSEJPQVJEX01PRFVMRSIsIkdPT0dMRV9BTkFMWVRJQ1MiLCJMSVNURU5JTkciLCJMSVZFX1ZJREVPX01FVFJJQ1MiLCJQQUlEX1BPU1RfREVURUNUSU9OIiwiUEFJRF9QT1NUX0RFVEVDVElPTl9JRyIsIlBPU1RfQk9PU1RJTkciLCJQUklNRVRJTUUiLCJWSURFT19CRU5DSE1BUktTX0ZVTExfQUNDRVNTIiwiQlVTSU5FU1NfVE9HR0xFX1BVQkxJU0hFUl9JR19VU0VSU19UQUdHSU5HIiwiSU5GTFVFTkNFUlNfTU9EVUxFIiwiUEVSTUlTU0lPTlNfQllfU0VDVElPTlMiLCJCVVNJTkVTU19UT0dHTEVfU1RPUklFU19TQ0hFRFVMSU5HIiwiQlVTSU5FU1NfVE9HR0xFX0FTVFVURV9JTlRFR1JBVElPTiIsIkJVU0lORVNTX1RPR0dMRV9MSU5LRURJTl9UQVJHRVRJTkciLCJCVVNJTkVTU19UT0dHTEVfUFVCTElTSEVSX0lHX0xPQ0FUSU9OX1RBR0dJTkciLCJDT05URU5UX1BSRURJQ1RJT04iLCJDT05URU5UX1BSRURJQ1RJT05fSUciLCJQVUJMSVNIRVJfRkJfU0NIRURVTElORyIsIkJVU0lORVNTX1RPR0dMRV9JR19PUkdBTklDX1BBSURfUkVNT1ZBTF9JTlRFUklNIiwiQlVTSU5FU1NfVE9HR0xFX0lHX09SR0FOSUNfUEFJRF9SRU1PVkFMX0ZJTkFMIiwiQkVUQV9NT0JJTEVfQ09NTVVOSVRZX01PRFVMRSIsIkFVRElFTkNFU19NT0RVTEUiLCJCVVNJTkVTU19UT0dHTEVfQ09NTVVOSVRZX1JFUE9SVElORyIsIlNVSVRFX0FEUyIsIkJVU0lORVNTX1RPR0dMRV9QQUlEX1NUT1JFRF9EQVRBIiwiQlVTSU5FU1NfVE9HR0xFX1BSSU9SSVRZX1NDT1JFIiwiSU5GTFVFTkNFUlNfRlVMTF9BQ0NFU1MiXSwicHJvZmlsZXMiOlt7InByb2ZpbGVJZCI6WyIzNzY2ODQwOTM3NDE0NjYwNTEiXSwibmV0d29yayI6InBpbnRlcmVzdCIsInRpbWV6b25lIjoiVVRDIiwiaW5zaWdodHMiOmZhbHNlLCJtYW5hZ2VkIjpmYWxzZSwiaW5zdGFncmFtVG9rZW4iOmZhbHNlLCJpc0F1dG9TZW50aW1lbnRFbmFibGVkIjp0cnVlLCJpbmZsdWVuY2VySW5zaWdodHMiOmZhbHNlfV0sImNyZWF0ZWRUaW1lIjp7ImZyb20iOiIyMDIwLTA2LTEwVDAwOjAwOjAwWiIsInRvIjoiMjAyMC0wNy0xOFQyMzo1OTo1OVoifSwic29ydCI6W3sidHlwZSI6ImNyZWF0ZWRUaW1lIiwib3JkZXIiOiJkZXNjIn1dfSwiY3Vyc29yIjp7InNvcnQiOlt7InR5cGUiOiJjcmVhdGVkVGltZSIsInZhbHVlIjoxNTkyMTI5NDc3MDAwLCJvcmRlciI6ImRlc2MifV0sImxhc3RTb3J0SGFzaCI6Iis5MDA1NjA3MTI1MjYzOTkyIiwiaWRzIjpbIjM3NjY4NDA5Mzc0MTQ2NjA1MV8zNzY2ODM5NTYzMzg4MTM5MzUiXX0sInRvdGFsIjo4LCJzY3JvbGxDb3VudCI6MSwic2Nyb2xsZWRDb3VudCI6NX0=",
    "remaining": 3
  }
}

Vkontakte Profile Posts Metrics

Returns a set of posts created during the specified date range for each requested Vkontakte profile. Vkontakte posts endpoint returns lifetime values of the metrics.

Parameters

Name Description
profiles array, list of profile IDs of the profiles available from the /3/vkontakte/profiles endpoint.
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. Your request is transformed using the time zone assigned to a profile in the Suite settings of your account. The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct timezone using the timezone of each individual profile from the /3/vkontakte/profiles endpoint. The last day will be also included in the response.
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 results per page. The default value is 10 and the maximal value is 500.
after string, (optional). Pagination cursor. Points to the end of the page that has been returned.
sort You can sort the results by specifying a field and sorting order in the sort object: "field": "created_time" and "order": "desc". See the list of fields allowed for sorting.
filter You can filter results by providing the filter parameter with field and value. See the list of fields allowed for filtering.
Basic Fields
Name Type Example Description
attachments array 
[{ "image_url": "https://i.pinimg.com/600x/19/43/9d/19439d8e299609ebfe93e5b9e8cdf991.jpg", "type":"photo" }]
 Details about post attachments.
author object 
{ "id": "2869454533", "name": "Socialbakers", "url": "http://vk.com/socialbakers" }
 Author details of the post.
comments integer 
15
 Total number of comments.
content string 
Today is #InternationalBeerDayđŸ»
 Content of the VKontakte post.
content_type string 
post
 Content type of the VKontakte post.
created_time datetime 
2016-10-24T16:15:04+00:00
 Date and time the post was created in VKontakte.
id string 
17966172199068623_490402220
 VKontakte post id.
interactions integer 
25
 Sum of reactions, comments and shares.
interactions_per_1k_fans float 
0.8
 Interaction count for every 1000 fans.
likes integer 
8
 Total number of likes.
media_type string 
status|link|video|poll|animated_gif|album|photo
 Type of VKontakte post.
origin string 
User-Generated Content|Brand's Content
 Source of post.
page object 
{ "id": "2869454533", "name": "Socialbakers", "url": "http://vk.com/socialbakers" }
 Information about the VKontakte page.
post_labels array 
[{ "id": "2a8545bcc98b48d1a0c4", "name": "label A"}]
 Post labels assigned to the post.
shares integer 
15
 Number of times the post has been shared.
url string 
https://www.vk.com/wall-3335458_6524564
 Link to the VKontakte post.

Fields that might be used to sort Vkontakte posts:
Basic Fields
  • comments
  • created_time
  • interactions
  • interactions_per_1k_fans
  • likes
  • shares

Fields that might be used to filter Vkontakte posts:
Basic Fields
  • media_type - ["status", "photo", "video", "link", "note", "poll", "album"]
  • origin - ["User-Generated Content", "Brand's Content"]
  • post_labels - This field supports advanced post filters.

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 /3/vkontakte/profile/posts HTTPS
Host: api.socialbakers.com
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "profiles": ["490402220", "55674325"],
  "date_start": "2018-06-01",
  "date_end": "2018-08-31",
  "fields": [
    "id",
    "created_time",
    "attachments"
  ],
  "sort": [{
    "field": "created_time",
    "order": "desc"
  }],
  "limit": 5
}

Example response

{
  "success": true,
  "data": {
    "posts": [
        {
          "id": "48771076_2874",
          "created_time": "2020-07-30T08:09:00+00:00",
          "attachments": [
              {
                  "image_url": "https://sun9-60.userapi.com/c858520/v858520187/1e966b/0dkw0112z.jpg"
              },
              {
                  "description": "Description of the post."
              }
          ]
      }
    ],
    "next": "eyJjdXJzb3IiOlt7ImZpZWxkIjoiY3JlYXRlZF90aW1lIiwidmFsdWUiOiIyMDE4LTA2LTI4VDEyOjM4OjM0KzAwOjAwIiwib3JkZXIiOiJkZXNjIn1dLCJpZHMiOlsiMTc4OTM5NTExNjIyMTY0NjRfNDkwNDAyMjIwIl19=",
    "remaining": 15
  }
}

Aggregated Post Metrics

Aggregated Post metrics display lifetime data from individual posts published during the selected time period of your analysis. All post data is aggregated and displayed for the day the post was published, regardless of when the engagement happened. Spam and deleted posts are removed from results.

Parameters

Name Description
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. The response uses a timezone assigned to a profile in Suite settings of the account. The last day will be also included in the response.
profiles array of objects, consists of profile IDs and platforms. You can get the profiles from the List of Connected Profiles section.
metric string, the list of available metrics is displayed below.
dimensions array of objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimensions in the table of metrics below. Dimensions marked with an asterisk* must be last, and only one such dimension can be used. A maximum of 2 dimensions can be used.
filter array of objects. You can filter the results using simple or advanced post filters. See the list of fields allowed for filtering.

Metrics

Metrics prefixed with insights_ can only be used for profiles from platforms that have insights enabled. Not all metrics are available for all platforms.

Aggregation is the type of calculation used for grouping values of a specific metric.

Name Dimensions Metrics Description
engagement_rate
FBIGTWYTLIVK
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type
published_status
sentiment_type		 avg Engagement Rate for a particular post displays the average number of Interactions per Fan. Engagement Rate is therefore calculated by dividing the number of Interactions of a post by the number of Fans on that day. No data available for FB pages that is part of the Global Page Structure and does not have insights connected.
insights_completion_rate
IGStories
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
media_type		 avg The percentage of times a story impression was not interrupted by an exit, tap back, or tap forward.
insights_engagements
FBIGTW
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
media_type
content_type		 sum Total number of posts engagement which includes likes, shares and comments.
insights_impressions
FBIGTW
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type
published_status
sentiment_type		 sum Number of impressions for your posts.
insights_media_views
TW
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
media_type
content_type
sentiment_type		 sum All views(autoplay and clicks) of the media which includes videos, gifs and images.
insights_post_clicks
FB
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type
published_status		 sum The number of times people clicked on anywhere in your posts without generating an activity.
insights_reach_engagement
FB
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type
published_status		 avg Number of people who engaged with your Post per Number of people who have seen any content associated with your Post. Engagement includes any click or activity created.
insights_reach_per_content
FBIG
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type
published_status
sentiment_type		 avg Number of people who have seen any content associated with your Page. (Unique Users)
insights_story_exits
IGStories
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
media_type		 sum The number of times users exited your story.
insights_story_taps_back
IGStories
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
media_type		 sum The number of times users clicked back to return to the previous story.
insights_story_taps_forward
IGStories
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
media_type		 sum The number of times users clicked forward to skip to the next story.
insights_video_views
FBIGTWYT
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
published_status
sentiment_type		 sum Number of times page's videos have been viewed for more than 3 seconds.
interactions
FBIGTWYTLIPIVK
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type
published_status
interaction_type
sentiment_type		 sum Number of interactions on page posts.
interactions_per_1k_fans
FBIGTWYTLIVK
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type
published_status
sentiment_type		 sum Number of interactions on page posts per 1k fans. No data available for FB pages that is part of the Global Page Structure and does not have insights connected.
likes
FBIGTWYT
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
media_type
sentiment_type		 sum Number of likes of profile posts.
number_of_comments
FBIGTWYTLIPIVK
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type
published_status
sentiment_type		 sum Number of comments on page posts.
page_posts
FBIGTWYTLIPIVK
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type
published_status
sentiment_type		 sum Number of page posts.
page_replies
TW
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label		 sum Number of replies by the Twitter profile.
page_shares
FBTWPI
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label		 sum Number of retweets or shares by the page/profile
profile_tweets
TW
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
media_type		 sum Total number of tweets, excluding replies and retweets.
sentiment_manual_auto
FBIGTW
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
media_type
sentiment*		 sum The breakdown of sentiment – Positive, Negative, or Neutral – for all comments. This metric needs to be used with the sentiment dimension.
shares
FBTWPIVK
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type
published_status		 sum Number of interactions on page posts, filtered by content type shared.
user_posts
FBTW
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type		 sum Number of page posts, filtered by origin incoming.
user_posts_average_response_time
FBTW
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type		 avg Average response time of page posts, filtered by origin incoming
user_posts_responded
FBTW
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type
response_time		 sum Number of non-admin page posts that have been responed, filtered by origin incoming.
user_posts_response_rate
FBTW
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type		 avg Ratio of responded user posts to number of user posts
user_questions
FBTWVK
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type		 sum Number of page posts which are questions.
user_questions_average_response_time
FBTW
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type		 avg Average response time of page posts which are questions, filtered by origin incoming
user_questions_responded
FBTW
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type
response_time		 sum Number of non-admin page posts which are questions that have been responded.
user_questions_response_rate
FBTW
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type		 avg Ratio of responded user questions to user questions.
Fields that might be used to filter posts:
Basic Fields

Example request


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

{
  "profiles": [
    {
      "id": "564919357",
      "platform": "twitter",
    },
    {
      "id": "164929129743",
      "platform": "facebook"
    }
  ],
  "date_start": "2018-11-01",
  "date_end": "2018-11-12",
  "metric": "page_posts",
  "dimensions": [
    {
      "type": "profile"
    }
  ],
  "filter": [
    {
      "field": "post_labels",
      "value": [
        "e3af7de2d2274393b86b"
      ]
    }
  ]
}

Example response


{
  "success": true,
  "header": [
    {
      "type": "profile",
      "rows": [
        {
          "id": "564919357",
          "platform": "twitter",
        },
        {
          "id": "164929129743",
          "platform": "facebook"
        }
      ]
    },
    {
      "type": "metric",
      "rows": [
        "page_posts"
      ]
    }
  ],
  "data": [
    [
      3
    ],
    [
      6
    ]
  ]
}

Advanced Post Filters

Introduction

Some fields support advanced possibilities of filtering. It is possible to create filter rules as a combination of match_all and match_any clauses. A combination with simple filter definition is also possible. The filter consists of two types of clauses:

Simple filter clauses

Specifies particular field(s) and its values. Posts having these values will be part of the results. 

    
    {
      "field": "type",
      "value": [
        "photo",
        "status"
      ]
    }
Advanced filter clauses

The advanced filter is used to combine multiple filters in a logical meaning as AND, and OR.

  • match_all - Represents logical AND. Items have to match in all criteria for each clause
  • match_any - Represents logical OR. The result of this filter has to match at least in one criterion of the clause.
    
    {
      "match_all": [
        {
          "field": "post_labels",
          "value": [
            "fa14dde7e4f041e3a646",
            "890c135d9cee4cf89b42"
          ]
        }
      ]
    }

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 /3/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",
    ],
    "labels": ["my label"],
}

Example response

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

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

Google Data Studio Connector

Introduction

Google Data Studio is an analytics dashboard report service which turns your analytics data into informative reports which are easy to read, share and customizable.

Official Google Data Studio Connector description: https://support.google.com/datastudio/answer/6268208.

The connector allows you to access Socialbakers API and use it as a source of data for your reports.

To access the connector, please visit this address: Socialbakers GDS Connector

For authorization, you’ll need to input a User name and Token. These are linked to a specific user of a Socialbakers Suite account. Get in touch with our Support team at support@socialbakers.com to get yours.

(Please note that name convention slightly differs on Socialbakers’ side where ‘Token’ and ‘Secret’ is being used.
EXAMPLE of what you’ll use for input:
User Name: (called token on Socialbakers side)
NjE5MTA4XzE3OTAyMTVfMTU0NTMxNDUyOTA4OV82MTRlODkxODAzNDI0ZmU5MTQwY2VkZTY4NzI2NmI1OA== (example only, not functional)
Token: (called secret on Socialbakers side)
f0e2b4ca2fd76b8515265fd6b8bced5d (example only, not functional)

More info about authorization: Security and authentication

Available metrics

Network Metrics
Facebook Metrics all metrics
Instagram Metrics all metrics
Twitter Metrics all metrics
YouTube Metrics all metrics
Pinterest Metrics all metrics

Changelog

v3.1

  • Removed name and url from the profile field in Twitter Post Metrics
  • Removed created time from Twitter Post Metrics as it is against the Twitter Developer Policy

v3.0

  • Post labels and Profile labels endpoints are now GET method instead of POST
  • Added new metrics and properties for Post Metrics
  • Added LinkedIn, Pinterest and VKontakte support for Post Metrics
  • Aggregated Post Metrics now filters out spam and deleted posts

v2.0

  • Added get connected profiles support for LinkedIn and Vkontakte.
  • Introduced new Profile level metrics with dimension support.
  • Added Profile level metrics for LinkedIn.
  • Facebook Post Metrics endpoint within the Aggregated Post Metric is removed.

v1.2

  • Introduced new Aggregated Post Metrics endpoint under the Aggregated Post Metrics section. This adds support to aggregate data across multiple social networks.
  • Introduced post level aggregated data for IG Story specific metrics.

v1.1

  • IG carousel typed posts now returns all image links (bugfix).

v1.0

2020/03/04

  • Fix community add and delete labels

2020/01/13

  • Add profile-level engagement_rate.

2020/01/08

  • Add post-level engagement_rate. Multiplication by 10 is needed for all values except for the FB one, as we already receive it multiplied by 10

2019/07/11

2019/06/22

2018/12/17

  • new endpoint /1/metrics to get aggregated data of a set of posts defined by profiles and filtering parameters
  • /1/facebook/page/posts now returns also unpublished posts.
  • new sort fields to sort Facebook posts by insights_impressions, insights_impressions_paid, insights_impressions_organic
  • new field url added to Instagram posts

2018/11/04

v0.9

2019/06/22

2018/12/17

  • new sort fields to sort Facebook posts by insights_impressions, insights_impressions_paid, insights_impressions_organic
  • new field url added to Instagram posts

2018/11/04

  • the timezone is (internally) applied to correspond with Suite data when using post level endpoints

2018/10/17

2018/09/10

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
Terms & Conditions Privacy policy