This document refers to an outdated version of Emplifi API. Please use the latest version.

Emplifi API Documentation

Introduction

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

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

Security and Authentication

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

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

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

Example request

GET /1/facebook/profiles HTTPS
Host: api.emplifi.io
Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l
Content-Type: application/json; charset=utf-8

Using OAuth 2.0 to access Emplifi API

Emplifi API uses the OAuth 2.0 framework to authorize users to make API request. Emplifi API supports the Oauth 2.0 Authorization code flow.

Before you begin create a new Custom integration in the Emplifi Settings.

OAuth2 endpoints are located at https://api.emplifi.io/oauth2/0/.

The OAuth2 configuration is available at https://api.emplifi.io/oauth2/0/.well-known/openid-configuration.

How to get access to OAuth 2.0

OAuth 2.0 access has to be enabled by our support team, even if you have Emplifi API Integration purchased. Please send oAuth activation request to support@emplifi.io

OAuth2.0 Authorization code flow

Steps to get API access

  1. Obtain credential from Emplifi OAuth app settings
  2. Getting an authorization code
  3. Exchange authorization code for access token
  4. Using an access token
  5. Access token refreshing
  6. Access token revoking

Getting the access_token

First visit the Emplifi Custom integrations to obtain the client ID and client secret that are known to both Emplifi and your application. These credential will be used in following steps to communicate with the Emplifi API.

Obtain user approval and authorization code

First step in retrieving an access token is to get an approval from a user of Emplifi platform. To get this approval you must redirect the user to a consent page on Emplifi.

The URL to the consent page is: https://api.emplifi.io/oauth2/0/auth and it accepts following parameters:

Parameter Description
client_id The client ID for your application. You can find it in in the Custom integrations section.
redirect_uri URI to handle successful user authorization handled by your application. Must match with Redirect URI specified in the integration's settings.
response_type Emplifi API only supports code.
scope

A space-delimited list of scopes that identify the resources that your application could access on the user's behalf. These will be presented for approval to the user. If your application would like to refresh access token without user's interaction the scope has to include offline_access value, e.g. api.read offline_access.

Scopes requirements of each endpoint are shown in its documentation.

state An opaque value that you can use to maintain state between the your authorization request and the authorization server's response. The authorization server includes this value when redirecting the user-agent back to your app. Your application should compare the locally stored state with the one sent back from the Emplifi API to prevent CSRF attacks.
prompt Must be set to consent if the refresh token should be issued together with access token.

When the user approves the request, the Emplifi API will redirect the user back to the redirect_uri with an authorization code in the query string as "code".

Exchange authorization code for access token

Once you received authorization code from the previous step you can exchange it for access token and optionally refresh token. To do so, you have to make POST request to the https://api.emplifi.io/oauth2/0/token endpoint of the OAuth2 authorization server with the following Request Headers and Request Body information:

Request Header
Header Value
Authorization Basic authentication where username is the Client ID and password the Client Secret. The string "Basic" with your Client ID and Client Secret separated with colon (:), Base64-encoded. For example, client_id:client_secret The final value is Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=.
Content-Type application/x-www-form-urlencoded
Request Body
Parameter Value
code The authorization code supplied to the callback URI from previous step.
grant_type authorization_code
redirect_uri Your application redirect URI. Has to be same URI as specified in authorization code request. In our example https://my-example-app.com/auth/callback.
Response
Parameter Value
access_token Access token to be used for accessing the Emplifi API.
token_type Only supported type is bearer
expires_in Access token expiration time in seconds.
refresh_token Refresh token to be used for refreshing the access token. Only present when scope contains offline_access.
scope Scopes that were granted by the user. Space delimited string. e.g. api.read offline_access

Request URL to obtain the authorization code

https://api.emplifi.io/oauth2/0/auth?response_type=code&client_id={CLIENT_ID}&state=ed56BgdY64aswDC&redirect_uri=https%3A%2F%2Fmy-example-app.com%2Fauth%2Fcallback&scope=api.read%20offline_access&prompt=consent

The URL user is sent to after they approve the request

https://my-example-app.com/auth/callback?code=derfDST4r5sGNY_425sDW3wf&state=ed56BgdY64aswDC&iss=https://3348d0628f75ab43fe445e17eb650c1b.sbksapps.com

Request to exchange authorization code for access token

curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic Y1xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
-d "grant_type=authorization_code&code=derfDST4r5sGNY_425sDW3wf&redirect_uri=https://my-example-app.com/auth/callback"
https://api.emplifi.io/oauth2/0/token

Example response with the access_token and refresh_token

{
  "access_token": "Imu6FyXyiATtf529qX5QsbZeamylWlg5wM50KingLoM",
  "token_type": "bearer",
  "refresh_token": "C8DEVlA-RuOlRhKiyvvWLQlc0cNZ2wk1K5uySKey7Yw",
  "expires_in": 7200,
  "scope": "api.read offline_access"
}

Full example using passport and passport-oauth2 NPM packages to get an access_token (Javascript)

const passport = require('passport')
const OAuth2Strategy = require('passport-oauth2')
const express = require('express')
const session = require('express-session')
const fetch = require('node-fetch')

const app = express()
app.use(
  session({
    secret: 'example_app_session_secret',
    resave: false,
    saveUninitialized: true,
  })
)
const EmplifiStrategy = new OAuth2Strategy(
  {
    authorizationURL: 'https://api.emplifi.io/oauth2/0/auth',
    tokenURL: 'https://api.emplifi.io/oauth2/0/token',
    clientID: 'CLIENT_ID',
    clientSecret:
      'CLIENT_SECRET',
    callbackURL: 'http://localhost:3000/auth/example/callback',
  },
  async function verify(accessToken, refreshToken, profile, next) {
    const userInfoResponse = await fetch('https://api.emplifi.io/1/user/me', {
      headers: {
        Authorization: `Bearer ${accessToken}`,
      },
    })
    if (userInfoResponse.status !== 200) {
      const { statusText, status } = userInfoResponse
      next(
        new Error(`Failed to fetch user information ${status} - ${statusText}`)
      )
    }
    const userInfo = await userInfoResponse.json()
    // find the user in your application based on the received data and pass it to the next
    next(null, { accessToken, refreshToken, user: userInfo.userInfo })
  }
)
// when offline_access scope is requested, the prompt parameter is required to be set to consent
EmplifiStrategy.authorizationParams = function (options) {
  return {
    ...options,
    prompt: 'consent',
  }
}
app.use(passport.session())
app.use(passport.initialize())
passport.use('emplifi', EmplifiStrategy)
passport.serializeUser((user, next) => next(null, user))
passport.deserializeUser((id, next) => next(null, id))

app.get(
  '/auth/example',
  passport.authenticate('emplifi', {
    // offline_access is necessary to receive refresh_token. Required scopes are listed in the Emplifi API documentation
    scope: ['api.read', 'offline_access'],
  })
)

app.get(
  '/auth/example/callback',
  passport.authenticate('emplifi', { failureRedirect: '/failed' }),
  function (req, res) {
    // Successful authentication, redirect home.
    res.redirect('/')
  }
)

app.get('/failed', (req, res) => {
  res.send('Failed to authenticate')
})

app.get('/', (req, res) => {
  if (req.user) {
    res.send(req.user)
  } else {
    res.send("<a href='/auth/example'>Login</a>")
  }
})

app.listen(3000, () => {
  console.log('Server is running on port 3000')
})

Using the access token

Send request to Emplifi API with access_token in HTTP authorization header. "Authorization": "Bearer <ACCESS_TOKEN>"

The access token is valid for 30 days.

cURL request example

curl -X GET \
-H "Authorization: Bearer Imu6FyXyiATtf519qX5QsbZeamylWlg5wM50KingLoM" \
-H "Content-Type: application/json; charset=utf-8" \
https://api.emplifi.io/1/facebook/profiles

Access token refreshing

The access token live time is limited. Refer to expires_in property of the exchange authorization code to access token. Once access token expires, you will have to refresh it by using refresh token. The refresh token is returned by https://api.emplifi.io/oauth2/0/token endpoint if the scope property of the /auth endpoint contains offline_access.

To refresh access token make POST request to /token endpoint with following Request header and Request body.

Request Header
Header Value
Authorization Basic authentication where username is the Client ID and password the Client Secret.
The string "Basic" with your Client ID and Client Secret separated with colon (:), Base64-encoded. For example, client_id:client_secret The final value is Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=.
Content-Type application/x-www-form-urlencoded
Request Body
Parameter Value
refresh_token The refresh token obtained when asking for access token in step 3. In our example C8DEVlA-RuOlRhKiyvvWLQlc0cNZ1wk1K5uySKey7Yw
grant_type refresh_token

Refresh token expires in 180 days.

cURL request example

curl -X POST \
-H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token&refresh_token=C8DEVlA-RuOlRhKiyvvWLQlc0cNZ1wk1K5uySKey7Yw" \
https://api.emplifi.io/oauth2/0/token

Example response

{
  "access_token": "JWefwbpGr3PJyBJjGP3DMaLe5ooX75StcfEb7bgaosn",
  "expires_in": 7200,
  "refresh_token": "C8DEVlA-RuOlRhKiyvvWLQlc0cNZ1wk1K5uySKey7Yw",
  "scope": "api offline_access",
  "token_type": "Bearer"
}

Access token revoking

To revoke access token, make a POST request to https://api.emplifi.io/oauth2/0/token/revocation endpoint with following request headers and request body.

Request Header
Header Value
Authorization Basic authentication where username is the Client ID and password the Client Secret.
The string "Basic" with your Client ID and Client Secret separated with colon (:), Base64-encoded. For example, client_id:client_secret The final value is Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=.
Content-Type application/x-www-form-urlencoded
Request Body
Parameter Value
token The access token to be revoked. In our example JWefwbpGr3PJyBJjGP3DMaLe5ooX75StcfEb7bgaosn

The OAuth2 provider will always response with HTTP status 200.

cURL request example

curl -X POST \
 -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d "token=JWefwbpGr3PJyBJjGP3DMaLe5ooX75StcfEb7bgaosn" \
 https://api.emplifi.io/oauth2/0/token/revocation

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

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

Sometimes, your request may return Complexity error (code:4) even if you did not reach any of the limits. This is because the amount of data to return is too large. Try to split your request into multiple smaller ones.

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

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

Rate limit headers with Oauth 2.0 Authorization

When using Oauth 2.0 Authorization, each request to the API will additionally return the following headers to let you know the current state of your quota usage:

HTTP/1.1 200 OK
X-RateLimit-Limit: 500, 500;window=3600, 1000;window=3600
X-RateLimit-Remaining: 20
X-RateLimit-Reset: 1201

The X-RateLimit-Limit header contains the maximum number of requests you are permitted to make. There can be multiple entries separated by comma followed by space () in the header.

  • The entry is always a number and contains the lowest number of requests you can make for this resource in the current window.
  • Starting with the second entry each entry corresponds to a limit that affects this resource. It is always in format number_of_requests;window=size_of_the_window_in_seconds. e.g. 500;window=3600 means 500 requests can be made every hour (3600 seconds)

The X-RateLimit-Remaining header tells you how many requests you have left to use in the current window.

The X-RateLimit-Reset header tells you how many seconds until the current window resets.

The example above shows that the current window resets in 1201 seconds and you can make 20 more requests until then. It also shows that the called endpoint is subject to 2 different limits: one with 500 calls every 3600 seconds and one with 1000 calls every 3600 seconds. It also shows that the closest limit to be hit is the one with 500 calls per 3600 seconds.

Requests failing with status code 429 Too Many Requests

When the number of allowed requests gets exceeded the response will contain additional header Retry-After with the number of seconds until the current window resets.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 500, 500;window=3600, 1000;window=3600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 800
Retry-After: 800

Errors

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

Error codes

Code Endpoint Description HTTP Status Code
3 all Input validation error 200
4 all Profiles, metrics or date range limit exceeded 200
5 all Profiles not allowed for user 200
6 all Start date is before history limit date 200
7 POST /1/facebook/metrics
POST /1/instagram/metrics
POST /1/facebook/page/posts
POST /1/instagram/profile/posts
POST /1/metrics
Profiles do not have insights enabled 200
8 all Labels used for filtering do not exists 200
10 all Account request limit exceeded 200
11 all User request limit exceeded 200
13 all Labeled content or conversation does not exist in Community. 200
99 all An unknown error occurred 200
400 all Bad request 400
401 all Missing authorization header, invalid secret or token 401
403 all Action is not permitted 403
404 all Resource not allowed 404
405 all HTTP method not allowed 405
500 all Internal server error 500
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

Required OAuth2 scope: 
api.read

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

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 Emplifi 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.
community_enabled boolean, true if community content is available for profile.

Example request

              GET /1/{network}/profiles HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
Supported values for {network}: facebook, instagram, twitter, youtube, pinterest
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",
      "community_enabled": true
    },
    ...
  ]
}

List of Content Labels

Required OAuth2 scope: 
api.read

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

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

Response fields

Name Description
id string, content label unique identifier
name string, content label name

Example request

              POST /1/post/labels HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
Example response
{
  "success": true,
  "data": [
    {
      "id": "5d879004a44a4cbcb13e",
      "name": "Content Label 1"
    },
    {
      "id": "ffc196eb056b42fd9b03",
      "name": "Content Label 2"
    },
    ...
  ]
}

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.

Facebook Metrics

Required OAuth2 scope: 
api.read

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 /1/facebook/profiles endpoint.
metrics object, the list of metrics that will be returned in the response. Available metrics are listed in the table below.
Basic Metrics
Name Type Example Description
comments integer
100
Number of comments on page posts.
comments_by_ppd_status object
{ "paid": 1, "organic": 2, "unknown": 0 }
Number of comments on page posts by paid status (organic/paid/unknown) based on PPD.
comments_by_type object
{ "video": 1, "photo": 2 }
Number of comments on page posts by post type.
engagement_rate float
4.2
Engagement Rate displays the average number of Interactions per Fan per Post. Engagement Rate is therefore calculated by dividing the number of Interactions of posts published a particular day by the number of Fans on that day and finally by the number of posts on that day. The final Engagement Rate figure is multiplied by 100 and should be displayed as a percentage (Interactions / Fans / Posts * 100). The Engagement Rate for a time period should be calculated as the average of all the Engagement Rate values for all of the days that are being examined.
fans_change integer
100
Absolute change of fans count of a page.
fans_lifetime integer
100
Total number of likes (=fans) of a page.
interactions integer
100
Number of interactions on page posts.
interactions_by_ppd_status object
{ "paid": 1, "organic": 2, "unknown": 0 }
Number of interactions on page posts by paid status (organic/paid/unknown) based on PPD.
interactions_by_type object
{ "video": 1, "photo": 2 }
Number of interactions on page posts by post type.
interactions_per_1000_fans float
1.94042765739004
Number of interactions per thousand fans.
interactions_per_1000_fans_by_type object
{ "photo": 0.94042765739004, "video": 0.001426624803003 }
Number of interactions per thousand fans by type.
page_posts integer
100
Number of page posts.
page_posts_by_app object
{ "web": 1, "Socialbakers": 2 }
Number of page posts by application via it was posted (any facebook app is "web").
page_posts_by_ppd_status object
{ "paid": 1, "organic": 2, "unknown": 0 }
Number of page posts by paid status (organic/paid/unknown) based on PPD.
page_posts_by_type object
{ "video": 1, "photo": 2 }
Number of page posts by post type.
reactions integer
100
Number of reactions on page posts.
reactions_by_ppd_status object
{ "paid": 1, "organic": 2, "unknown": 0 }
Number of reactions on page posts by paid status (organic/paid/unknown) based on PPD.
reactions_by_reaction_type object
{ "love": 1, "haha": 2, "like": 3, "sorry": 4, "anger": 5, "wow": 6 }
Number of reactions on page posts by reaction type (like, love, haha, etc...).
reactions_by_type object
{ "video": 1, "photo": 2 }
Number of reactions on page posts by post type.
shares integer
100
Number of shares on page posts.
shares_by_ppd_status object
{ "paid": 1, "organic": 2, "unknown": 0 }
Number of shares on page posts by paid status (organic/paid/unknown) based on PPD.
shares_by_type object
{ "video": 1, "photo": 2 }
Number of shares on page posts by post type.
user_posts integer
100
Number of user posts.
user_posts_average_response_time integer
100
Average reponse time (mins) of responded user posts.
user_posts_by_app object
{ "web": 1, "Socialbakers": 2 }
Number of user posts by application via it was posted (any facebook app is "web").
user_posts_responded integer
100
Number of user posts that are responded (at least 1 page comment).
user_posts_responded_by_time object
{ "Under 10 mins": 0, "10 - 30 mins": 0, "30 - 60 mins": 0, "60 - 90 mins": 0, "90 mins - 2 hours": 0, "2 - 4 hours": 0, "4 - 6 hours": 0, "6 - 12 hours": 0, "12 - 24 hours": 0, "24 - 48 hours": 0, "48 - 72 hours": 0, "More than 72 hours": 0 }
Number of responded user posts by response time category.
user_posts_response_rate float
1.94042765739004
Ratio of user posts and responded user posts.
user_questions integer
100
Number of user posts that are marked as a question.
user_questions_average_response_time integer
100
Average reponse time (mins) of responded user questions.
user_questions_responded integer
100
Number of user posts that are marked as a question and that are responded (at least 1 page comment).
user_questions_responded_by_time object
{ "Under 10 mins": 0, "10 - 30 mins": 0, "30 - 60 mins": 0, "60 - 90 mins": 0, "90 mins - 2 hours": 0, "2 - 4 hours": 0, "4 - 6 hours": 0, "6 - 12 hours": 0, "12 - 24 hours": 0, "24 - 48 hours": 0, "48 - 72 hours": 0, "More than 72 hours": 0 }
Number of responded user questions by response time category.
user_questions_response_rate float
1.94042765739004
Ratio of user questions and responded user questions.
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 /1/facebook/profiles endpoint.

Name Type Example Description
insights_activity
No longer supported
integer
719
Number of activities created about your Page. (Total Count)
insights_activity_by_activity_type
No longer supported
object
{"other": 345, "fan": 280, "page post": 90, "mention": 4, "user post": 0, "coupon": 0, "checkin": 0, "question": 0, "event": 0 }
Number of activities about your Page by activity type. (Total Count)
insights_activity_unique
No longer supported
integer
35
Number of people sharing activity about your page. These activity include liking your Page, posting to your Page's timeline, liking, commenting on or sharing one of your Page posts, answering a question you posted, responding to one of your events, mentioning your Page, tagging your Page in a photo or checking in at your location. (Unique Users)
insights_activity_unique_by_activity_type
No longer supported
object
{ "fan": 285, "other": 281, "page post": 32, "mention": 4, "user post": 0, "coupon": 0, "checkin": 0, "question": 0, "event": 0 }
Number of people talking about your Page, by activity type. (Unique Users)
insights_activity_unique_by_age_gender
No longer supported
object
{ "M.18-24": 169, "M.25-34": 120, "F.18-24": 85, "F.25-34": 81, "F.35-44": 37, "M.35-44": 35, "M.45-54": 12, "M.55-64": 8, "M.65+": 7, "F.45-54": 6, "F.65+": 6, "U.25-34": 3, "F.55-64": 3, "U.35-44": 2, "F.13-17": 1 }
Number of People Talking About the Page by user age and gender (Unique Users)
insights_activity_unique_by_city
No longer supported
object
{ "Dhaka, Dhaka Division, Bangladesh": 33, "Phnom Penh, Cambodia": 14, "Mexico City, Distrito Federal, Mexico": 13, "Karachi, Sindh, Pakistan": 12, "Ho Chi Minh City, Vietnam": 11, "Cairo, Cairo Governorate, Egypt": 10, ... }
Number of People Talking About the Page by user city. (Unique Users)
insights_activity_unique_by_country
No longer supported
object
{ "PK": 44, "BD": 40, "IN": 30, "BR": 28, "MX": 24, ... }
Number of People Talking About the Page by user country (Unique Users)
insights_activity_unique_by_locale
No longer supported
object
{ "en_US": 302, "en_GB": 99, "es_LA": 48, ... }
Number of People Talking About the Page by user language. (Unique Users)
insights_engaged_users
No longer supported
integer
1134
Number of people who engaged with your Page. Engagement includes any click or activity created. (Unique Users).
insights_fan_adds integer
280
Number of new people who have liked your Page.
insights_fan_adds_by_paid_non_paid_unique object
{ "total": 280, "paid": 194, "unpaid": 86 }
New likes by paid and non-paid : Number of new people who have liked your page broken down by paid and non-paid. (Unique Users)
insights_fan_adds_unique integer
285
New Likes : Number of new people who have liked your Page (Unique Users)
insights_fan_removes integer
33
Number of Unlikes of your Page (Total Count)
insights_fan_removes_unique integer
32
Number of Unlikes of your Page (Unique Users)
insights_fans_by_like_source object
{ "feed_story": 69, "sponsored_story": 52, "feed_pyml": 50, "page_profile": 71, "ads": 9, "api": 5, "mobile_ads": 4, "vertex_page": 3, "timeline_like_chaining": 3, "search": 1, "timeline_collection": 1 }
Breakdown of Number of Page likes from the most common places where people can like your Page. (Total Count)
insights_fans_by_like_source_unique object
{ "feed_story": 69, "sponsored_story": 52, "feed_pyml": 50, "page_profile": 71, "ads": 9, "api": 5, "mobile_ads": 4, "vertex_page": 3, "timeline_like_chaining": 3, "search": 1, "timeline_collection": 1 }
Number of people who liked your Page, broken down by the most common places where people can like your Page. (Unique Users)
insights_fans_by_unlike_source_unique object
{ "normal_unfan": 20, "deactivated_fan_removal": 1 }
Number of people who unliked your Page, broken down by the most common places where people can unlike your Page. (Unique Users)
insights_fans_city object
{ "São Paulo, SP, Brazil": 7073, "Mexico City, Distrito Federal, Mexico": 6622, "Istanbul, Istanbul Province, Turkey": 5061, "Bangkok, Thailand": 3714, ... }
Aggregated location data, sorted by city, number of people who like your Page. (Unique Users)
insights_fans_gender_age_lifetime
No longer supported
object
{ "M.25-34": 61893, "F.25-34": 50721, "M.35-44": 33300, "F.35-44": 22872, "M.18-24": 21956, "F.18-24": 13998, "M.45-54": 12220, "F.45-54": 8169, "M.55-64": 3426, "F.55-64": 2882, "M.65+": 2450, "F.65+": 1687, "F.13-17": 1342, "M.13-17": 1330 }
Aggregated demographic data about the people who like your Page based on the age and gender information they provide in their user profiles. (Unique Users)
insights_fans_lifetime integer
23423234
Number of people who have liked your Page. (Unique Users)
insights_fans_lifetime_by_country object
{ "US": 10539639, "BR": 7059801 }
Lifetime value of number of fans grouped by country.
insights_fans_locale_lifetime object
{ "en_US": 94843, "en_GB": 27878, "es_LA": 27558, "pt_BR": 21176, "fr_FR": 7338, ... }
Aggregated language data about the people who like your Page based on the default language setting selected when accessing Facebook. (Unique Users)
insights_fans_online integer
23423234
Number of people who liked your Page and when they are online (Unique Users)
insights_fans_online_by_hour object
{ "0": 83292, "1": 78332, "2": 83660, "3": 91509, "4": 101188, "5": 108478, "6": 113041, "7": 114870, "8": 113888, "9": 110740, "10": 106890, "11": 103823, "12": 102124, "13": 99136, "14": 91921, "15": 81431, "16": 73596, "17": 70081, "18": 69155, "19": 68482, "20": 65979, "21": 66731, "22": 70748, "23": 74399 }
Number of your fans who saw any posts on Facebook on a given day, broken down by hour of day in PST (Pacific Standard Time)
insights_impressions integer
23423234
Number of impressions seen of any content associated with your Page. (Total Count)
insights_impressions_by_paid_non_paid object
{ "total": 192630, "paid": 169167, "unpaid": 23463 }
Number of impressions seen of any content associated with your page broken down by paid and non-paid. (Total Count)
insights_impressions_organic integer
23423234
Number of times your posts were seen in News Feed or ticker or on visits to your Page. These impressions can be by people who have liked your Page and people who haven't. (Total Count)
insights_impressions_paid integer
23423234
Number of impressions of a Sponsored Story or Ad pointing to your Page. (Total Count)
insights_impressions_viral integer
379
Number of impressions of an activity published by a friend about your Page. These activities include liking your Page, posting to your page's Wall, liking, commenting on or sharing one of your Page posts, answering a Question you posted, RSVPing to one of your events, mentioning your Page, phototagging your Page or checking in at your Place. (Total Count)
insights_impressions_viral_frequency_distribution object
 { "1": 2053, "2": 415, "3": 120, "4": 64, "5": 29, "6-10": 30, "11-20": 10, "21+": 4 }
Number of people your Page reached from a story published by a friend, broken down by how many times people saw activities about your Page. (Unique Users)
insights_negative_feedback integer
23423234
Number of times people have given negative feedback to your Page. (Total Count)
insights_positive_feedback
No longer supported
integer
23423234
Number of times people have given positive feedback to your Page. (Total Count)
insights_post_clicks
No longer supported
integer
1965
Number of clicks on any of your content. Clicks generating activity are included in "Other Clicks." Activities generated without clicks on page content (e.g., liking the page in Timeline) are not included. (Total Count)
insights_post_clicks_by_type
No longer supported
object
{ "photo view": 821, "other clicks": 670, "link clicks": 446, "video play": 4 }
Number of clicks on any of your content, by type. Clicks generating activity are included in "Other Clicks." Activities generated without clicks on page content (e.g., liking the page in Timeline) are not included. Other clicks is defined as "Clicks not on the content of the post, such as page title clicks or click to see more".
insights_post_clicks_unique integer
1650
Number of people who clicked on any of your content. Clicks that create activity are included in "Other Clicks." Activities that are created without clicking on Page content (ex, liking the Page from timeline) are not included. (Unique Users)
insights_post_clicks_unique_by_type object
{ "photo view": 601, "other clicks": 428, "link clicks": 210, "video play": 4 }
Number of of people who clicked on any of your content, by type. Clicks that create activity are included in "Other Clicks." Activities that are created without clicking on Page content (ex, liking the Page from timeline) are not included. (Unique Users)
insights_post_impressions integer
23423234
Number of impressions that came from all of your posts. (Total Count)
insights_post_impressions_by_paid_non_paid object
{ "total": 168616, "paid": 147501, "unpaid": 21115 }
Number of impressions that came from all of your posts broken down by paid and non-paid. (Total Count)
insights_post_impressions_frequency_distribution object
{ "1": 82733, "2": 25929, "3": 6863, "4": 1354, "5": 432, "6-10": 562, "11-20": 106, "21+": 19 }
Number of people who saw your Page posts, broken down by how many times people saw your posts. (Unique Users)
insights_post_impressions_paid integer
23423234
Number of impressions of your Page posts in an Ad or Sponsored Story. (Total Count)
insights_post_reach integer
23423234
Number of people who saw any of your Page posts. (Unique Users)
insights_post_reach_by_paid_non_paid object
{ "total": 115514, "paid": 105891, "unpaid": 9623 }
Number of impressions that came from all of your posts broken down by paid and non-paid. (Unique Users)
insights_post_reach_organic integer
23423234
Number of people who saw your Page posts in news feed or ticker, or on your Page's timeline. (Unique Users)
insights_post_reach_paid integer
23423234
Number of people who saw your Page posts in an ad or sponsored story. (Unique Users)
insights_reach integer
23423234
Number of people who have seen any content associated with your Page. (Unique Users)
insights_reach_by_age_gender object
{ "M.25-34": 32425, "M.18-24": 25498, "F.25-34": 19674, "F.18-24": 14386, "M.35-44": 11693, "F.35-44": 7029, "M.45-54": 3339, "F.45-54": 2198, "M.55-64": 1317, "M.65+": 1275, "F.55-64": 873, "F.65+": 692, "M.13-17": 31, "F.13-17": 31 }
Total Page Reach by age and gender. (Unique Users)
insights_reach_by_paid_non_paid object
{ "total": 119886, "paid": 108459, "unpaid": 11427 }
Number of impressions seen of any content associated with your page broken down by paid and non-paid. (Unique Users)
insights_reach_engagement
No longer supported
float
0.013763074921175114
Number of people who engaged with your Page per Number of people who have seen any content associated with your Page. Engagement includes any click or activity created.
insights_reach_organic integer
23423234
Number of people who visited your Page, or saw your Page or one of its posts in news feed or ticker. These can be people who have liked your Page and people who haven't. (Unique Users)
insights_reach_paid integer
23423234
Number of people who saw a sponsored story or ad pointing to your Page. (Unique Users)
insights_reach_viral integer
379
Number of people who saw your Page or one of its posts from a activity shared by a friend. These activities include liking your Page, posting to your page's timeline, liking, commenting on or sharing one of your Page posts, answering a question you posted, responding to one of your events, mentioning your Page, tagging your Page in a photo or checking in at your location. (Unique Users)
insights_reactions integer
100
Number of reactions on any of your content.
insights_reactions_by_type object
{ "like": 319, "love": 4, "wow": 7, "haha": 0, "sorry": 0, "anger": 0 }
Number of reactions on any of your content by type.
insights_video_complete_views_30s integer
5
Number of times page's videos have been viewed for more than 30 seconds
insights_video_complete_views_30s_autoplayed integer
5
Number of times page's autoplayed videos have been viewed for more than 30 seconds
insights_video_complete_views_30s_click_to_play integer
1
Number of times page's videos have been viewed after the user clicks on play for more than 30 seconds
insights_video_complete_views_30s_organic integer
5
Number of times page's videos have been viewed for more than 30 seconds by organic reach
insights_video_complete_views_30s_repeat_views integer
9
Number of times that people replay a page's videos for more than 30 seconds
insights_video_complete_views_30s_unique integer
62
Number of times page's videos have been played for unique people for more than 30 seconds
insights_video_repeat_views integer
35
Number of times that people replay a page's videos for more than 3 seconds
insights_video_views integer
6
Number of times page's videos have been viewed for more than 3 seconds
insights_video_views_autoplayed integer
5
Number of times page's autoplayed videos have been viewed for more than 3 seconds
insights_video_views_click_to_play integer
10
Number of times page's videos have been viewed after the user clicks on play for more than 3 seconds
insights_video_views_organic integer Number of times page's videos have been viewed for more than 3 seconds by organic reach
insights_video_views_paid integer
44
Number of times page's promoted videos have been viewed for more than 3 seconds
insights_video_views_unique integer
55
Number of times page's videos have been played for unique people for more than 3 seconds
insights_views integer
379
Page views (Total Count)

Example request

POST /1/facebook/metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "date_start": "2016-01-01",
  "date_end": "2016-01-02",
  "profiles": ["164929129743", "477018229123929"],
  "metrics": ["fans_lifetime", "fans_change", ...]
}

Example response

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

Instagram Metrics

Required OAuth2 scope: 
api.read

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 /1/instagram/profiles endpoint.
metrics The list of metrics that will be returned in the response. Available metrics are listed in the table below.
Basic Metrics
Name Type Example Description
comments integer
100
Number of comments of profile posts.
comments_by_image_filter
No longer supported
object
{ "Normal": 1, "Clarendon": 2 }
Number of comments of profile posts by used image filter of that post.
comments_by_type object
{ "image": 1, "video": 2 }
Number of comments of profile posts by post type.
comments_by_video_filter
No longer supported
object
{ "Normal": 1 }
Number of comments of profile posts by used video filter of that post.
engagement_rate float
4.2
Engagement Rate displays the average number of Interactions per Fan per Post. Engagement Rate is therefore calculated by dividing the number of Interactions of posts published a particular day by the number of Fans on that day and finally by the number of posts on that day. The final Engagement Rate figure is multiplied by 100 and should be displayed as a percentage (Interactions / Fans / Posts * 100). The Engagement Rate for a time period should be calculated as the average of all the Engagement Rate values for all of the days that are being examined.
followers_change integer
100
Absolute change of followers count lifetime.
followers_lifetime integer
100
Followers count - lifetime value.
following_change integer
100
Absolute change of following count lifetime.
following_lifetime integer
100
Following count - lifetime value.
interactions integer
100
Number of interactions (likes and comments) of profile posts.
interactions_by_image_filter
No longer supported
object
{ "Normal": 1, "Clarendon": 2 }
Number of interactions of profile posts by used image filter of that post.
interactions_by_type object
{ "image": 1, "video": 2 }
Number of interactions of profile posts by post type.
interactions_by_video_filter
No longer supported
object
{ "Normal": 1 }
Number of interactions of profile posts by used video filter of that post.
interactions_per_1000_followers float
11.94042765739004
Number of interactions (likes and comments) per thousand followers.
interactions_per_1000_followers_by_image_filter
No longer supported
object
{ "Normal": 11.94042765739004, "Clarendon": 12.94042765739004 }
Number of interactions (likes and comments) per thousand followers by used image filter.
interactions_per_1000_followers_by_type object
{ "image": 10.94042765739004, "video": 11.94042765739004 }
Number of interactions (likes and comments) per thousand followers by used post type.
interactions_per_1000_followers_by_video_filter
No longer supported
object
{ "Normal": 10.94042765739004 }
Number of interactions (likes and comments) per thousand followers by used video filter.
likes integer
100
Number of likes of profile posts.
likes_by_image_filter
No longer supported
object
{ "Normal": 1, "Clarendon": 2 }
Number of likes of profile posts by used image filter of that post.
likes_by_post_type object
{ "image": 1, "video": 2 }
Number of likes of profile posts by post type.
likes_by_video_filter
No longer supported
object
{ "Normal": 1 }
Number of likes of profile posts by used video filter of that post.
profile_posts integer
100
Number of profile posts.
profile_posts_by_image_filter
No longer supported
object
{ "Normal": 1, "Clarendon": 2 }
Number of profile posts by used image filter of that post.
profile_posts_by_type object
{ "image": 1, "video": 2 }
Number of profile posts by post type.
profile_posts_by_video_filter
No longer supported
object
{ "Normal": 1 }
Number of profile posts by used video filter of that post.
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 /1/instagram/profiles endpoint.

Name Type Example Description
insights_followers_by_city_by_day object
{ "Dhaka, Dhaka Division, Bangladesh": 33, "Phnom Penh, Cambodia": 14, "Mexico City, Distrito Federal, Mexico": 13, ... }
The cities of the Business Account's followers.
insights_followers_by_country_by_day object
{ "PK": 44, "BD": 40, "IN": 30, "BR": 28, "MX": 24, ... }
The countries of the Business Account's followers.
insights_followers_by_gender_by_age_by_day object
{ "M.18-24": 169, "M.25-34": 120, "F.18-24": 85, "F.25-34": 81, "F.35-44": 37, "M.35-44": 35, "M.45-54": 12, "M.55-64": 8, "M.65+": 7, "F.45-54": 6, "F.65+": 6, "U.25-34": 3, "F.55-64": 3, "U.35-44": 2, "F.13-17": 1 }
The gender and age distribution of the Business Account's followers.
insights_post_engagement_by_day integer
100
Total number of likes and comments on the posts.
insights_post_engagement_by_type_by_day object
{ "video": 100, "carousel_album": 100, "carousel": 100, "image": 100 }
Total engagement (likes and comments) broken down by post type (video, carousel album, carousel, image).
insights_post_impressions_by_day integer
100
The number of times posts have been seen.
insights_post_impressions_by_type_by_day object
{ "video": 100, "carousel_album": 100, "carousel": 100, "image": 100 }
The number of times posts have been seen, broken down by post type.
insights_post_interactions_by_day integer
100
The number of Likes, Comments and Saves posts received. The data source of this chart is different from the post_engagement. As a result, the number of interactions may vary.
insights_post_interactions_by_int_type_by_day object
{ "like": 100, "saved": 100, "comment": 100 }
The number of Likes, Comments and Saves posts received, broken down by the type of Interactions. The data source of this chart is different from the post_engagement. As a result, the number of interactions may vary.
insights_post_saves_by_day integer
100
Total number of saves on the posts.
insights_post_saves_by_type_by_day object
{ "video": 100, "carousel_album": 100, "carousel": 100, "image": 100 }
Total number of saves broken down by post type (video, carousel album, carousel, image).
insights_post_video_views_by_day integer
100
The number of times videos have been viewed.
insights_post_video_views_by_type_by_day object
{ "video": 100, "carousel_album": 100, "carousel": 100, "image": 100 }
The number of times videos have been viewed, broken down by video type.
insights_profile_all_clicks_by_day integer
100
The number of times user clicked on a specific contact on your Business Account's profile.
insights_profile_email_contacts_by_day integer
100
Total number of taps on the email link in the Business Account's profile.
insights_profile_get_directions_clicks_by_day integer
100
Total number of taps on the directions link in the Business Account's profile.
insights_profile_impressions_by_day integer
100
Total number of times the Business Account's media objects (i.e. posts, stories and promotions) have been viewed. Does not include profile views.
insights_profile_phone_call_clicks_by_day integer
100
Total number of taps on the call link in the Business Account's profile.
insights_profile_reach_by_day integer
100
Unique Impressions (Reach) refers to the number of different people who see your post. One person can see your post 5 times but is only counted once toward Reach.
insights_profile_text_message_clicks_by_day integer
100
Total number of taps on the text message link in the Business Account's profile.
insights_profile_views_by_day integer
100
Total number of unique users who have viewed the Business Account's profile.
insights_profile_website_clicks_by_day integer
100
Total number of taps on the website link in the Business Account's profile.

Example request

POST /1/instagram/metrics HTTPS
Host: api.emplifi.io
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_lifetime", "followers_change", ...]
}

Example response

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

Twitter Metrics

Required OAuth2 scope: 
api.read

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 /1/twitter/profiles endpoint.
metrics The list of metrics that will be returned in the response. Available metrics are listed in the table below.
Metrics
Name Type Example Description
engagement_rate float
4.2
Engagement Rate displays the average number of Interactions per Fan per Post. Engagement Rate is therefore calculated by dividing the number of Interactions of posts published a particular day by the number of Fans on that day and finally by the number of posts on that day. The final Engagement Rate figure is multiplied by 100 and should be displayed as a percentage (Interactions / Fans / Posts * 100). The Engagement Rate for a time period should be calculated as the average of all the Engagement Rate values for all of the days that are being examined.
ff_ratio float
97.1443812233286
Absolute change of following count lifetime.
followers_change integer
100
Absolute change of followers count lifetime.
followers_lifetime integer
100
Followers count - lifetime value.
following_change integer
100
Absolute change of following count lifetime.
following_lifetime integer
100
Following count - lifetime value.
incoming integer
100
Number of all incoming activities (mentions + retweets + replies) created by others mentioning this profile.
incoming_questions integer
100
Number of user tweets that are also marked as a question.
incoming_questions_average_response_time float
12.34
Average reponse time (mins) of responded user questions.
incoming_questions_responded integer
100
Number of user tweets that are marked as a question and that are responded (profile reply).
incoming_questions_responded_by_time object
{ "Under 10 mins": 0, "10 - 30 mins": 0, "30 - 60 mins": 0, "60 - 90 mins": 0, "90 mins - 2 hours": 0, "2 - 4 hours": 0, "4 - 6 hours": 0, "6 - 12 hours": 0, "12 - 24 hours": 0, "24 - 48 hours": 0, "48 - 72 hours": 0, "More than 72 hours": 0 }
Number of responded user questions by response time category.
incoming_questions_response_rate float
0.02409638554216
Ratio of user questions and responded user questions.
incoming_replies integer
100
Number of replies made by others.
incoming_retweets integer
100
Number of retweets made by others.
incoming_tweets integer
100
Number of user tweets. User tweet is considered any incoming activity (mention, reply), exluding retweets.
incoming_tweets_average_response_time float
12.34
Average reponse time (mins) of responded user tweets.
incoming_tweets_responded integer
100
Number of user tweets that are responded (profile reply).
incoming_tweets_responded_by_time object
{ "Under 10 mins": 0, "10 - 30 mins": 0, "30 - 60 mins": 0, "60 - 90 mins": 0, "90 mins - 2 hours": 0, "2 - 4 hours": 0, "4 - 6 hours": 0, "6 - 12 hours": 0, "12 - 24 hours": 0, "24 - 48 hours": 0, "48 - 72 hours": 0, "More than 72 hours": 0 }
Number of responded user tweets by response time category.
incoming_tweets_response_rate float
0.02409638554216
Ratio of user tweets and responded user tweets.
interactions integer
100
Number of interactions on profile tweets and replies.
interactions_per_1000_followers float
1.55379654060392
Number of interactions per thousand followers.
likes integer
100
Number of likes on profile tweets and replies.
listed_change integer
100
Absolute change of listed count lifetime.
listed_lifetime integer
100
Listed count - lifetime value (how many times profile has been listed).
profile_activities integer
100
Number of all activities (tweets + retweets + replies) created by the profile.
profile_activities_by_app object
{ "twitter-web-client": 1, "tweetdeck": 2 }
Number of all activities posted by profile by application via it was posted.
profile_replies integer
100
Number of replies made by profile.
profile_retweets integer
100
Number of retweets made by profile.
profile_tweets integer
100
Number of tweets made by profile.
replies integer
100
Number of replies on profile tweets and replies.
retweets integer
100
Number of retweets on profile tweets and replies.

Example request

POST /1/twitter/metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "date_start": "2016-01-01",
  "date_end": "2016-01-02",
  "profiles": ["78569316", "3311741584"],
  "metrics": ["followers_lifetime", "followers_change", ...]
}

Example response

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

YouTube Metrics

Required OAuth2 scope: 
api.read

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 /1/youtube/profiles endpoint.
metrics The list of metrics that will be returned in the response. Available metrics are listed in the table below.
Metrics
Name Type Example Description
comments_change integer
100
Absolute change of comments count on uploaded videos.
dislikes_change integer
100
Absolute change of dislikes count on uploaded videos. Dislike count is no longer available as of December 13, 2021 Learn more
engagement_rate float
4.2
Engagement Rate displays the average number of Interactions per Fan per Post. Engagement Rate is therefore calculated by dividing the number of Interactions of posts published a particular day by the number of Fans on that day and finally by the number of posts on that day. The final Engagement Rate figure is multiplied by 100 and should be displayed as a percentage (Interactions / Fans / Posts * 100). The Engagement Rate for a time period should be calculated as the average of all the Engagement Rate values for all of the days that are being examined. Dislike count is no longer available for this metric as of December 13, 2021 Learn more.
interaction_change integer
100
Absolute change of interactions (likes + dislikes + comments) count on uploaded videos. Dislike count is no longer available for this metric as of December 13, 2021 Learn more.
interactions_per_1000_subscribers float
23.56734832691981
Daily growth of interactions per thousand subscribers on all uploaded videos by the channel on a given day. Number is aggregated by day to the midnight of UTC timezone. Dislike count is no longer available for this metric as of December 13, 2021 Learn more.
likes_change integer
100
Absolute change of likes count on uploaded videos.
subscribers_change integer
100
Absolute change of subscribers count lifetime.
subscribers_count_lifetime integer
100
Subscribers count - lifetime value.
video_change integer
100
Absolute change of videos count lifetime.
video_count_lifetime integer
100
Video count - lifetime value.
viewed_time_change integer
100
Absolute change of viewed time (in seconds) lifetime. Viewed time for each video is number of views multiplied by length of the video.
viewed_time_lifetime integer
100
Viewed time (in seconds) of all uploaded videos - lifetime value. Viewed time for each video is number of views multiplied by length of the video.
views_change integer
100
Absolute change of views count lifetime.
views_count_lifetime integer
100
Views count of all uploaded videos - lifetime value.

Example request

POST /1/youtube/metrics HTTPS
Host: api.emplifi.io
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_lifetime", "subscribers_change", ...]
}

Example response

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

Pinterest Metrics

Required OAuth2 scope: 
api.read

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 /1/pinterest/profiles endpoint.
metrics The list of metrics that will be returned in the response. Available metrics are listed in the table below.
Metrics
Name Type Example Description
boards_change integer
100
Absolute change of boards count lifetime.
boards_lifetime integer
100
Boards count - lifetime value.
comments integer
100
Number of comments on profile pins.
followers_change integer
100
Absolute change of followers count lifetime.
followers_lifetime integer
100
Followers count - lifetime value.
following_change integer
100
Absolute change of following count lifetime.
following_lifetime integer
100
Following count - lifetime value.
interactions integer
100
Number of interactions on profile pins.
likes integer
100
Number of likes on profile pins.
pins_change integer
100
Absolute change of pins count lifetime.
pins_lifetime integer
100
Pins count - lifetime value
repins integer
100
Number of repins on profile pins.

Example request

POST /1/pinterest/metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

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

Example response

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

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

Required OAuth2 scope: 
api.read

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 /1/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 /1/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"}]
Array of objects containing details about post attachments. Fields: title, description, url, image_url.
author_id string
164929129743
Facebook page post author profile id.
comments integer
100
Facebook post comments count.
created_time datetime
2016-10-24T16:15:04+00:00
Facebook post created time.
engagement_rate float
4.2
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.
id string
164929129743_10154702368914744
Facebook post id.
interactions integer
100
Facebook post interaction count.
is_published boolean
true
Is post published
message string
A free tool that delivers a custom benchmark report, in minutes, so you can easily understand how well you are using social media to nurture customer relationships. Do you know your numbers?
Facebook post contents.
page_id string
164929129743
Facebook page id for the published post.
post_labels array
[{"id": "as3442fs", "name": "label 1"}, {"id": "vz4451jg", "name": "label 2"}]
Array of content labels (formally post labels) for given post and account
ppd_status string
paid|organic|unknown
Indicates whether the post was organic, paid or unknown based on PPD algorithm.
reactions integer
100
Facebook post reactions count.
reactions_by_type object
{"like": 548, "love": 2, "wow": 2, "haha": 0, "sorry": 0, "anger": 0}
Object containing Facebook post reactions number.
shares integer
100
Facebook post share count.
story string
Socialbakers published a note
Text from stories not intentionally generated by users, such as those generated when two people become friends, or when someone else posts on the person's wall.
type string
photo|status|link|video|offer|note|poll|unknown
Facebook post type.
universal_video_id string
164929129743_10156499215049744
The publishers asset management code for this video. Only available in case the post type is a video.
url string
https://www.facebook.com/permalink.php?story_fbid=10154702368914744&id=164929129743
Link to facebook post.
video_id string
10156498782054744
The id of the video object. Only available in case the post type is a video.
video_length float
125.481
Duration of the video in seconds. Only available in case the post type is a 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 /1/facebook/profiles endpoint.

Name Type Example Description
insights_engaged_fan integer
100
People who have liked your page and engaged with your post.
insights_engaged_users integer
100
The number of people who clicked anywhere in your posts
insights_engagement_rate
No longer supported
float
0.0378
Reach shows you how many people were exposed to your content and Reach Engagement Rate shows you how many of those reached people actually interacted with it.

We have updated and improved this metric and it is available for you to use from the latest API version. The older version of this metric will still return data for the time being but please bear in mind that this will show different values in comparison to the new one. If you are interested about the details of the new metric, please check this article.
insights_impressions integer
100
The number of impressions for your Page post
insights_impressions_by_paid_non_paid object
{ "paid": 0, "unpaid": 7655, "total": 7655 }
The number of impressions for your Page post, broken down by total, paid, and non-paid
insights_impressions_fan integer
100
The number of impressions for your Page post by people who have liked your Page
insights_impressions_fan_paid integer
100
The number of impressions for your Page post by people who like your Page in an Ad or Sponsored Story
insights_impressions_organic integer
100
The number of impressions of your post in Newsfeed, Ticker, or on your Page's Wall
insights_impressions_paid integer
100
The number of impressions for your Page post in an Ad or Sponsored Story
insights_negative_feedback integer
100
The number of times people took a negative action in your post (e.g. hid it)
insights_negative_feedback_unique integer
100
The number of people who took a negative action in your post (e.g., hid it)
insights_paid_status string
paid|organic
Whether the post has been promoted (received any paid impression) or not
insights_post_clicks integer
100
The number of times people clicked on anywhere in your posts without generating an activity
insights_post_clicks_by_type object
{"photo view": 368, "other clicks": 186, "link clicks": 1, "video play": 0},
The number of times people clicked on anywhere in your posts without generating an activity, broken-down by post click type.
insights_post_clicks_by_type_unique object
{"photo view": 4, "other clicks": 15, "link clicks": 46, "video play": 0},
The number of people who clicked anywhere in your post without generating an activity, broken-down by post click type.
insights_post_clicks_unique integer
100
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 Page post
insights_reach_by_paid_non_paid object
{ "paid": 0, "unpaid": 7655, "total": 7655 }
The number of people who saw your Page post, broken down by total, paid, and non-paid
insights_reach_fan integer
100
The number of people who have like your Page who saw your Page post
insights_reach_fan_paid integer
100
The number of people who have like your Page and saw your Page post in an Ad or Sponsored Story
insights_reach_organic integer
100
The number of people who saw your post in their Newsfeed or Ticker or on your Page's Wall
insights_reach_paid integer
100
The number of people who saw your Page post in an Ad or Sponsored Story
insights_reactions_by_type_total object
{"like": 8, "love": 0, "wow": 0, "haha": 0, "sorry": 0, "anger": 0}
The number of reactions to a Page's post by reaction type.
insights_reactions_like_total integer
100
The number of "like" reactions to a post.
insights_stories integer
100
The number of stories created about your Page (Stories)
insights_story_adds integer
100
The number of stories generated about your Page post.
insights_storytellers integer
100
The number of people sharing stories about your page ("People Talking About This" / PTAT). These stories include liking your Page, posting to your Page's Wall, liking, commenting on or sharing one of your Page posts, answering a Question you posted, RSVPing to one of your events, mentioning your Page, phototagging your Page or checking in at your Place
insights_video_avg_time_watched integer
100
The average length of time (in milliseconds) people spent viewing your video
insights_video_complete_views_30s integer
100
Total number of times Page's videos have been viewed for more than 30 seconds
insights_video_complete_views_30s_autoplayed integer
100
Total number of times Page's autoplayed videos have been viewed to the end, or viewed for more than 30 seconds
insights_video_complete_views_30s_clicked_to_play integer
100
Total number of times Page's videos have been viewed to the end, or viewed after the user clicks on play for more than 30 seconds
insights_video_complete_views_30s_organic integer
100
Total number of times Page's videos have been viewed to the end, or viewed for more than 30 seconds by organic reach
insights_video_complete_views_30s_paid integer
100
Total number of times Page's promoted videos have been viewed to the end, or for more than 30 seconds
insights_video_complete_views_30s_unique integer
100
Total number of times Page's videos have been played for unique people to the end, or viewed for more than 30 seconds
insights_video_complete_views_organic integer
100
The number of times your video was organically viewed from the beginning to 95% of its length
insights_video_complete_views_organic_unique integer
100
The number of people who viewed your video organically from the beginning to 95% of its length
insights_video_complete_views_paid integer
100
The number of times your video was viewed via paid impression from the beginning to 95% of its length
insights_video_complete_views_paid_unique integer
100
The number of people who viewed your video via paid impression from the beginning to 95% of its length
insights_video_retention_graph array
[0.6680000000000001, 1, 0.9683999999999999, 0.8257000000000001, 0.7319000000000001, 0.6640000000000001]
Percentage of viewers at each interval. Video length is divided into short buckets. Each key in response represents a bucket. Values are percent of people saw the video in that bucket
insights_video_retention_graph_autoplayed array
[0.6680000000000001, 1, 0.9683999999999999, 0.8257000000000001, 0.7319000000000001, 0.6640000000000001]
Percentage of viewers at each interval where the video started playing automatically. Video length is divided into short buckets. Each key in response represents a bucket. Values are percent of people saw the video in that bucket
insights_video_view_time integer
100
The total number of milliseconds your video was watched, including replays and views less than 3 seconds.
insights_video_view_time_by_age_bucket_and_gender object
{"M.25-34": 41521414, "U.18-24": 6220}
The total time, in milliseconds, your video played for your Top Audiences, age and gender
insights_video_view_time_by_country_id object
{"US":123, "CZ":54, "DE":6}
The total number of minutes your video played for your Top 45 Locations - Countries
insights_video_view_time_organic integer
100
Total time (in milliseconds) video has been viewed without paid promotion
insights_video_view_time_paid integer
100
Total time (in milliseconds) video has been viewed with paid promotion
insights_video_views integer
100
The number of times your video was watched for an aggregate of at least 3 seconds, or for nearly its total length, whichever happened first.
insights_video_views_autoplayed integer
100
Number of times your video started automatically playing and people viewed it for more than 3 seconds
insights_video_views_clicked_to_play integer
100
Number of times people clicked to play your video and viewed it more than 3 seconds
insights_video_views_organic integer
100
The number of times your video was organically viewed for 3 seconds or more
insights_video_views_organic_unique integer
100
The number of people who viewed at least 3 seconds of your video organically
insights_video_views_paid integer
100
The number of times your video was viewed via paid impression for 3 seconds or more
insights_video_views_paid_unique integer
100
The number of people who viewed at least 3 seconds of your video via paid impression
insights_video_views_unique integer
100
The number of distinct people who viewed your video at least once.

Fields that might be used to sort Facebook posts:
Basic Fields
  • comments
  • created_time
  • interactions
  • 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_engagement_rate  
    No longer supported
  • insights_impressions
  • insights_impressions_organic
  • insights_impressions_paid
  • insights_post_clicks
  • insights_post_clicks_by_type_unique.link clicks
  • insights_post_clicks_by_type_unique.photo view
  • insights_post_clicks_by_type_unique.video play
  • insights_reach
  • insights_reach_organic
  • insights_reach_paid
  • insights_video_avg_time_watched
  • insights_video_complete_views_30s
  • insights_video_view_time
  • insights_video_views
  • insights_video_views_organic
  • insights_video_views_paid
  • insights_video_views_unique

Fields that might be used to filter Facebook posts:
Basic FieldsInsights Fields
  • insights_paid_status

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 /1/facebook/page/posts HTTPS
Host: api.emplifi.io
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": "Content Label 1"
          }
        ],
        "story": "Emplifi 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

Required OAuth2 scope: 
api.read

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 /1/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 /1/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
[{ "images": [{ "url": "https://external.xx.fbcdn.net/safe_image.php?d=AQCXbmZ491Pwd29M&url=https%3A%2F%2Fcdn.socialbakers.com%2Fwww%2Fstorage%2Fmicrosites%2Fkyn%2FOG-KYN.jpg" ]}, "videos": [], "indices": [] }]
Array of objects containing details about post attachments. Fields: url, type, width, height
author_id string
490402220
Author profile ID.
comments integer
100
Total number of comments on the media object.
created_time datetime
2016-10-24T16:15:04+00:00
Instagram media created time.
engagement_rate float
4.2
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.
id string
17966172199068623_490402220
Instagram media ID.
interactions integer
100
Total number of interactions on the media object.
likes integer
100
Total number of likes on the media object.
message string
A first instagram post
Instagram media contents.
post_labels array
[{"id": "as3442fs", "name": "label 1"}, {"id": "vz4451jg", "name": "label 2"}]
Array of content labels (formally post labels) for given post and account
type string
carousel|image|video|carousel_album
Media post type.
url string
https://www.instagram.com/p/Bk4f5J_gypJ/
Link to 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 /1/instagram/profiles endpoint.

Name Type Example Description
insights_engagement
No longer supported
integer
100
Total number of likes and comments on the media object.

We have updated and improved this metric and it is available for you to use from the latest API version. The older version of this metric will still return data for the time being but please bear in mind that this will show different values in comparison to the new one. If you are interested about the details of the new metric, please check this article.
insights_impressions integer
100
Total number of times the media object has been seen.
insights_reach integer
100
Total number of unique accounts that have seen the media object.
insights_saved integer
100
Total number of unique accounts that have saved the media object.
insights_video_views integer
100
(Videos only) Total number of times the video has been seen. Returns 0 for videos in carousel albums.

Fields that might be used to sort Instagram posts:
Basic Fields
  • comments
  • created_time
  • interactions
  • likes
Insights Fields
  • insights_engagement  
    No longer supported
  • insights_impressions
  • insights_reach
  • insights_saved
  • insights_video_views

Fields that might be used to filter Instagram posts:
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 /1/instagram/profile/posts HTTPS
Host: api.emplifi.io
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": "Content 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
  }
}

Twitter Tweets Metrics

Required OAuth2 scope: 
api.read

Returns tweets metrics for each requested Twitter profile.

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

Parameters

Name Description
profiles array, list of profile IDs of the profiles available from the /1/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 /1/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.
Fields
Name Type Example Description
attachments
No longer supported
array
{"attachments":[{"url":"https://t.co/zj4QKZ9oLr","display_url":"en.wikipedia.org/wiki/Let_3","expanded_url":"https://en.wikipedia.org/wiki/Let_3","indices":[0,23]},{"url":"https://t.co/TydZGpShh8","display_url":"pic.twitter.com/TydZGpShh8","expanded_url":"https://twitter.com/aljinovicante/status/838708864761671680/video/1","indices":[42,65],"image":{"width":320,"height":224,"url":"http://pbs.twimg.com/ext_tw_video_thumb/838708091659116544/pu/img/yrYiZy7QwfT5wVQn.jpg:small"},"images":[{"width":320,"height":224,"url":"http://pbs.twimg.com/ext_tw_video_thumb/838708091659116544/pu/img/yrYiZy7QwfT5wVQn.jpg:small"},{"width":320,"height":224,"url":"http://pbs.twimg.com/ext_tw_video_thumb/838708091659116544/pu/img/yrYiZy7QwfT5wVQn.jpg:medium"},{"width":320,"height":224,"url":"http://pbs.twimg.com/ext_tw_video_thumb/838708091659116544/pu/img/yrYiZy7QwfT5wVQn.jpg:large"},{"width":150,"height":150,"url":"http://pbs.twimg.com/ext_tw_video_thumb/838708091659116544/pu/img/yrYiZy7QwfT5wVQn.jpg:thumb"}]}]}
Array of objects containing details about post attachments.
author_id string
100004577
Tweet author profile id.
coordinates
No longer supported
object
{"coordinates": [ 16.449281999999997, 43.523876 ]}
Represents the geographic location of this Tweet as reported by the user or client application. The inner coordinates array is formatted as geoJSON (longitude first, then latitude).
created_time
No longer supported
datetime
2016-10-24T16:15:04+00:00
Tweet created time.
engagement_rate float
4.2
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.
entities
No longer supported
object
{"entities":{"hashtags":[{"indices":[10,14],"text":"bla"}],"tags":[{"id":"1964904343","indices":[15,26],"name":"Jurica Grgicevic","text":"jgrgicevic","type":"user"}]}}
Entities provide metadata and additional contextual information about content posted on Twitter.
id string
833759796105007104
Tweet id.
in_reply_to_user_id
No longer supported
string
719525790308765697
If the represented Tweet is a reply, this field will contain the integer representation of the original Tweet’s author ID.
interactions
No longer supported
integer
100
Number of interactions.
language
No longer supported
string
en
Indicates a BCP 47 language identifier corresponding to the machine-detected language of the Tweet text.
likes
No longer supported
integer
100
Number of times tweet was liked (favorited).
mentions
No longer supported
array
[ "1964904343" ]
List of Twitter profile ids mentioned.
message
No longer supported
string
A free tool that delivers a custom benchmark report, in minutes, so you can easily understand how well you are using social media to nurture customer relationships. Do you know your numbers?
Tweet content.
post_labels array
[{"id": "as3442fs", "name": "label 1"}, {"id": "vz4451jg", "name": "label 2"}]
Array of content labels (formally post labels) for given tweet and account
replies
No longer supported
integer
100
Number of replies.
retweeted_user_id
No longer supported
string
719525790308765697
If the represented Tweet is a retweet, this field will contain the integer representation of the original Tweet’s author ID.
shares
No longer supported
integer
100
Number of shares.
source
No longer supported
object
{ "name": "Twitter Ads", "id": "<a href=\"https://ads.twitter.com\" rel=\"nofollow\">Twitter Ads</a>;" }
id: HTML-formatted string linking to utility used to create the tweet; name: name of the utility
type
No longer supported
string
animated_gif|link|photo|status|video
List of tweet types.

Fields that might be used to filter Twitter posts:
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 /1/twitter/profile/tweets HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "profiles": ["1964904343", "8643567434"],
  "date_start": "2016-01-01",
  "date_end": "2017-01-01",
  "fields": [
    "id",
    "author_id",
    "post_labels"
  ],
  "filter": [
    {
      "match_any": [
        {
          "field": "post_labels",
          "value": [
            "fa14dde7e4f041e3a646",
            "890c135d9cee4cf89b42"
          ]
        }
      ]
    }
  ],
  "limit": 5
}

Example response

{
  "success": true,
  "data": {
    "posts": [
      {
        "id": "689427258210004992",
        "post_labels": [
          {
            "id": "fa14dde7e4f041e3a646",
            "name": "Content Label 1"
          }
        ],
        "author_id": "1964904343",
      }
    ],
    "remaining": 0
  }
}
                

YouTube Profile Video Metrics

Required OAuth2 scope: 
api.read

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 /1/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 /1/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.
Fields
Name Type Example Description
author_id string
UCA6AG33Zac0xi6f9VMTxkFQ
The ID that YouTube uses to uniquely identify the channel that the video was uploaded to.
comments integer
100
The number of comments for the video.
created_time datetime
2018-09-03T16:15:04+00:00
The date and time when the uploaded video file was created.
dislikes integer
100
Number of dislikes for the video. Dislike count is no longer available as of December 13, 2021 Learn more.
duration integer
100
The length of the video [s].
engagement_rate float
4.2
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. Dislike count is no longer available for this metric as of December 13, 2021 Learn more.
id string
UCA6AG33Zac0xi6f9VMTxkFQ
The ID that YouTube uses to uniquely identify the video.
interactions integer
100
Sum of likes and comments. Dislike count is no longer available for this metric as of December 13, 2021 Learn more.
likes integer
100
The number of users who have indicated that they liked the video.
message string
Get caught up on the most important social media news of the week!
Beginner-friendly guide to Influencer Marketing: http://goo.gl/aTWHRV
The video's description.
post_labels array
[{"id": "as3442fs", "name": "label 1"}, {"id": "vz4451jg", "name": "label 2"}]
Array of content labels (formally post labels) for given profile and account
published_time datetime
2018-08-03T12:30:05+00:00
The date and time when the video was published.
video_view_time integer
100
The number of time the video has been viewed multiplied by duration [s].
video_views integer
100
The 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
  • likes
  • published_time
  • 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 /1/youtube/profile/videos HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "profiles": ["UCA6AG33Zac0xi6f9VMTxkFQ", "455DFG232sdg677"],
  "date_start": "2018-06-01",
  "date_end": "2018-08-31",
  "fields": [
    "id",
    "created_time",
    "message",
    "author_id",
    "comments",
    "duration",
    "video_view_time",
    "published_time",
    "dislikes",
    "video_views",
    "likes",
    "interactions",
    "post_labels"
  ],
  "sort": [
    {
      "field": "created_time",
      "order": "desc"
    }
  ],
  "filter": [
    {
      "match_any": [
        {
          "field": "post_labels",
          "value": [
            "fa14dde7e4f041e3a646",
            "890c135d9cee4cf89b42"
          ]
        }
      ]
    }
  ],
  "limit": 5
}

Example response

{
  "success": true,
  "data": {
    "posts": [
      {
        "id": "6Ol7dJtKcq0",
        "created_time": "2018-06-15T14:41:32.000Z",
        "message": "Get caught up on the most important social media news of the week!\nBeginner-friendly guide to Influencer Marketing: http://goo.gl/aTWHRV",
        "author_id": "UCA6AG33Zac0xi6f9VMTxkFQ",
        "comments": 0,
        "likes": 6,
        "duration": 114,
        "video_view_time": 41040,
        "published_time": "2018-06-15T14:41:32.000Z",
        "dislikes": 0,
        "video_views": 360,
        "interactions": 6,
        "post_labels": [
          {
            "id": "fa14dde7e4f041e3a646",
            "name": "Content Label 1"
          }
        ]
      },
    ],
    "next": "eyJjdXJzb3IiOlt7ImZpZWxkIjoiY3JlYXRlZF90aW1lIiwidmFsdWUiOiIyMDE4LTA2LTI4VDEyOjM4OjM0KzAwOjAwIiwib3JkZXIiOiJkZXNjIn1dLCJpZHMiOlsiMTc4OTM5NTExNjIyMTY0NjRfNDkwNDAyMjIwIl19=",
    "remaining": 15
  }
}

Aggregated Post Metrics

You can find this endpoint useful in case you want to get the aggregated metrics data of a set of posts. The set of posts is defined by the profiles and filtering parameters.

The set of posts is defined by the date range, the profiles, and the filtering parameters.

When requesting the data, the dimension of the data is required. Dimensions are common criteria that are used to aggregate data, such as the date on that the post has been published or the content label of the post.

You can use this endpoint to answer questions like: How many interactions (impressions, posts, reactions, etc.) relate to posts having a specific content label? How many interactions relate to a particular type of post? How many interactions were created by organic or paid posts?

Facebook Post Metrics

Required OAuth2 scope: 
api.read

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
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 list of profile IDs from the /1/facebook/profiles endpoint.
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.
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 that have insights_enabled property set to true in the response of the /1/facebook/profiles endpoint.

Name Dimensions Metrics Description
page_posts date.day
date.month
date.quarter
date.week
date.year
profile
post_labels
post_type
ppd_status
Number of page posts.
interactions date.day
date.month
date.quarter
date.week
date.year
profile
post_labels
post_type
ppd_status
interaction_type
Number of interactions on page posts.
insights_impressions date.day
date.month
date.quarter
date.week
date.year
profile
post_labels
post_type
The number of impressions for your posts.
reactions date.day
date.month
date.quarter
date.week
date.year
profile
post_labels
post_type
ppd_status
reaction_type
Number of reactions on page posts.
insights_video_views date.day
date.month
date.quarter
date.week
date.year
profile
post_labels
Number of times page's videos have been viewed for more than 3 seconds.
insights_post_clicks date.day
date.month
date.quarter
date.week
date.year
profile
post_labels
post_type
The number of times people clicked on anywhere in your posts without generating an activity.
insights_reach_engagement date.day
date.month
date.quarter
date.week
date.year
profile
post_labels
post_type
Reach Engagement Rate informs about the percentage of users who engaged with a post during its lifetime given its reach. Learn More.
Fields that might be used to filter Facebook posts:
Basic Fields

Example request

POST /1/metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "profiles": [
    {
      "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": [
        "164929129743"
      ]
    },
    {
      "type": "metric",
      "rows": [
        "page_posts"
      ]
    }
  ],
  "data": [
    [
      3
    ]
  ]
}

Aggregated Post Metrics

Required OAuth2 scope: 
api.read

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.

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.
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.

All LinkedIn and Pinterest metrics can only be used for profiles that have insights_enabled property set to true in the response of their respective /${apiVersion}/{network}/profiles endpoint.

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

Name Dimensions Aggregation Metrics Description
engagement_rate
FBIGTWYTLI
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type
published_status
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.
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
FBIGTWYT
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
media_type
content_type
sum Engagements inform about how many times users engaged with a post during its lifetime. Learn More.
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
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_post_saves
IG
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
media_type
content_type
sum Total number of saves on the posts.
insights_reach_engagement
FBIG
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type
published_status
avg Reach Engagement Rate informs about the percentage of users who engaged with a post during its lifetime given its reach. Learn More.
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
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
sum Number of times page's videos have been viewed for more than 3 seconds. For Instagram Reels number of plays are counted as video views. Plays are defined as video sessions with 1 ms + of playback, excluding replays.
interactions
FBIGTWYTLIPI
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type
published_status
interaction_type
sum Number of interactions on page posts. YouTube dislike count is no longer available for this metric as of December 13, 2021 Learn more.
interactions_per_1k_fans
FBIGTWYTLI
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 per 1k fans.
likes
FBIGTWYT
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
media_type
sum Number of likes of profile posts.
number_of_comments
FBIGTWYTLIPI
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 comments on page posts.
page_posts
FBIGTWYTLIPI
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 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
FBTWPI
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
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 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 /1/aggregated-metrics HTTPS
Host: api.emplifi.io
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"
      ]
    }
  ]
}

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 Emplifi API and use it as a source of data for your reports.

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

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

(Please note that name convention slightly differs on Emplifi’s side where ‘Token’ and ‘Secret’ is being used.
EXAMPLE of what you’ll use for input:
User Name: (called token on Emplifi side)
NjE5MTA4XzE3OTAyMTVfMTU0NTMxNDUyOTA4OV82MTRlODkxODAzNDI0ZmU5MTQwY2VkZTY4NzI2NmI1OA== (example only, not functional)
Token: (called secret on Emplifi 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

Community

Currently only content labeling endpoints are available for Community.

Content Labeling

Required OAuth2 scope: 
api.write

Add or remove labels to content in Community.

Requires labeling user permissions:

  • Apply Global Content Labels
  • Create and Edit Global Profile Labels, Content Labels and Label Groups

Currently supports the following networks: facebook, instagram, 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 /1/community/{network}/labels HTTPS
Host: api.emplifi.io
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"
      }
    }
  }
}

Changelog

v1.17 (2024/03/07)

  • /1/facebook/metrics
  • /1/facebook/page/posts
    • Facebook has updated deprecation list for several page and post metrics. (more info here).
    • The historical data will be available until June 11, 2024. After that, the API will return an invalid metric or dimension error.
      • No longer deprecated metrics:
        • insights_reactions
        • insights_reactions_by_type
      • Additional deprecated metrics:
        • insights_activity
        • insights_activity_by_activity_type
        • insights_activity_unique
        • insights_activity_unique_by_activity_type
        • insights_activity_unique_by_age_gender
        • insights_activity_unique_by_city
        • insights_activity_unique_by_country
        • insights_activity_unique_by_locale

v1.16 (2024/02/28)

  • /1/facebook/metrics
    • Facebook has deprecated several page metrics. (more info here).
    • The historical data will be available until June 11, 2024. After that, the API will return an invalid metric or dimension error.
      • Metrics:
        • insights_positive_feedback
        • insights_post_clicks
        • insights_post_clicks_by_type
        • insights_reach_engagement
        • insights_engaged_users
        • insights_reactions
        • insights_reactions_by_type

v1.15 (2023/08/24)

v1.14 (2023/01/12)

  • video_igtv media type is now merged together with the rest of the media_type=video content. As of October 5, 2021, Facebook has combined IGTV and feed videos into a single format - Instagram Video.
    • POST /1/aggregated-metrics will no longer return video_igtv as a separate bucket of media_type breakdown. Instead, it will include the results in the video bucket.

v1.13 (2022/10/26)

  • Socialbakers API is now Emplifi API.
    Read below for the list of changes that may affect you:
    • The Emplifi API documentation is now located on https://api.emplifi.io/. https://api.socialbakers.com/ automatically redirects here
    • All API calls should be sent to new hostname api.emplifi.io
    • For security reasons API calls to api.socialbakers.com are not going to be automatically redirected to api.emplifi.io. You should update the hostname of all of your calls
    • IMPORTANT Please note that API calls made to api.socialbakers.com will stop working on Jan 1st 2024

v1.12

  • Instagram Reels data is available and supported under dimension media_type='reel'. Affected endpoints:

v1.11

  • LinkedIn organic metrics now require connected LinkedIn Insights data connection instead of Publishing in order to return data

v1.10

v1.9

  • YouTube metrics have been updated to reflect the change of Dislikes count availability introduced by YouTube in December 13, 2021 Learn more. Affected are:
  • Requesting non-existing route will now ends up with HTTP status code 404 and JSON error response.
  • User rate limits for request count is not shared between accounts.

v1.8

v1.7

  • Tableau WDC connector v1 is no longer supported, please use latest version.

v1.6

  • /1/facebook/page/posts
    • insights_engagement_rate - no longer supported. We have introduced a new version of the Reach ER in the latest version of the API. This field will still be return for the time being.
  • /1/instagram/profile/posts
    • insights_engagement - no longer supported. We have introduced a new version of the Engagement in the latest version of the API. This field will still be return for the time being.
  • /1/aggregated-metrics
    • insights_engagement - YT Engagements is now supported under this field. Calculation for Facebook and Instagram engagements has been upgraded. Learn More
    • insights_reach_engagement - IG Reach ER is now supported under this field. Calculation for Facebook has been upgraded. Learn More
  • /1/metrics
    • insights_reach_engagement - Calculation for Facebook Aggregated metrics has been upgraded. Learn More

v1.5

  • IGTV data is available and supported under dimension media_type='video_igtv'
  • Affected endpoints:

v1.4

  • insights_video_views metric is now returning data also for Instagram Carousels with videos
  • v1.3

    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

    2021/06/16

    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

    Available versions

    Version Date Introduced Available Until
    v3 September 16, 2020 TBD
    v2 July 22, 2020 TBD
    v1 November 4, 2018 TBD
    v0 September 30, 2016 July 22, 2021