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 API access, please contact our Emplifi Sales representative.

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 /3/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/3/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/3/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: 100
  • Metrics: 25
  • Date range: 12 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, dimensions 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 /3/linkedin/metrics
POST /3/tiktok/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
14 POST /3/listening/metrics Listening queries not allowed for user 403
15 all Ad accounts not allowed for user 200
16 all Ad accounts have invalid tokens 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, LinkedIn, Pinterest, TikTok or Snapchat 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 /3/{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, linkedin, pinterest, tiktok, snapchat
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

              GET /3/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"
    },
    ...
  ]
}

List of Content Label Groups

Required OAuth2 scope: 
api.read

Each Content Label Group can have multiple Content Labels assigned to it. The endpoint returns the list of all private, global, and shared content label groups visible to your user in your account. These groups are identified by name and ID and each of them has an array of IDs of content labels that are assigned to the group.

In order to use this endpoint, you need to have a shared labels and label groups feature enabled in your account. Get in touch with customer support to do so, please.

Response fields

Name Description
id string, content label group unique identifier
name string, content label group name
label_ids array, list of IDs of content labels assigned to this group

Example request

              GET /3/post/label-groups HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
Example response
{
  "success": true,
  "data": [
    {
      "id": "138",
      "name": "Content Label Group 1",
      "label_ids": [
        "02782bb93ba340ef9330",
        "0134ebd3c6f44d888da5"
      ]
    },
    {
      "id": "241",
      "name": "Content Label Group 2",
      "label_ids": [
        "02782bb93ba340ef9330"
      ]
    },
    ...
  ]
}

List of Profile Labels

Required OAuth2 scope: 
api.read

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

Response fields

Name Description
id string, profile label unique identifier
name string, profile label name
profiles array, information about profile tagged with the specific profile label

Example request

            GET /3/profile/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": "Profile Label 1",
      "profiles": [
        {
          "name": "Profile 1",
          "platform": "facebook"
        },
        {
          "name": "Profile 2",
          "platform": "twitter"
        }
      ]
    },
    {
      "id": "ffc196eb056b42fd9b03",
      "name": "Profile Label 2",
      "profiles": [],
    },
    ...
  ]
}

List of Listening Queries

Required OAuth2 scope: 
api.read

Queries are keyword-based and they are defined by a name and one or more text-based conditions that specify what you want to monitor. The endpoint returns the list of all Listening queries visible to your user in your account, identified by a unique ID.

Response fields

Name Description
id string, Listening query unique identifier
name string, Listening query name
community_enabled boolean, true if community content is processed by the Listening query
status string, possible values are described in tables below

Status

Active queries
Status Description
Running The query is collecting data within the specified date range.
Scheduled The query will start collecting listening mentions on the scheduled date.
Regulated The query hit the annual mentions limit set for the query. The query is run again at the beginning of the next billing period.
Suspended The query isn’t collecting any data because of reaching the annual limit for the number of listening mentions. The data collection will be renewed at the beginning of the next billing period.
Inactive queries
Status Description
Paused The query was paused by the user and it isn’t collecting any listening mentions.
Done The query has reached the end date and it isn’t collecting any listening mentions.

Example request

            GET /3/listening/queries HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
Example response
{
  "success": true,
  "queries": [
    {
      "id": "LNQ_172196_6241c597857f917a0529975d",
      "name": "Listening Query 1",
      "community_enabled": false,
      "status": "Running",
    },
    {
      "id": "LNQ_172196_6241c5c4dbd2b023b9d97221",
      "name": "Listening Query 2",
      "community_enabled": true,
      "status": "Paused",
    },
    ...
  ]
}

List of Ad Accounts

Required OAuth2 scope: 
api.read

The endpoint returns the list of all Ad accounts available to your account and user in specified date range.

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.

Response fields

Name Description
id string, ad account unique identifier.
name string, ad account name.

Example request

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

{
  "date_start": "2021-01-01",
  "date_end": "2022-01-01"
}
Example response
{
  "success": true,
  "ad_accounts": [
    {
      "id": "640875043xxxxxx",
      "name": "Emplifi 1.0",
    },
    ...
  ]
}

Profile Metrics

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

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

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

Facebook Metrics

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 /3/facebook/profiles endpoint.
metrics array, the list of metrics that will be returned in the response. Available metrics are listed in the table below.
dimensions array of {type: dimensionType} objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimension types for each metric in the table below. Dimensions marked with an asterisk* must be last, and only one such dimension can be used.
Basic Metrics
Name Dimensions Aggregation Metric description
fans_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of fans count of a page.
fans_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of likes (=fans) of a page.
Insights Metrics

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

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

Example request

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

Example response


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

Instagram Metrics

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 /3/instagram/profiles endpoint.
metrics The list of metrics that will be returned in the response. Available metrics are listed in the table below.
dimensions array of {type: dimensionType} objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimension types for each metric in the table below. Dimensions marked with an asterisk* must be last, and only one such dimension can be used.
Basic Metrics
Name Dimensions Aggregation Metric description
followers_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of followers count lifetime.
followers_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of followed-by of a user by day. Number is aggregated to the midnight of profile timezone.
following_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of follows of a user by day. Number is aggregated to the midnight of profile timezone.
following_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of people profile follows.
Insights Metrics

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

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

Example request

POST /3/instagram/metrics HTTPS
Host: api.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_change"],
  "dimensions": [
    {
      "type": "date.day"
    }
  ]
}

Example response


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

Twitter Metrics

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 /3/twitter/profiles endpoint.
metrics The list of metrics that will be returned in the response. Available metrics are listed in the table below.
dimensions array of {type: dimensionType} objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimension types for each metric in the table below. Dimensions marked with an asterisk* must be last, and only one such dimension can be used.
Basic Metrics
Name Dimensions Aggregation Metric description
ff_ratio date.day,
date.month,
date.week,
profile,
profile_label 		avg Ratio of total followers and total following aggregated by day.
followers_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of followers (=fans) of a profile. Number is aggregated by day.
followers_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of followers (=fans) of a profile. Number is aggregated by day.
following_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of how many people profile follows. Number is aggregated by day.
following_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of how many people profile follows
listed_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of on how many lists profile appears.
listed_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total count of on how many lists profile appears.

Example request

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

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

Example response


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

YouTube Metrics

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 /3/youtube/profiles endpoint.
metrics The list of metrics that will be returned in the response. Available metrics are listed in the table below.
dimensions array of {type: dimensionType} objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimension types for each metric in the table below. Dimensions marked with an asterisk* must be last, and only one such dimension can be used.
Metrics
Name Dimensions Aggregation Metric Description
interaction_change date.day,
date.month,
date.week,
profile,
profile_label,
interaction_type* 		sum Daily growth of interactions on all uploaded videos by the channel on a given day. Number is aggregated by day to the midnight of UTC timezone. Dislike count is no longer available for this metric as of December 13, 2021 Learn more.
interactions_per_1k_fans date.day,
date.month,
date.week,
profile,
profile_label 		sum Daily growth of interactions per 1000 fans on all uploaded videos by the channel on a given day. Number is aggregated by day to the midnight of UTC timezone. Dislike count is no longer available for this metric as of December 13, 2021 Learn more.
subscribers_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of subscribers count lifetime.
subscribers_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of subscribers of the channel.
video_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of uploaded videos by the channel on a given day. Number is aggregated by day to the UTC midnight.
viewed_time_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute daily growth of viewed time. Number is aggregated by day to the midnight of UTC. All values are provided in seconds.
views_change date.day,
date.month,
date.week,
profile,
profile_label 		sum This is the absolute daily growth of views. Number is aggregated by day to the midnight of UTC timezone.

Example request

POST /3/youtube/metrics HTTPS
Host: api.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_change"],
  "dimensions": [
    {
      "type": "date.day"
    }
  ]
}

Example response

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

LinkedIn Metrics

Required OAuth2 scope: 
api.read

Returns daily metrics for each requested LinkedIn profile.

Parameters

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

Basic metrics for Linkedin profiles can be accessed only for profiles that have insights_enabled property set to true in the response of the /3/linkedin/profiles endpoint.

Name Dimensions Aggregation Metric Description
followers_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of followers of a company by day. Number is aggregated to the midnight of selected timezone.
followers_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of followers of a company by day. Number is aggregated to the midnight of selected timezone.
Insights metrics

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

Name Dimensions Aggregation Metric Description
insights_engagements date.day,
date.month,
date.week,
profile,
profile_label 		sum Engagements refers to the number of times that users engaged with your posts during the specified date range. Learn More.
insights_impressions date.day,
date.month,
date.week,
profile,
profile_label 		sum The total number of times any content associated with your page has been seen.
insights_impressions_engagement_rate date.day,
date.month,
date.week,
profile,
profile_label 		avg The number of impressions received by the content published on your page, divided by the number of people who have seen any content associated with your page. Learn More.
insights_post_clicks date.day,
date.month,
date.week,
profile,
profile_label 		sum The number of clicks on all the content published on your page.
insights_reach date.day,
date.month,
date.week,
profile,
profile_label 		avg The number of people who have seen any content associated with your page.
insights_reach_engagement_rate date.day,
date.month,
date.week,
profile,
profile_label 		avg The number of people who engaged with your page, divided by the number of people who have seen any content associated with your page. Learn More.

Example request

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

Example response

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

Pinterest Metrics

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 /3/pinterest/profiles endpoint.
metrics The list of metrics that will be returned in the response. Available metrics are listed in the table below.
dimensions array of {type: dimensionType} objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimension types for each metric in the table below. Dimensions marked with an asterisk* must be last, and only one such dimension can be used.
Metrics
Name Dimensions Aggregation Metric description
boards_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of number of profile boards. Number is aggregated by day.
boards_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of boards of the profile.
followers_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of followers of a profile.
followers_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of followers of the profile. Number is aggregated by day.
following_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Absolute change of followed profiles. Number is aggregated by day.
following_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of followed profiles.
pins_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		avg Total number of pins of the profile.

Example request

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

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

Example response


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

TikTok Metrics

Required OAuth2 scope: 
api.read

Returns daily metrics for each requested TikTok profile.

Parameters

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

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

Name Dimensions Aggregation Metric Description
insights_engagements date.day,
date.month,
date.week,
profile,
profile_label 		sum Engagements returns the number of times that users engaged with your posts during the specified date range. Learn more
insights_fans_change date.day,
date.month,
date.week,
profile,
profile_label 		sum Net growth of the total number of users who follow a profile.
insights_fans_lifetime date.day,
date.month,
date.week,
profile,
profile_label 		sum The total number of users who follow a profile.
insights_profile_views date.day,
date.month,
date.week,
profile,
profile_label 		sum Total number of users who have viewed the TikTok business account during the specific date range.
insights_video_views date.day,
date.month,
date.week,
profile,
profile_label 		sum Total number of times the TikTok profile videos have been viewed during the selected date range.

Example request

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

{
  "date_start": "2022-05-01",
  "date_end": "2022-05-02",
  "profiles": [
    "c3694e88-379a-4f3d-9942-acc7203f72e3"
  ],
  "metrics": ["insights_fans_change"],
  "dimensions": [
    {
      "type": "date.day"
    }
  ]
}

Example response

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

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

Pagination

These endpoints also supports pagination. You can only get up to a 100 posts per request. To get additional posts, you would need to make subsequent requests by only including the after parameter.

When the response contains remaining and next keys, more posts are available using pagination.

The key remaining contains the number of items that are available after the last item in the response.

To request the next page, send the parameter after set to value of the next key from the previous response.

Example request

			POST /3/linkedin/page/posts HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "profiles": ["urn:li:organization:2056516"],
  "date_start": "2020-01-15",
  "date_end": "2020-01-17",
  "fields": ["attachments", "comments"],
  "sort": [
    {
      "field": "comments",
      "order": "desc"
    }
  ],
  "limit": 1
}

Example response

			{
"success": true,
"data": {
    "posts": [
      {
        "attachments": [
          {
            "title": "2020 Vision: Marketers List Year's Top Priorities",
            "description": "What will be the top digital marketing trends in 2020? Emplifi gathered thoughts and priorities from marketers across the globe.",
            "url": "http://bit.ly/2TzpGXU",
            "image_url": "https://www.socialbakers.com/www/storage/www/articles/og-image/2019-12/1577440777-1552993065-og-blog__11tips.jpg",
            "type": "link"
          }
        ],
        "comments": 2
      }
    ],
    "next": "eyJxdWVyeSI6eyJmZWVkVHlwZSI6InVzZXJGZWVkIiwiZmllbGRzIjpbImF0dGFjaG1lbnRzIiwiY29tbWVudENvdW50Iiwib3JpZ2luIiwiYXV0aG9ySWQiLCJwcm9maWxlSWQiLCJtb25pdG9yZWRQcm9maWxlSWQiLCJzdG9yYWdlVHlwZSJdLCJmaWx0ZXJzIjpbeyJ0eXBlIjoib3IiLCJmaWx0ZXJzIjpbeyJ0eXBlIjoiYW5kIiwiZmlsdGVycyI6W3sidHlwZSI6ImNyZWF0ZWRUaW1lIiwicmFuZ2UiOnsiZnJvbSI6IjIwMjAtMDEtMTVUMDA6MDA6MDBaIiwidG8iOiIyMDIwLTAxLTE3VDIzOjU5OjU5WiJ9fSx7InR5cGUiOiJwcm9maWxlSWQiLCJwcm9maWxlcyI6W3sicHJvZmlsZUlkIjpbInVybjpsaTpvcmdhbml6YXRpb246MjA1NjUxNiJdLCJuZXR3b3JrIjoibGlua2VkaW4ifV19XX1dfSx7InR5cGUiOiJuZXR3b3JrIiwidmFsdWUiOlsiZmFjZWJvb2siLCJ0d2l0dGVyIiwicGludGVyZXN0IiwiaW5zdGFncmFtIiwieW91dHViZSIsInZrb250YWt0ZSIsImxpbmtlZGluIl19XSwic29ydCI6W3sidHlwZSI6ImNvbW1lbnRDb3VudCIsIm9yZGVyIjoiZGVzYyJ9LHsidHlwZSI6ImNyZWF0ZWRUaW1lIiwib3JkZXIiOiJkZXNjIn1dLCJsaW1pdCI6MSwiYWNjb3VudElkIjoiMTcyMTk2IiwidXNlcklkIjoiZDE5NTk5NTEiLCJ0b2dnbGVzIjpbIkNPTU1VTklUWV9TRVRfRE9ORV9BRlRFUl9SRVBMWSIsIkFOQUxZVElDU19NT0RVTEUiLCJBVURJRU5DRVNfVEVBU0lORyIsIlBVQkxJU0hfTU9EVUxFIiwiVE9LRU5fRkxPVyIsIkFEU19CRU5DSE1BUktTIiwiTElOS0VESU5fQ09NTVVOSVRZIiwiQVVUT01BVEVEX1NFTlRJTUVOVF9BQ0NFUFRFRCIsIkFEX0FDQ09VTlRTX1JPTEVTX1BFUk1JU1NJT05TIiwiQVBQUk9WQUxfRkxPVyIsIkFVVE9MQUJFTElORyIsIkRBU0hCT0FSRF9PTU5JX1dJREdFVFMiLCJGSUxFU1RBQ0tfRlVMTCIsIklOU1RBR1JBTV9BRFNfUFVCX0NPTSIsIklOU1RBR1JBTV9WSURFT19QVUJMSVNISU5HIiwiTElOS0VESU5fUFVCTElTSElORyIsIk1PQklMRV9DT01NVU5JVFlfTU9EVUxFIiwiQ09OVEVOVF9IVUJfTU9EVUxFIiwiUlVMRV9CQVNFRF9MQUJFTElORyIsIkNPTlRFTlRfSFVCX0NPTExFQ1RJT05TIiwiUEFJRF9NT0RVTEUiLCJQVUJMSVNIRVJfRVhURVJOQUwiLCJUV19JTlNJR0hUUyIsIkNPTU1VTklUWV9NT0RVTEUiLCJBRFNfQkVOQ0hNQVJLU19GVUxMX0FDQ0VTUyIsIkJFTkNITUFSS1NfTVVMVElDT01QQVJFIiwiQ0FNUEFJR05fVklFVyIsIkNPTlRFTlRfU0VBUkNIX1BSTyIsIkRBU0hCT0FSRF9NT0RVTEUiLCJHT09HTEVfQU5BTFlUSUNTIiwiTElTVEVOSU5HIiwiTElWRV9WSURFT19NRVRSSUNTIiwiUEFJRF9QT1NUX0RFVEVDVElPTiIsIlBBSURfUE9TVF9ERVRFQ1RJT05fSUciLCJQT1NUX0JPT1NUSU5HIiwiUFJJTUVUSU1FIiwiVklERU9fQkVOQ0hNQVJLU19GVUxMX0FDQ0VTUyIsIkJVU0lORVNTX1RPR0dMRV9QVUJMSVNIRVJfSUdfVVNFUlNfVEFHR0lORyIsIklORkxVRU5DRVJTX01PRFVMRSIsIlBFUk1JU1NJT05TX0JZX1NFQ1RJT05TIiwiQlVTSU5FU1NfVE9HR0xFX1NUT1JJRVNfU0NIRURVTElORyIsIkJVU0lORVNTX1RPR0dMRV9BU1RVVEVfSU5URUdSQVRJT04iLCJCVVNJTkVTU19UT0dHTEVfTElOS0VESU5fVEFSR0VUSU5HIiwiQlVTSU5FU1NfVE9HR0xFX1BVQkxJU0hFUl9JR19MT0NBVElPTl9UQUdHSU5HIiwiQ09OVEVOVF9QUkVESUNUSU9OIiwiQ09OVEVOVF9QUkVESUNUSU9OX0lHIiwiUFVCTElTSEVSX0ZCX1NDSEVEVUxJTkciLCJCVVNJTkVTU19UT0dHTEVfUFVCTElDX0RBU0hCT0FSRCIsIkVOR0FHRU1FTlRfUkFURV9FU1RFX0xBVURFUiIsIkNPTlRFTlRfU0VOVElNRU5UIiwiQVVUT01BVEVEX1NFTlRJTUVOVCIsIkJVU0lORVNTX1RPR0dMRV9PUkdBTklDX0FOQUxZVElDUyIsIkJVU0lORVNTX1RPR0dMRV9MSVNURU5JTkdfTU9EVUxFIiwiQlVTSU5FU1NfVE9HR0xFX0lHX09SR0FOSUNfUEFJRF9SRU1PVkFMX0lOVEVSSU0iLCJCVVNJTkVTU19UT0dHTEVfSUdfT1JHQU5JQ19QQUlEX1JFTU9WQUxfRklOQUwiLCJCRVRBX01PQklMRV9DT01NVU5JVFlfTU9EVUxFIiwiQVVESUVOQ0VTX01PRFVMRSIsIkJVU0lORVNTX1RPR0dMRV9DT01NVU5JVFlfUkVQT1JUSU5HIiwiU1VJVEVfQURTIiwiQlVTSU5FU1NfVE9HR0xFX1BBSURfU1RPUkVEX0RBVEEiLCJCVVNJTkVTU19UT0dHTEVfUFJJT1JJVFlfU0NPUkUiLCJJTkZMVUVOQ0VSU19GVUxMX0FDQ0VTUyJdLCJwcm9maWxlcyI6W3sicHJvZmlsZUlkIjpbInVybjpsaTpvcmdhbml6YXRpb246MjA1NjUxNiJdLCJuZXR3b3JrIjoibGlua2VkaW4iLCJ0aW1lem9uZSI6IlVUQyIsImluc2lnaHRzIjpmYWxzZSwibWFuYWdlZCI6ZmFsc2UsImluc3RhZ3JhbVRva2VuIjpmYWxzZSwiaXNBdXRvU2VudGltZW50RW5hYmxlZCI6dHJ1ZSwiaW5mbHVlbmNlckluc2lnaHRzIjpmYWxzZX1dLCJjcmVhdGVkVGltZSI6eyJmcm9tIjoiMjAyMC0wMS0xNVQwMDowMDowMFoiLCJ0byI6IjIwMjAtMDEtMTdUMjM6NTk6NTlaIn19LCJjdXJzb3IiOnsic29ydCI6W3sidHlwZSI6ImNvbW1lbnRDb3VudCIsInZhbHVlIjoyLCJvcmRlciI6ImRlc2MifSx7InR5cGUiOiJjcmVhdGVkVGltZSIsInZhbHVlIjoxNTc5MjY4MjYxMDAwLCJvcmRlciI6ImRlc2MifV0sImxhc3RTb3J0SGFzaCI6Iis5MDA3MTk5MjU0NzQwOTkwXys5MDA1NjE5OTg2NDc5OTkyIiwiaWRzIjpbInVybjpsaTpzaGFyZTo2NjIzOTMxMTg1NDE0MzI4MzIwIl19LCJ0b3RhbCI6OCwic2Nyb2xsQ291bnQiOjEsInNjcm9sbGVkQ291bnQiOjF9",
    "remaining": 7
  }
}

Next page request

			POST /3/linkedin/page/posts HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "after": "eyJxdWVyeSI6eyJmZWVkVHlwZSI6InVzZXJGZWVkIiwiZmllbGRzIjpbImF0dGFjaG1lbnRzIiwiY29tbWVudENvdW50Iiwib3JpZ2luIiwiYXV0aG9ySWQiLCJwcm9maWxlSWQiLCJtb25pdG9yZWRQcm9maWxlSWQiLCJzdG9yYWdlVHlwZSJdLCJmaWx0ZXJzIjpbeyJ0eXBlIjoib3IiLCJmaWx0ZXJzIjpbeyJ0eXBlIjoiYW5kIiwiZmlsdGVycyI6W3sidHlwZSI6ImNyZWF0ZWRUaW1lIiwicmFuZ2UiOnsiZnJvbSI6IjIwMjAtMDEtMTVUMDA6MDA6MDBaIiwidG8iOiIyMDIwLTAxLTE3VDIzOjU5OjU5WiJ9fSx7InR5cGUiOiJwcm9maWxlSWQiLCJwcm9maWxlcyI6W3sicHJvZmlsZUlkIjpbInVybjpsaTpvcmdhbml6YXRpb246MjA1NjUxNiJdLCJuZXR3b3JrIjoibGlua2VkaW4ifV19XX1dfSx7InR5cGUiOiJuZXR3b3JrIiwidmFsdWUiOlsiZmFjZWJvb2siLCJ0d2l0dGVyIiwicGludGVyZXN0IiwiaW5zdGFncmFtIiwieW91dHViZSIsInZrb250YWt0ZSIsImxpbmtlZGluIl19XSwic29ydCI6W3sidHlwZSI6ImNvbW1lbnRDb3VudCIsIm9yZGVyIjoiZGVzYyJ9LHsidHlwZSI6ImNyZWF0ZWRUaW1lIiwib3JkZXIiOiJkZXNjIn1dLCJsaW1pdCI6MSwiYWNjb3VudElkIjoiMTcyMTk2IiwidXNlcklkIjoiZDE5NTk5NTEiLCJ0b2dnbGVzIjpbIkNPTU1VTklUWV9TRVRfRE9ORV9BRlRFUl9SRVBMWSIsIkFOQUxZVElDU19NT0RVTEUiLCJBVURJRU5DRVNfVEVBU0lORyIsIlBVQkxJU0hfTU9EVUxFIiwiVE9LRU5fRkxPVyIsIkFEU19CRU5DSE1BUktTIiwiTElOS0VESU5fQ09NTVVOSVRZIiwiQVVUT01BVEVEX1NFTlRJTUVOVF9BQ0NFUFRFRCIsIkFEX0FDQ09VTlRTX1JPTEVTX1BFUk1JU1NJT05TIiwiQVBQUk9WQUxfRkxPVyIsIkFVVE9MQUJFTElORyIsIkRBU0hCT0FSRF9PTU5JX1dJREdFVFMiLCJGSUxFU1RBQ0tfRlVMTCIsIklOU1RBR1JBTV9BRFNfUFVCX0NPTSIsIklOU1RBR1JBTV9WSURFT19QVUJMSVNISU5HIiwiTElOS0VESU5fUFVCTElTSElORyIsIk1PQklMRV9DT01NVU5JVFlfTU9EVUxFIiwiQ09OVEVOVF9IVUJfTU9EVUxFIiwiUlVMRV9CQVNFRF9MQUJFTElORyIsIkNPTlRFTlRfSFVCX0NPTExFQ1RJT05TIiwiUEFJRF9NT0RVTEUiLCJQVUJMSVNIRVJfRVhURVJOQUwiLCJUV19JTlNJR0hUUyIsIkNPTU1VTklUWV9NT0RVTEUiLCJBRFNfQkVOQ0hNQVJLU19GVUxMX0FDQ0VTUyIsIkJFTkNITUFSS1NfTVVMVElDT01QQVJFIiwiQ0FNUEFJR05fVklFVyIsIkNPTlRFTlRfU0VBUkNIX1BSTyIsIkRBU0hCT0FSRF9NT0RVTEUiLCJHT09HTEVfQU5BTFlUSUNTIiwiTElTVEVOSU5HIiwiTElWRV9WSURFT19NRVRSSUNTIiwiUEFJRF9QT1NUX0RFVEVDVElPTiIsIlBBSURfUE9TVF9ERVRFQ1RJT05fSUciLCJQT1NUX0JPT1NUSU5HIiwiUFJJTUVUSU1FIiwiVklERU9fQkVOQ0hNQVJLU19GVUxMX0FDQ0VTUyIsIkJVU0lORVNTX1RPR0dMRV9QVUJMSVNIRVJfSUdfVVNFUlNfVEFHR0lORyIsIklORkxVRU5DRVJTX01PRFVMRSIsIlBFUk1JU1NJT05TX0JZX1NFQ1RJT05TIiwiQlVTSU5FU1NfVE9HR0xFX1NUT1JJRVNfU0NIRURVTElORyIsIkJVU0lORVNTX1RPR0dMRV9BU1RVVEVfSU5URUdSQVRJT04iLCJCVVNJTkVTU19UT0dHTEVfTElOS0VESU5fVEFSR0VUSU5HIiwiQlVTSU5FU1NfVE9HR0xFX1BVQkxJU0hFUl9JR19MT0NBVElPTl9UQUdHSU5HIiwiQ09OVEVOVF9QUkVESUNUSU9OIiwiQ09OVEVOVF9QUkVESUNUSU9OX0lHIiwiUFVCTElTSEVSX0ZCX1NDSEVEVUxJTkciLCJCVVNJTkVTU19UT0dHTEVfUFVCTElDX0RBU0hCT0FSRCIsIkVOR0FHRU1FTlRfUkFURV9FU1RFX0xBVURFUiIsIkNPTlRFTlRfU0VOVElNRU5UIiwiQVVUT01BVEVEX1NFTlRJTUVOVCIsIkJVU0lORVNTX1RPR0dMRV9PUkdBTklDX0FOQUxZVElDUyIsIkJVU0lORVNTX1RPR0dMRV9MSVNURU5JTkdfTU9EVUxFIiwiQlVTSU5FU1NfVE9HR0xFX0lHX09SR0FOSUNfUEFJRF9SRU1PVkFMX0lOVEVSSU0iLCJCVVNJTkVTU19UT0dHTEVfSUdfT1JHQU5JQ19QQUlEX1JFTU9WQUxfRklOQUwiLCJCRVRBX01PQklMRV9DT01NVU5JVFlfTU9EVUxFIiwiQVVESUVOQ0VTX01PRFVMRSIsIkJVU0lORVNTX1RPR0dMRV9DT01NVU5JVFlfUkVQT1JUSU5HIiwiU1VJVEVfQURTIiwiQlVTSU5FU1NfVE9HR0xFX1BBSURfU1RPUkVEX0RBVEEiLCJCVVNJTkVTU19UT0dHTEVfUFJJT1JJVFlfU0NPUkUiLCJJTkZMVUVOQ0VSU19GVUxMX0FDQ0VTUyJdLCJwcm9maWxlcyI6W3sicHJvZmlsZUlkIjpbInVybjpsaTpvcmdhbml6YXRpb246MjA1NjUxNiJdLCJuZXR3b3JrIjoibGlua2VkaW4iLCJ0aW1lem9uZSI6IlVUQyIsImluc2lnaHRzIjpmYWxzZSwibWFuYWdlZCI6ZmFsc2UsImluc3RhZ3JhbVRva2VuIjpmYWxzZSwiaXNBdXRvU2VudGltZW50RW5hYmxlZCI6dHJ1ZSwiaW5mbHVlbmNlckluc2lnaHRzIjpmYWxzZX1dLCJjcmVhdGVkVGltZSI6eyJmcm9tIjoiMjAyMC0wMS0xNVQwMDowMDowMFoiLCJ0byI6IjIwMjAtMDEtMTdUMjM6NTk6NTlaIn19LCJjdXJzb3IiOnsic29ydCI6W3sidHlwZSI6ImNvbW1lbnRDb3VudCIsInZhbHVlIjoyLCJvcmRlciI6ImRlc2MifSx7InR5cGUiOiJjcmVhdGVkVGltZSIsInZhbHVlIjoxNTc5MjY4MjYxMDAwLCJvcmRlciI6ImRlc2MifV0sImxhc3RTb3J0SGFzaCI6Iis5MDA3MTk5MjU0NzQwOTkwXys5MDA1NjE5OTg2NDc5OTkyIiwiaWRzIjpbInVybjpsaTpzaGFyZTo2NjIzOTMxMTg1NDE0MzI4MzIwIl19LCJ0b3RhbCI6OCwic2Nyb2xsQ291bnQiOjEsInNjcm9sbGVkQ291bnQiOjF9"
}

Facebook Posts

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 /3/facebook/profiles endpoint.
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. Your request is transformed using the time zone assigned to a profile in the Suite settings of your account. The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct timezone using the timezone of each individual profile from the /3/facebook/profiles endpoint. The last day will be also included in the response.
fields array, the list of fields that will be returned in the response. Available fields are listed in the table below.
limit integer, (optional). The number of results per page. The default value is 10 and the maximal value is 100.
sort (optional), 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 (optional), You can filter results by providing the filter parameter with field and value. See the list of fields allowed for filtering.

Parameter for Pagination

after string, value of the next property from previous response.
Basic Fields
Name Type Example Description
attachments array 
[{ "title": "Know Where You Stand on Social Media", "description": "Get a free customized report that will provide you with detailed data insights showing you where you stand vereses your competition on Facebook. Try it now! ", "url": "https://goo.gl/AtTi93", "image_url": "https://external.xx.fbcdn.net/safe_image.php?d=AQCXbmZ491Pwd29M&url=https%3A%2F%2Fcdn.socialbakers.com%2Fwww%2Fstorage%2Fmicrosites%2Fkyn%2FOG-KYN.jpg", "type": "photo"}]
 Details about post attachments.
author object 
{ "id": "164929129743", "name": "Socialbakers", "url": "https://www.facebook.com/socialbakers"}
 Author details of the post.
authorId string 
164929129743
 The id of the post author.
comments integer 
15
 Total number of comments.
comments_sentiment object 
{ "positive": 4, "neutral": 5, "negative": 1 }
 Total sentiment for the comments of the post. Sum of sentiment breakdown might not equal the total comments. There would be comments which sentiment are either unassigned or undetected. For stories, this value is undefined since users can not comment on them.
content string 
Today is #InternationalBeerDay🍻
 Content of the Facebook post.
content_type string 
post|shared
 Content type of the Facebook post.
created_time datetime 
2016-10-24T16:15:04+00:00
 Date and time the post was created in Facebook.
deleted boolean 
true
 Describes if the post has been deleted on Facebook.
grade string 
C
 Grade score of the post.
hidden boolean 
false
 Describes if the post has been hidden from Facebook.
id string 
164929129743_10154702368914744
 Facebook post id.
interactions integer 
32
 Sum of reactions, comments and shares.
interactions_per_1k_fans float 
0.12
 Interaction count for every 1000 fans.
media_type string 
status|link|video|note|poll|carousel|animated_gif|album|offer|photo|reel
 Type of Facebook post.
origin string 
User-Generated Content|Brand's Content
 Source of post.
page object 
{ "id": "164929129743", "name": "Socialbakers", "url": "https://www.facebook.com/socialbakers" }
 Information about the Facebook page.
post_attribution object 
{ "status": "paid", "type": "ppd" }
 Type of post whether it's organic or paid. For posts from a profile with insights connected, data comes directly from Facebook. For the rest of the posts, the attribution is based on Socialbakers Paid Post Detection algorithm.
post_labels array 
[{ "id": "2a8545bcc98b48d1a0c4", "name": "label A"}]
 Content labels (formally post labels) assigned to the post.
profileId string 
461245129743
 The id of the Facebook page.
published boolean 
true
 Describes if the post is published.
reactions integer 
15
 Total number of reactions.
reactions_by_type object 
{"like": 8, "love": 0, "wow": 0, "haha": 0, "sorry": 0, "anger": 0}
 Breakdown of reactions.
sentiment string 
neutral
 Facebook page post sentiment.
shares integer 
15
 Number of times the post has been shared.
spam boolean 
false
 Describes if the post has been marked as spam.
universal_video_id integer 
15
 The publishers asset management code for this video. Only available in case the post type is a video.
url string 
https://www.facebook.com/657747477695267/posts/2037994753003859
 Link to the Facebook post.
video object 
{"id": "4200898453277020", "length": 16, "crosspost": false, "crosspostable": false, "live": false, "shared": false}
 Details about the post's video.
Insights Fields

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

Name Type Example Description
insights_engaged_users integer 
100
 The number of people who clicked anywhere in your posts
insights_engagements integer 
100
 Engagements inform about how many times users engaged with a post during its lifetime. Learn More.
insights_impressions integer 
100
 The number of impressions for your post.
insights_impressions_by_post_attribution object 
{ "paid": 0, "organic": 34, "viral": 10 }
 The number of impressions broken down by post attribution.
insights_impressions_engagement_rate float 
0.34
 Impressions Engagement Rate informs about the percentage of users who engaged with a post during its lifetime given its impressions. Learn More.
insights_interactions integer 
100
 Sum of reactions, comments and shares.
insights_interactions_by_interaction_type object 
{ "comments": 0, "reactions": 5, "shares": 3 }
 Count of reactions, comments and shares.
insights_negative_feedback_unique integer 
20
 The number of people who took a negative action in your post (hid it, for example)
insights_post_clicks integer 
12
 The number of times people clicked on anywhere in your posts without generating an activity.
insights_post_clicks_by_clicks_type object 
{ "link_clicks": null, "button_clicks": 4, "other_clicks": 22, "photo_views": null, "video_plays": 6 }
 The number of times people clicked on anywhere in your posts without generating an activity.
insights_post_clicks_unique integer 
10
 The number of people who clicked anywhere in your post without generating an activity.
insights_reach integer 
100
 The number of people who saw your post.
insights_reach_by_post_attribution object 
{ "paid": 100, "organic": 0, "viral": 0 }
 The number of people who saw your post.
insights_reach_engagement_rate float 
0.34
 Reach Engagement Rate informs about the percentage of users who engaged with a post during its lifetime given its reach. Learn More.
insights_reactions integer 
100
 Total reactions.
insights_reactions_by_type object 
{ "anger": 1, "haha": null, "like": 3, "love": 10, "sorry": null, "wow": 1 }
 Breakdown of reactions.
insights_video_view_time integer 
2657
 The total number of seconds your video was watched, including replays and views less than 3 seconds.
insights_video_view_time_average float 
125.7
 The average length in seconds people spent watching your video.
insights_video_view_time_by_country object 
{ "United States": 345, "Czech Republic": 1076 }
 The total number of seconds your video was watched, including replays and views less than 3 seconds.
insights_video_view_time_by_distribution object 
{ "owned": 234, "shared": 125 }
 The total number of seconds your video was watched, including replays and views less than 3 seconds.
insights_video_view_time_by_gender_age object 
{ "U.55-64": 10746, "M.55-64": 313915, "F.35-44": 186910 }
 The total number of seconds your video was watched, including replays and views less than 3 seconds.
insights_video_view_time_by_post_attribution object 
{ "organic": 12, "paid": 5 }
 The total number of seconds your video was watched, including replays and views less than 3 seconds.
insights_video_views integer 
35
 The number of times your video was watched for an aggregate of at least 3 seconds, or for nearly its total length, whichever happened first.
insights_video_views_10s integer 
125
 The number of times your video has been viewed for more than 10 seconds.
insights_video_views_10s_by_play_type object 
{ "autoplayed": 5, "click_to_play": 5 }
 The number of times your video has been viewed for more than 10 seconds.
insights_video_views_10s_by_post_attribution object 
{ "organic": 5, "paid": 10 }
 The number of times your video has been viewed for more than 10 seconds.
insights_video_views_10s_by_sound object 
{ "on": 10, "off": 4 }
 The number of times your video has been viewed for more than 10 seconds.
insights_video_views_10s_unique integer 
20
 The number of people who have watched your video for at least 10 seconds.
insights_video_views_30s integer 
30
 The number of times your video has been viewed for more than 30 seconds.
insights_video_views_30s_by_play_type object 
{ "autoplayed": 12, "click_to_play": 2 }
 The number of times your video has been viewed for more than 30 seconds.
insights_video_views_30s_by_post_attribution object 
{ "organic": 12, "paid": 4 }
 The number of times your video has been viewed for more than 30 seconds.
insights_video_views_30s_unique integer 
30
 The number of people who have watched your video for at least 30 seconds.
insights_video_views_average_completion float 
350.34
 The average percentage of a video watched during a video playback collected during the lifetime of the video.
insights_video_views_by_play_type object 
{ "autoplayed": 10, "click_to_play": 2 }
 The number of times your video was watched for an aggregate of at least 3 seconds, or for nearly its total length, whichever happened first.
insights_video_views_by_post_attribution object 
{ "organic": 10, "paid": 2 }
 The number of times your video was watched for an aggregate of at least 3 seconds, or for nearly its total length, whichever happened first.
insights_video_views_by_sound object 
{ "on": 12, "off": 5 }
 The number of times your video was watched for an aggregate of at least 3 seconds, or for nearly its total length, whichever happened first.
insights_video_views_complete integer 
10
 The number of times your video has been viewed for about 95% of its length.
insights_video_views_complete_by_post_attribution object 
{ "organic": 12, "paid": 4 }
 The number of times your video has been viewed for about 95% of its length.
insights_video_views_complete_unique integer 
12
 The number of people who have watched your video for about 95% of its length.
insights_video_views_complete_unique_by_post_attribution object 
{ "organic": 12, "paid": 5 }
 The number of people who have watched your video for about 95% of its length.
insights_video_views_distribution object 
{ "owned": 5, "shared": 10 }
 The number of times your video was watched for an aggregate of at least 3 seconds, or for nearly its total length, whichever happened first.
insights_video_views_unique integer 
13
 The number of people who have watched your video for at least 3 seconds.
insights_video_views_unique_by_post_attribution object 
{ "organic": 12, "paid": 5 }
 The number of people who have watched your video for at least 3 seconds.

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

Fields that might be used to filter Facebook posts:
Field Allowed values Description Advanced filter support
content_type post
shared		 Content type of the Facebook post. ✅ Supported operators:
  • match_any
grade A+
A
B
C
D		 Grade score of the post. ✅ Supported operators:
  • match_any
media_type status
link
video
note
poll
offer
photo
carousel
reel		 Type of Facebook post. ✅ Supported operators:
  • match_any
origin User-Generated Content
Brand's Content		 Source of post. ✅ Supported operators:
  • match_any
post_attribution organic
paid		 Type of post whether it's organic or paid. For posts from a profile with insights connected, data comes directly from Facebook. For the rest of the posts, the attribution is based on Socialbakers Paid Post Detection algorithm. ✅ Supported operators:
  • match_any
post_labels *
Pattern: .+		 Content labels (formally post labels) assigned to the post. ✅ Supported operators:
  • match_all
  • match_any
video_type crosspost
crosspostable
live
shared		 Filter results by specific video types, an attribute of Facebook that belongs only to Facebook Video. Filter by Shared, Crosspost (Videos that have been reused from another profile), Crosspostable (Videos that have been made available for crossposting by their owner) and Live videos. ✅ Supported operators:
  • match_any

Response

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

Example request

POST /3/facebook/page/posts HTTPS
Host: api.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",
    "author",
    "content_type",
    "hidden",
    "media_type",
    "post_attribution",
    "post_labels"
  ],
  "sort": [
    {
      "field": "created_time",
      "order": "desc"
    }
  ],
  "filter": [
    {
      "field": "post_attribution",
      "value": "organic"
    }
  ],
  "limit": 5
}

Example response

{
  "success": true,
  "data": {
    "posts": [
      {
        "id": "164929129743_10155892118379744",
        "created_time": "2017-10-25T16:06:00+00:00",
        "author": {
          "id": "164929129743",
          "name": "Socialbakers",
          "url": "https://www.facebook.com/socialbakers"
        },
        "content_type": "post",
        "hidden": false,
        "media_type": "link",
        "post_attribution": {
          "status": "organic",
          "type": "insights"
        },
        "post_labels": []
      }
    ],
    "next": "eyJuZXh0IjoiZXlKeGRXVnllU0k2ZXlKbVpXVmtWSGx3WlNJNkluVnpaWEpHWldWa0lpd2labWxsYkdSeklqcGJJbWxrSWl3aVkzSmxZWFJsWkZScGJXVWlMQ0poZFhSb2IzSkpibVp2SWl3aVkyOXVQ==",
    "remaining": 194
  }
}

Instagram Posts

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 /3/instagram/profiles endpoint.
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. Your request is transformed using the time zone assigned to a profile in the Suite settings of your account. The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct timezone using the timezone of each individual profile from the /3/instagram/profiles endpoint. The last day will be also included in the response.
fields array, the list of fields that will be returned in the response. Available fields are listed in the table below.
limit integer, (optional). The number of results per page. The default value is 10 and the maximal value is 100.
sort (optional), 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 (optional), You can filter results by providing the filter parameter with field and value. See the list of fields allowed for filtering.

Parameter for Pagination

after string, value of the next property from previous response.
Basic Fields
Name Type Example Description
attachments array 
[{ "image_url": "https://scontent-sea1-1.cdninstagram.com/v/t51.2885-15/65870902_147436403025286_4108244888990266821_n.jpg?_nc_cat=109&_nc_sid=8ae9d6&_nc_ohc=DJ0kCnsbf5QAX_acZuB&_nc_ht=scontent-sea1-1.cdninstagram.com&oh=bd44242c1ef473f8efff17f285dc5c86&oe=5F003D93", "type": "photo" }]
 Details about post attachments.
author object 
{"id": "490402220", "name": "Socialbakers", "url": "https://instagram.com/socialbakers"}
 Author details of the post.
authorId string 
164929129743
 The id of the post author.
comments integer 
15
 Total number of comments.
comments_sentiment object 
{ "positive": 1, "neutral": 5, "negative": 1 }
 Total sentiment for the comments of the post. Sum of sentiment breakdown might not equal the total comments. There would be comments which sentiment are either unassigned or undetected. For stories, this value is undefined since users can not comment on them.
content string 
Do you know which age groups and genders are most likely to follow a brand page on 📸#Instagram?
 Content of the Instagram post.
content_type string 
post|story
 Content type of the Instagram post.
created_time datetime 
2016-10-24T16:15:04+00:00
 Date and time the post was created in Instagram.
grade string 
C
 Grade score of the post.
id string 
17966172199068623_490402220
 Instagram post or story id.
interactions integer 
10
 Sum of reactions and comments.
interactions_per_1k_fans float 
0.12
 Interaction count for every 1000 fans.
likes integer 
45
 Total number of likes.
media_type string 
video|photo|carousel|video_igtv|reel
 Type of Instagram post.
origin string 
User-Generated Content|Brand's Content
 Source of post.
page object 
{ "id": "490402220", "name": "Socialbakers", "url": "https://instagram.com/socialbakers" }
 Information about the Instagram profile.
post_attribution object 
{ "status": "organic", "type": "insights" }
 Type of post whether it's organic or paid. For posts from a profile with insights connected, data comes directly from Instagram. For the rest of the posts, the attribution is based on Socialbakers Paid Post Detection algorithm.
post_labels array 
[{ "id": "2a8545bcc98b48d1a0c4", "name": "label A"}]
 Content labels (formally post labels) assigned to the post.
profileId string 
490402220
 The id of the Instagram page.
sentiment string 
neutral
 Instagram post sentiment.
url string 
https://instagram.com/stories/socialbakers/2342286418084049209
 Link to the Instagram post.
Insights Fields

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

Name Type Example Description
insights_engagement integer 
100
 Engagements inform about how many times users engaged with a post during its lifetime. Learn More.
insights_engagement_by_engagement_type object 
{ "comments": 0, "likes": 5, "saves": 10 }
 Breakdown of insights_engagement.
insights_impressions integer 
100
 The number of impressions for your post.
insights_impressions_engagement_rate float 
0.34
 Impressions Engagement Rate informs about the percentage of users who engaged with a post during its lifetime given its impressions. Learn More.
insights_reach integer 
100
 Number of people who saw your post.
insights_reach_engagement_rate float 
0.34
 Reach Engagement Rate informs about the percentage of users who engaged with a post during its lifetime given its reach. Learn More.
insights_saves integer 
12
 Number of unique accounts that saved your post.
insights_story_completion_rate float 
0.42
 The percentage of times a story impression was not interrupted by an exit, tap back, or tap forward.
insights_story_exits integer 
15
 The number of times users exited your story.
insights_story_replies integer 
1
 The number of times users replied to your story.
insights_story_taps_back integer 
87
 The number of times users clicked back to return to the previous story.
insights_story_taps_forward integer 
11
 The number of times users clicked forward to skip to the next story.
insights_video_views integer 
768
 Total number of times your video has been seen. For Instagram Reels number of plays are counted as video views. Plays are defined as video sessions with 1 ms + of playback, excluding replays.

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

Fields that might be used to filter Instagram posts:
Field Allowed values Description Advanced filter support
content_type post
story		 Content type of the Instagram post. ✅ Supported operators:
  • match_any
grade A+
A
B
C
D		 Grade score of the post. ✅ Supported operators:
  • match_any
media_type video
photo
carousel
video_igtv
reel		 Type of Instagram post. ✅ Supported operators:
  • match_any
origin User-Generated Content
Brand's Content		 Source of post. ✅ Supported operators:
  • match_any
post_attribution organic
paid		 Type of post whether it's organic or paid. For posts from a profile with insights connected, data comes directly from Instagram. For the rest of the posts, the attribution is based on Socialbakers Paid Post Detection algorithm. ✅ Supported operators:
  • match_any
post_labels *
Pattern: .+		 Content labels (formally post labels) assigned to the post. ✅ Supported operators:
  • match_all
  • match_any

Response

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

Example request

POST /3/instagram/profile/posts HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "profiles": ["490402220", "55674325"],
  "date_start": "2020-06-01",
  "date_end": "2020-08-31",
  "fields": [
    "id",
    "created_time",
    "author",
    "content_type",
    "media_type",
    "post_attribution",
    "post_labels"
  ],
  "sort": [
    {
      "field": "created_time",
      "order": "desc"
    }
  ],
  "filter": [
    {
      "field": "media_type",
      "value": "photo"
    }
  ],
  "limit": 1
}

Example response

{
  "success": true,
  "data": {
    "posts": [
      {
        "id": "17966172199068623_490402220",
        "created_time": "2020-06-25T16:06:00+00:00",
        "author": {
          "id": "490402220",
          "name": "Socialbakers",
          "url": "https://www.instagram.com/socialbakers"
        },
        "content_type": "post",
        "media_type": "photo",
        "post_attribution": {
          "status": "organic",
          "type": "insights"
        },
        "post_labels": []
      }
    ]
  }
}

YouTube Videos

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 /3/youtube/profiles endpoint.
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. Your request is transformed using the time zone assigned to a profile in the Suite settings of your account. The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct timezone using the timezone of each individual profile from the /3/youtube/profiles endpoint. The last day will be also included in the response.
fields array, the list of fields that will be returned in the response. Available fields are listed in the table below.
limit integer, (optional). The number of results per page. The default value is 10 and the maximal value is 100.
sort (optional), 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 (optional), You can filter results by providing the filter parameter with field and value. See the list of fields allowed for filtering.

Parameter for Pagination

after string, value of the next property from previous response.
Basic Fields
Name Type Example Description
author object 
{"id": "UCA6AG33Zac0xi6f9VMTxkFQ","name": "Socialbakers","url": "https://www.youtube.com/channel/UCA6AG33Zac0xi6f9VMTxkFQ"}
 Author details of the video.
authorId string 
UCA6AG33Zac0xi6f9VMTxkFQ
 The id of the video author.
channel object 
{"id": "UCA6AG33Zac0xi6f9VMTxkFQ","name": "Socialbakers","url": "https://www.youtube.com/channel/UCA6AG33Zac0xi6f9VMTxkFQ"}
 Information about the Youtube channel.
comments integer 
42
 Total number of comments.
created_time datetime 
2018-09-03T16:15:04+00:00
 Date and time the video was uploaded on Youtube.
description string 
Today is #InternationalBeerDay🍻
 Description of the Youtube video.
dislikes integer 
42
 Number of dislikes for the video. Dislike count is no longer available as of December 13, 2021 Learn more.
duration integer 
42
 Length of the video in seconds.
id string 
UCA6AG33Zac0xi6f9VMTxkFQ
 Youtube video id.
insights_engagement integer 
100
 Engagements inform about how many times users engaged with a post during its lifetime. Learn More.
interactions integer 
42
 Sum of likes and comments. Dislike count is no longer available for this metric as of December 13, 2021 Learn more.
interactions_per_1k_fans float 
42.42
 Interaction count for every 1000 subscribers. Dislike count is no longer available for this metric as of December 13, 2021 Learn more.
likes integer 
42
 Number of likes for the video.
media_type string 
video
 Type of Youtube video.
post_labels array 
[{ "id": "2a8545bcc98b48d1a0c4", "name": "label A"}]
 Content labels (formally post labels) assigned to the video.
profileId string 
UCA6AG33Zac0xi6f9VMTxkFQ
 The id of the Youtube profile.
url string 
https://www.youtube.com/watch?v=9AVkNQ0kDTA
 Link to the Youtube video.
video_view_time integer 
42
 Number of times the video has been viewed multiplied by the duration in seconds.
video_views integer 
42
 Number of times the video has been viewed.

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

Fields that might be used to filter YouTube profile video:
Field Allowed values Description Advanced filter support
media_type video Type of Youtube video. ✅ Supported operators:
  • match_any
post_labels *
Pattern: .+		 Content labels (formally post labels) assigned to the video. ✅ Supported operators:
  • match_all
  • match_any

Response

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

Example request

POST /3/youtube/profile/videos HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

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

Example response

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

Twitter Tweets

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, 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 /3/twitter/profiles endpoint.
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. Your request is transformed using the time zone assigned to a profile in the Suite settings of your account. The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct timezone using the timezone of each individual profile from the /3/twitter/profiles endpoint. The last day will be also included in the response.
fields array, the list of fields that will be returned in the response. Available fields are listed in the table below.
limit integer, (optional). The number of results per page. The default value is 10 and the maximal value is 100.
filter (optional), You can filter results by providing the filter parameter with field and value. See the list of fields allowed for filtering.

Parameter for Pagination

after string, value of the next property from previous response.
Basic Fields
Name Type Example Description
id string 
164929129743_10154702368914744
 Twitter tweet id.
origin string 
User-Generated Content|Brand's Content
 Source of post.
post_labels array 
[{"id": 78569316, "name": "Label Name"}]
 Content labels (formally post labels) assigned to the post.
profile object 
{"id": 78569316}
 Information about the Twitter profile.
profileId string 
78569316
 The id of the tweet author.

Fields that might be used to filter Twitter posts:
Field Allowed values Description Advanced filter support
origin User-Generated Content
Brand's Content		 Source of post. ✅ Supported operators:
  • match_any
post_labels *
Pattern: .+		 Content labels (formally post labels) assigned to the post. ✅ Supported operators:
  • match_all
  • match_any

Response

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

Example request


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

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

Example response


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

Linkedin Posts

Required OAuth2 scope: 
api.read

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

Parameters

Name Description
profiles array, list of profile IDs of the profiles available from the /3/linkedin/profiles endpoint.
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. Your request is transformed using the time zone assigned to a profile in the Suite settings of your account. The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct timezone using the timezone of each individual profile from the /3/linkedin/profiles endpoint. The last day will be also included in the response.
fields array, the list of fields that will be returned in the response. Available fields are listed in the table below.
limit integer, (optional). The number of results per page. The default value is 10 and the maximal value is 100.
sort (optional), 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.

Parameter for Pagination

after string, value of the next property from previous response.
Basic Fields
Name Type Example Description
attachments array 
[{ "title": "Struggling to find the content creation tools you need?", "description": "Check out our comprehensive list, and bookmark to keep these awesome tools right at your fingertips!", "url": "https://bit.ly/3bVufCv", "image_url": "https://external-sea1-1.xx.fbcdn.net/safe_image.php?d=AQD1V87mrnL6mHgJ&url=https%3A%2F%2Fsbks-builder.s3.amazonaws.com%2Fngysh9o0e9.jpg&_nc_hash=AQA1efZXH6wQ_JHo", "type":"link" }]
 Details about post attachments.
author object 
{ "id": "urn:li:organization:2056516", "name": "Socialbakers", "url": "https://linkedin.com/company/socialbakers-com" }
 Author details of the post.
authorId string 
urn:li:organization:2056516
 The id of the post author.
comments integer 
5
 Total number of comments.
content string 
To #TikTok or not to TikTok, that is the question.
 Content of the LinkedIn post.
content_type string 
post
 Content type of the LinkedIn post.
created_time datetime 
2016-10-24T16:15:04+00:00
 Date and time the post was created in LinkedIn.
id string 
urn:li:share:6643188663637422080
 LinkedIn post id.
interactions integer 
20
 Sum of reactions, comments and shares.
interactions_per_1k_fans float 
0.37
 Interaction count for every 1000 fans.
media_type string 
link|photo|video|status
 Type of LinkedIn post.
page object 
{ "id": "urn:li:organization:2056516", "name": "Socialbakers", "url": "https://linkedin.com/company/socialbakers-com" }
 Information about the LinkedIn page.
post_labels array 
[{ "id": "2a8545bcc98b48d1a0c4", "name": "label A"}]
 Content labels (formally post labels) assigned to the post.
profileId string 
urn:li:organization:2056516
 The id of the LinkedIn page.
reactions integer 
15
 Total number of reactions.
url string 
https://www.linkedin.com/feed/update/urn:li:share:6643188663637422080/
 Link to the LinkedIn post.
Insights Fields

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

Name Type Example Description
insights_clicks integer 
10
 Number of clicks received by a post during its lifetime.
insights_comments integer 
12
 Sum of comments received by a post during its lifetime. This is an Insights type of metric. Learn More.
insights_content_impressions integer 
10
 Sum of impressions received by a post during its lifetime.
insights_engagements integer 
15
 Engagements refers to how many times users engaged with a post during its lifetime. Learn More.
insights_impressions_engagement_rate float 
0.15
 Impressions engagement rate refers to the percentage of users who engaged with a post during its lifetime, given its impressions. Learn More.
insights_reactions integer 
5
 Sum of reactions received by a post during its lifetime. This is an Insights type of metric. Learn More.
insights_video_views integer 
13
 Number of times a LinkedIn video was viewed for at least 3 seconds. Learn More.
insights_video_views_unique integer 
6
 Number of unique people who watched this video for at least 3 seconds during its lifetime. Learn More.
insights_view_time integer 
123
 The total amount of time that users watched a LinkedIn video during its lifetime. Learn More.

Fields that might be used to sort Linkedin posts:
Basic Fields
  • comments
  • created_time
  • interactions
  • interactions_per_1k_fans
  • reactions
Insights Fields
  • insights_clicks
  • insights_comments
  • insights_content_impressions
  • insights_engagements
  • insights_impressions_engagement_rate
  • insights_video_views
  • insights_video_views_unique
  • insights_view_time

Fields that might be used to filter Linkedin posts:
Field Allowed values Description Advanced filter support
media_type status
link
video
photo
album
carousel		 Type of LinkedIn post. ✅ Supported operators:
  • match_any
post_labels *
Pattern: .+		 Content labels (formally post labels) assigned to the post. ✅ Supported operators:
  • match_all
  • match_any

Example request

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

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

Example response

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

Pinterest Posts

Required OAuth2 scope: 
api.read

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

Parameters

Name Description
profiles array, list of profile IDs of the profiles available from the /3/pinterest/profiles endpoint.
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. Your request is transformed using the time zone assigned to a profile in the Suite settings of your account. The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct timezone using the timezone of each individual profile from the /3/pinterest/profiles endpoint. The last day will be also included in the response.
fields array, the list of fields that will be returned in the response. Available fields are listed in the table below.
limit integer, (optional). The number of results per page. The default value is 10 and the maximal value is 100.
sort (optional), 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.

Parameter for Pagination

after string, value of the next property from previous response.
Basic Fields
Name Type Example Description
attachments array 
[{ "image_url": "https://i.pinimg.com/600x/19/43/9d/19439d8e299609ebfe93e5b9e8cdf991.jpg", "type":"photo" }]
 Details about post attachments.
author object 
{ "id": "376684093741466051", "name": "Socialbakers", "url": "http://pinterest.com/socialbakers" }
 Author details of the post.
authorId string 
376684093741466051
 The id of the post author.
content string 
#Video 📹 is still one of the most engaging content formats on #socialmedia.
 Content of the Pinterest post.
content_type string 
post
 Content type of the Pinterest post.
created_time datetime 
2020-06-18T10:11:50+00:00
 Date and time the post was created in Pinterest.
id string 
376684093741466051_376683956338863337
 Pinterest post id.
media_type string 
photo
 Type of Pinterest post.
post_labels array 
[{ "id": "5ee90e5126a3494b81ff", "name": "454" }]
 Content labels (formally post labels) assigned to the post.
profile object 
{ "id": "376684093741466051", "name": "Socialbakers", "url": "http://pinterest.com/socialbakers" }
 Information about the Pinterest profile.
profileId string 
376684093741466051
 The id of the Pinterest profile.
url string 
https://www.pinterest.com/pin/376683956338863337/
 Link to the Pinterest post.
Insights Fields

All metrics can only be used for profiles that have insights_enabled property set to true in the response of the /3/pinterest/profiles endpoint.

Name Type Example Description
comments integer 
2
 Total number of comments.
insights_avg_time_watched float 
125.7
 The average time in seconds someone spent playing the video and static image cards included in your Pin.
insights_engagements integer 
100
 Engagements inform about how many times users engaged with a pin during its lifetime. Learn More.
insights_impressions integer 
100
 The number of times your Pin was on screen.
insights_impressions_engagement_rate float 
0.34
 Impressions Engagement Rate informs about the percentage of users who engaged with a pin during its lifetime given its impressions. Learn More.
insights_link_clicks integer 
5
 The number of times users clicked on links that redirected them away from Pinterest.
insights_post_clicks integer 
12
 The total number of clicks on your Pin so it opens in closeup.
insights_post_saves integer 
12
 The number of times people saved your Pin to a board.
insights_reactions integer 
100
 Total reactions.
insights_save_rate float 
0.34
 The total saves of your Pins divided by the total number of times your Pins were on screen.
insights_video_completed_views integer 
35
 The number of times your video was viewed to 95% of its length.
insights_video_starts integer 
125
 Total number of video starts.
insights_video_views integer 
768
 The amount of views for at least 2 seconds with 50% of video in view.
insights_video_views_10s integer 
125
 The number of times your video was viewed for at least 10 seconds.
insights_view_time integer 
42
 The total play time for your video in seconds.
interactions integer 
4
 Sum of reactions and comments.
interactions_per_1k_fans float 
0.01
 Interaction count for every 1000 fans.

Fields that might be used to sort Pinterest posts:
Basic Fields
  • created_time
Insights Fields
  • comments
  • insights_avg_time_watched
  • insights_engagements
  • insights_impressions
  • insights_impressions_engagement_rate
  • insights_link_clicks
  • insights_post_clicks
  • insights_post_saves
  • insights_save_rate
  • insights_video_completed_views
  • insights_video_starts
  • insights_video_views
  • insights_video_views_10s
  • insights_view_time
  • interactions
  • interactions_per_1k_fans

Fields that might be used to filter Pinterest posts:
Field Allowed values Description Advanced filter support
content_type post
shared		 Content type of the Pinterest post. ✅ Supported operators:
  • match_any
post_labels *
Pattern: .+		 Content labels (formally post labels) assigned to the post. ✅ Supported operators:
  • match_all
  • match_any

Example request


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

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

Example response


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

TikTok Posts

Required OAuth2 scope: 
api.read

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

Parameters

Name Description
profiles array, list of profile IDs of the profiles available from the /3/tiktok/profiles endpoint.
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. Your request is transformed using the time zone assigned to a profile in the Suite settings of your account. The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct timezone using the timezone of each individual profile from the /3/tiktok/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 100.
sort (optional), 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 (optional), You can filter results by providing the filter parameter with field and value. See the list of fields allowed for filtering.

Parameter for Pagination

after string, value of the next property from previous response.
Basic Fields
Name Type Example Description
attachments array 
[{"image_url": {"url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-p-0068c799-us/ab475742d6f55e6f99837d167b4e76fa_1604427036~tplv-noop.image?x-expires=123123123123&x-signature=aslkfjabshfliwu"}, "type": "video"}]
 Details about post attachments.
author object 
{ "id": "26dba419-46af-4f7c-a22a-dc7176dc2af0", "name": "Emplifi", "url": "https://www.tiktok.com/@emplifi" }
 Author details of the post.
authorId string 
26dba419-46af-4f7c-a22a-dc7176dc2af0
 The id of the post author.
content_type string 
post
 Content type of the TikTok post.
created_time datetime 
2021-10-24T16:15:04+00:00
 Date and time the post was created in TikTok.
duration integer 
42
 Length of the video in seconds.
id string 
70565433244939975983
 TikTok post id.
link string 
https://www.tiktok.com/@psg/video/7054854344180600069?utm_campaign=tt4d_open_api&utm_source=6997404317372137474
 Link to the post in TikTok.
media string 
video
 Media type of TikTok post.
message string 
Message of the post.
 TikTok post content.
post_labels array 
[{ "id": "2a8545bcc98b48d1a0c4", "name": "label A"}]
 Content labels (formally post labels) assigned to the post.
Insights Fields

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

Name Type Example Description
insights_avg_time_watched integer 
42
 The average time that users spent watching the video during its lifetime.
Note: There can be up to 24h delay in availability for this metric from the TikTok Organic API.
insights_comments integer 
15
 Total number of comments for a TikTok video during its lifetime.
insights_completion_rate float 
0.42
 The percentage of times a video was watched in full during its lifetime.
Note: There can be up to 24h delay in availability for this metric from the TikTok Organic API.
insights_engagements integer 
100
 Total number of times users engaged with a video during its lifetime. TikTok Engagements is calculated from the sum of likes, comments and shares.
insights_impressions integer 
100
 The number of impressions for your post.
insights_impressions_by_traffic_source array 
[{"impression_source": "Follow","percentage": 0.1885},{"impression_source": "For You","percentage": 0.0314}]
 List of traffic sources from which a TikTok video has received its impressions.
Note: There can be up to 24h delay in availability for this metric from the TikTok Organic API.
insights_likes integer 
45
 Total number of likes for a TikTok video during its lifetime.
insights_reach integer 
100
 Total number of unique users who viewed a TikTok video during its lifetime.
Note: There can be up to 24h delay in availability for this metric from the TikTok Organic API.
insights_reach_engagement_rate float 
0.34
 Reach engagement rate informs about the percentage of users who engaged with a video during its lifetime given its reach. TikTok Engagements is calculated from the sum of likes, comments and shares.
insights_shares integer 
15
 Total number of shares for a TikTok video during its lifetime.
insights_video_views integer 
768
 Total number of video views for a TikTok video during its lifetime.
insights_view_time integer 
42
 The total amount of time that users watched the video during its lifetime.
Note: There can be up to 24h delay in availability for this metric from the TikTok Organic API.
insights_viewers_by_country array 
[{"country": "AU","percentage": 0.0255},{"country": "BR", "percentage": 0.0325}]
 Country breakdown of the viewers of a TikTok video.
Note: There can be up to 24h delay in availability for this metric from the TikTok Organic API.

Fields that might be used to sort TikTok posts:
Basic Fields
  • created_time
  • duration
Insights Fields
  • insights_avg_time_watched
  • insights_comments
  • insights_completion_rate
  • insights_engagements
  • insights_impressions
  • insights_likes
  • insights_reach_engagement_rate
  • insights_shares
  • insights_video_views
  • insights_view_time

Fields that might be used to filter TikTok posts:
Field Allowed values Description Advanced filter support
post_labels *
Pattern: .+		 Content labels (formally post labels) assigned to the post. ✅ Supported operators:
  • match_all
  • match_any

Response

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

Example request

POST /3/tiktok/profile/posts HTTPS
  Host: api.emplifi.io
  Authorization: Basic base64_encoded_auth
  Content-Type: application/json; charset=utf-8

  {
    "profiles": ["c3694e88-379a-4f3d-9942-acc7203f72e3"],
    "date_start": "2022-05-01",
    "date_end": "2022-05-20",
    "fields": [
      "id",
      "created_time",
      "attachments",
      "insights_reach"
    ],
    "sort": [
      {
        "field": "created_time",
        "order": "desc"
      }
    ],
    "limit": 1
  }

Example response

{
    "success": true,
    "data": {
      "posts": [
        {
          "id": "7099511034708315434",
          "created_time": "2022-05-19T18:08:45+00:00",
          "attachments": [
            {
              "image_url": "https://p16-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/eeb89870920743bbbcf0fecbaf18da8a_1652983726~tplv-noop.image?x-expires=1654798315&x-signature=CGac9MWE1J3XxgUE6N2TEm4pE4s%3D",
              "type": "video"
            }
          ],
          "insights_reach": 1228407
        }
      ],
      "next": "eyJjdXJzb3IiOlt7ImZpZWxkIjoiY3JlYXRlZF90aW1lIiwidmFsdWUiOiIyMDE4LTA2LTI4VDEyOjM4OjM0KzAwOjAwIiwib3JkZXIiOiJkZXNjIn1dLCJpZHMiOlsiMTc4OTM5NTExNjIyMTY0NjRfNDkwNDAyMjIwIl19=",
      "remaining": 28
    }
  }

Snapchat Posts

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

Parameters

Required OAuth2 scope: 
api.read
Name Description
profiles array, list of profile IDs of the profiles available from the /3/snapchat/profiles endpoint.
date_start, date_end string, the beginning / end of the period you want to get the data for in the format YYYY-MM-DD. Your request is transformed using the time zone assigned to a profile in the Suite settings of your account. The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct timezone using the timezone of each individual profile from the /3/snapchat/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 100.
sort (optional), 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 (optional), You can filter results by providing the filter parameter with field and value. See the list of fields allowed for filtering.

Parameter for Pagination

after string, value of the next property from previous response.
Basic Fields
Name Type Example Description
attachments array 
[{"image_url":"https://cf-st.sc-cdn.net/d/iKCnfr7QDOK3YVvENsqw.410.IRZXSOY?mo=Gj8aGBoAGgAyAQQ6AX1CBgjM8cakBkgCUF5gAVoQRGZMYXJnRodW1ibmFpbKIBEAiaAyIgAqB0lSWlhTT1k%3D&uc=94","type":"photo"}]
 Details about post attachments.
author object 
{ "id": "97e483bf-281e-4f2e-b890-da13edbc8d39", "name": "Emplifi", "url": "https://www.snapchat.com/add/@emplifi" }
 Author details of the post.
authorId string 
97e483bf-281e-4f2e-b890-da13edbc8d39
 The id of the post author.
content_type string 
snap
 Content type of the Snapchat post.
created_time datetime 
2021-10-24T16:15:04+00:00
 Date and time the post was created in Snapchat.
id string 
-w1hYHxrReeT-wZJyCTOHwAAgbWdlZ3NlZnZqAYlKyMdWAYlKyMadAAAAAA
 Snapchat post id.
media string 
video
 Media type of Snapchat post.
message string 
Message of the post.
 Snapchat post content.
post_labels array 
[{ "id": "2a8545bcc98b48d1a0c4", "name": "label A"}]
 Content labels (formally post labels) assigned to the post.
Insights Fields

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

Name Type Example Description
insights_avg_time_watched integer 
42
 The average time that users spent watching the video during its lifetime.
Note: There can be up to 24h delay in availability for this metric from the Snapchat Organic API.
insights_comments integer 
15
 Total number of comments for a Snapchat post during its lifetime.
insights_engagements integer 
100
 Total number of times users engaged with a post during its lifetime. Learn More.
insights_impressions integer 
100
 The number of impressions for your post.
insights_impressions_engagement_rate float 
0.15
 Impressions Engagement Rate informs about the percentage of users who engaged with a post during its lifetime given its impressions. Learn More.
insights_media_view_time integer 
63
 The total amount of time (in seconds) that users watched a video and images during its lifetime
insights_media_views integer 
63
 The total number of times a tile was viewed at least 1.2 seconds and viewed at least 25% of the tile on Snapchat within selected time range.
insights_reach integer 
100
 The number of people who saw your post.
insights_reach_engagement_rate float 
0.34
 Reach engagement rate informs about the percentage of users who engaged with a video during its lifetime given its reach. Learn More.
insights_screenshots integer 
15
 The number of screenshots of a snap.
insights_shares integer 
15
 Total number of shares for a Snapchat post during its lifetime.
insights_swipe_down integer 
100
 The number of swipe downs on an asset.
insights_swipe_up integer 
100
 The number of swipe ups on an asset.
insights_taps_back integer 
42
 The number of times a user taps backward on an Snapchat post
insights_taps_forward integer 
42
 The number of times a user taps forward on an Snapchat post
insights_video_views integer 
768
 Total number of video views for a Snapchat video during its lifetime.
insights_view_time integer 
42
 The total amount of time that users watched the video during its lifetime.

Fields that might be used to sort Snapchat posts:
Basic Fields
  • created_time
Insights Fields
  • insights_avg_time_watched
  • insights_comments
  • insights_engagements
  • insights_impressions
  • insights_impressions_engagement_rate
  • insights_media_view_time
  • insights_media_views
  • insights_reach
  • insights_reach_engagement_rate
  • insights_screenshots
  • insights_shares
  • insights_swipe_down
  • insights_swipe_up
  • insights_taps_back
  • insights_taps_forward
  • insights_video_views
  • insights_view_time

Fields that might be used to filter Snapchat posts:
Field Allowed values Description Advanced filter support
post_labels *
Pattern: .+		 Content labels (formally post labels) assigned to the post. ✅ Supported operators:
  • match_all
  • match_any

Response

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

Example request


POST /3/snapchat/profile/posts HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "profiles": ["97e483bf-281e-4f2e-b890-da13edbc8d39"],
  "date_start": "2022-05-01",
  "date_end": "2022-05-20",
  "fields": [
    "id",
    "created_time",
    "attachments",
    "insights_reach"
  ],
  "sort": [
    {
      "field": "created_time",
      "order": "desc"
    }
  ],
  "limit": 1
}

Example response


{
  "success": true,
  "data": {
    "posts": [
      {
        "id": "-w1hYHxrReeT-wZJyCTOHwAAgbWdlZ3NlZnZqAYlKyMdWAYlKyMadAAAAAA",
        "created_time": "2022-05-19T18:08:45+00:00",
        "attachments": [
          {
            "image_url": "https://cf-st.sc-cdn.net/d/iKCnfr7QDOK3YVvENsqw.410.IRZXSOY?mo=Gj8aGBoAGgAyAQQ6AX1CBgjM8cakBkgCUF5gAVoQRGZMYXJnRodW1ibmFpbKIBEAiaAyIgAqB0lSWlhTT1k%3D&uc=94",
            "type": "photo"
          }
        ],
        "insights_reach": 1228407
      }
    ],
    "next": "eyJjdXJzb3IiOlt7ImZpZWxkIjoiY3JlYXRlZF90aW1lIiwidmFsdWUiOiIyMDE4LTA2LTI4VDEyOjM4OjM0KzAwOjAwIiwib3JkZXIiOiJkZXNjIn1dLCJpZHMiOlsiMTc4OTM5NTExNjIyMTY0NjRfNDkwNDAyMjIwIl19=",
    "remaining": 28
  }
}

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. Spam and deleted posts are removed from results.

Parameters

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

Metrics

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

All LinkedIn, Pinterest, TikTok and Snapchat metrics can only be used for profiles that have insights_enabled property set to true in the response of their respective endpoint /${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
sentiment_type		 avg Engagement Rate for a particular post displays the average number of Interactions per Fan. Engagement Rate is therefore calculated by dividing the number of Interactions of a post by the number of Fans on that day.
insights_avg_time_watched
PITTSC
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label		 avg The average time that users spent watching the videos during its lifetime.
insights_completion_rate
IGStoriesTT
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
media_type		 avg For TikTok video this is a percentage of times a video was watched in full during its lifetime. For Instagram this is a percentage of times a story impression was not interrupted by an exit, tap back, or tap forward.
insights_engagements
FBIGTWYTLIPITTSC
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
media_type
content_type		 sum Engagements refers to how many times users engaged with a post during its lifetime. Learn More.
insights_impressions
FBIGTWLIPITTSC
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type
published_status
sentiment_type		 sum The number of impressions on your posts.
insights_impressions_engagement_rate
FBIGTWLIPISC
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
media_type
content_type		 avg Impressions engagement rate refers to the percentage of users who engaged with a post during its lifetime, given its impressions. Learn More.
insights_link_clicks
PI
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 users clicked on links that redirected them to a given destination.
insights_media_view_time
SC
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type		 sum The total amount of time (in seconds) that users watched a video and images during its lifetime
insights_media_views
TWSC
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
FBLIPI
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 clicks received by a post during its lifetime.
insights_post_saves
IGPI
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type		 sum The number of times people saved the content during its lifetime.
insights_reach_engagement
FBIGTTSC
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
FBIGTTSC
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type
published_status
sentiment_type		 avg Number of people who have seen any content associated with your Page. (Unique Users)
insights_save_rate
PI
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type
published_status		 avg The total saves of your content divided by the total number of times your content were on screen.
insights_screenshots
SC
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type		 sum The number of screenshots of a snap.
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_swipe_down
SC
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type		 sum The number of swipe downs on an asset.
insights_swipe_up
SC
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type		 sum The number of swipe ups on an asset.
insights_video_completed_views
PI
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
published_status
sentiment_type		 sum The number of times your video was viewed to 95% of its length.
insights_video_starts
PI
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
published_status
sentiment_type		 sum Total number of video starts.
insights_video_views
FBIGTWYTLIPITTSC
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
published_status
sentiment_type		 sum An aggregation of video views across multiple platforms. The definition of a video view differs per platform. FB, IG, LI count views of 3+ seconds; PI count views of 2+ seconds; YT counts views of 30+ seconds. For IG Reels video views count number of plays (video sessions with 1 ms+ of playback, excluding replays). For SC, the number of times a video snap was viewed during its lifetime. A view is counted immediately upon opening the video snap and for each time it is rewatched. Note: FB, IG, LI, TT, SC, PI and TW data represents Insights metrics. YT data comes from public sources.
insights_video_views_10s
PI
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
published_status
sentiment_type		 sum The number of times your video was viewed for at least 10 seconds.
insights_video_views_unique
LI
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
published_status
sentiment_type		 sum The number of people who have watched your video for at least 3 seconds.
insights_view_time
LIPITTSC
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label		 sum The total amount of time that users watched the video during its lifetime.
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
sentiment_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
sentiment_type		 sum Number of interactions on page posts per 1k fans.
likes
FBIGTWYTLIPI
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
media_type
sentiment_type		 sum Number of likes of profile posts. For Linkedin a public version of reactions is used. Learn More.
number_of_comments
FBIGTWYTLIPITTSC
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type
published_status
sentiment_type		 sum Number of comments on page posts.
page_posts
FBIGTWYTLIPITTSC
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
content_type
media_type
published_status
sentiment_type		 sum Number of page posts.
page_replies
TW
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label		 sum Number of replies by the Twitter profile.
page_shares
FBTWPI
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label		 sum Number of retweets or shares by the page/profile
profile_tweets
TW
date.day
date.month
date.quarter
date.week
date.year
platform
profile
post_labels
profile_label
media_type		 sum Total number of tweets, excluding replies and retweets.
sentiment_manual_auto
FBIGTWLI
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
FBTW
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:
Field Allowed values Description Advanced filter support
content_type post
reply
shared
story
snap		 Type of content. ✅ Supported operators:
  • match_any
media_type album
animated_gif
carousel
link
note
offer
photo
poll
reel
status
video
audio
activity
doc
map
combined
unknown		 Type of media used in content. ✅ Supported operators:
  • match_any
platform twitter
instagram
facebook
youtube
linkedin
pinterest
tiktok
snapchat		 Publishing platform of content. ✅ Supported operators:
  • match_any
post_labels *
Pattern: .+		 Content labels assigned to your posts ✅ Supported operators:
  • match_all
  • match_any
profile_labels *
Pattern: .+		 Profile labels assigned to your profiles. ✅ Supported operators:
  • match_all
  • match_any

Example request


POST /3/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"
          ]
        }
      ]
    }

Assets

Use these set of endpoints to integrate your current assets management solutions to our Collections.

Collections

Manage your collections with these endpoints. Besides getting a list of all the collections you have, you will also be able to create, update and archive them.

List Collections
Required OAuth2 scope: 
api.read

Get a list of all collections within the account.

Example request


GET /3/collections HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth

Example response


{
  "success": true,
  "data": [
    {
      "id": "g11N6XQBZejoR1EGGGq8",
      "name": "My first collection",
      "createdBy": {
        "userId": "1336595",
        "email": "my.email@emplifi.io"
      },
      "createdTime": "2020-10-02T12:32:57.849Z",
      "updatedTime": "2020-10-02T12:32:58.603Z",
      "status": "active",
      "permission": "private"
    }
  ]
}
Create Collection
Required OAuth2 scope: 
api.write

Create a new private or global collection inside your account. You can have a total of maximum 100 collections created.

Parameters

Name Description
name string. The name of the collection that will be created.
description string, (optional). Describes more in detail the colletion that will be created.
permission string, it can be only private or global. Defines the permission rule for the newly created Collection.

Example request


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

{
  "name": "New Collection",
  "description": "New example collection",
  "permission": "private"
}

Example response


{
  "success": true,
  "data": {
    "collectionId": "O1yxunQBZejoR1EGQshy"
  }
}
Edit Collection
Required OAuth2 scope: 
api.write

Edit a collection name and/or description.

Parameters

Name Description
collectionId string. The collection id.
name string, (optional). The name of the collection that will be created.
description string, (optional). Describes more in detail the colletion that will be created.
permission string, (optional). New permission. Changes the collection permission to global. Please note that you can only change from private to global.

Please note that name, description and permission are optional, but it's required to send at least one of them.

Example request


PATCH /3/collections HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "collectionId": "collection-id",
  "name": "a-new-name",
  "description": "a-new-description",
  "permission": "global"
}

Example response


{
  "success": true,
  "data": {
    "status": "ok"
  }
}
Archive Collection
Required OAuth2 scope: 
api.write

Archive a collection. Collection can be restored at any point.

Parameters

Name Description
collectionId string. The collection id.

Example request


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

{
  "collectionId": "collection-id"
}

Example response


{
  "success": true,
  "data": {
    "status": "ok"
  }
}
Delete Collection
Required OAuth2 scope: 
api.write

Delete a collection from suite. If there are any assets within the collection, those will get deleted as well. You can only delete a collection that has been archived. Please be extremely cautious when using this endpoint as this action is not reversible.

Parameters

Name Description
collectionId string. The collection id.

Example request


DELETE /3/collections HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "collectionId": "collection-id"
}

Example response


{
  "success": true,
  "data": {
    "status": "ok"
  }
}
Restore Collection
Required OAuth2 scope: 
api.write

Restore a previously archived collection. Collection can be archived again anytime.

Parameters

Name Description
collectionId string. The collection id.

Example request


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

{
  "collectionId": "collection-id"
}

Example response


{
  "success": true,
  "data": {
    "status": "ok"
  }
}

Assets

Manage assets with these endpoints. You can upload your own assets to existing collections or download them.

Upload Asset
Required OAuth2 scope: 
api.write

Upload an asset to a collection. You can only upload asset to a collection that already exists and you have permissions to. The maximum size of an asset you can upload is 5GB. However, for best results, upload an asset not more than 100MB. There can only be up to 500 assets per collection.

Uploading an asset is a 2 part process. This first is calling this endpoint and passing all relevant information to register the asset.

Upon registering, this endpoint will return a pre-signed URL that you should then use to upload the actual asset itself. The URL will expire in 10 minutes. More information regarding the pre-signed URL can be found here.

In your PUT request to the pre-signed URL, you should remove the authorization header. Please don't forget to include the necessary headers i.e Content-Type, Content-Length and Content-MD5 as specified in the second table below.

Parameters for 1st step - generating pre-signed URL

Name Description
collectionId string. The collection id.
assetName string. The name of the file to be uploaded. It does not necessarily need to be the existing name of that file and can be a new name. Needs to include the file extension. For example, the asset name can be thisisanimage.jpeg or thisisavideo.mkv.
assetContentType string. The MIME type of the file to be uploaded. It is only possible to upload either an image or a video. It is usually in the format of type/extension. For example, image/jpeg or video/mov. Check here to learn more about MIME types.
assetMd5 string. The MD5 checksum value of the file to be uploaded that is encoded to base64. More information on how to obtain this value can be found here, specifically the Resolution section.
description string, (optional). Asset's description.
note string, (optional). Asset's note.
labelIds array of string, (optional). An array of Emplifi label ids with which to tag the asset.

Headers for 2nd step - uploading file to pre-signed URL

Name Description
Content-Length The size of the file to be uploaded. This should be in bytes.
Content-MD5 The MD5 checksum value of the file to be uploaded that is encoded to base64. This should be the exact same value as the assetMd5 parameter specified in the first step when registering the asset.
Content-Type The MIME type of the file to be uploaded. This should be the exact same value as the assetContentType parameter specified in the first step when registering the asset.

The body should be the file to be uploaded only.

Example request


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

{
  "collectionId": "collection-id",
  "assetName": "asset-name",
  "assetContentType": "image/jpeg",
  "assetMd5": "asset-md5",
  "description": "some description",
  "note": "some note",
  "labelIds": ["labelId-1"]
}

Example response


{
  "success": true,
  "data": {
    "assetUploadUrl": "https://sbks-builder.s3-accelerate.amazonaws.com/production/content-hub/collection/account/123456/asset-name?AWSAccessKeyId=SOMEACCESSKEYID&Content-MD5=asset-md5&Content-Type=image%2Fjpeg&Expires=1603406210&Signature=SOMESIGNATURE"
  }
}

Example request to pre-signed URL


PUT https://sbks-builder.s3-accelerate.amazonaws.com/production/content-hub/collection/account/123456/asset-name?AWSAccessKeyId=SOMEACCESSKEYID&Content-MD5=asset-md5&Content-Type=image%2Fjpeg&Expires=1603406210&Signature=SOMESIGNATURE HTTPS
Content-Type: image/jpeg
Content-MD5: asset-md5
Content-Length: 12345
Body: file.jpeg

Example response from pre-signed URL


Status: 200
Get Assets
Required OAuth2 scope: 
api.read

Get the metadata and download url for all assets within a collection, or for the specified asset. All that is required is the collection id, and the asset id in case of retrieving data only for a specific asset. URLs for downloading the assets will expire in an hour.

Query String Parameters

Name Description
collectionId string. The collection id.
assetId string, (optional). The asset id.

Example request (all collection assets)


GET /3/collections/assets?collectionId=<collection_id> HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth

Example response


{
  "success": true,
  "data": [
    {
      "id": "NOo5u3QBrFWnaVYeCNdn",
      "userId": "d1961087",
      "accountId": "172196",
      "description": "aaaa something or other something",
      "createdTime": "2020-09-23T13:48:31.206Z",
      "updatedTime": "2020-09-23T13:48:31.206Z",
      "collectionId": "_MzdunQBrFWnaVYeXuI8",
      "type": "video",
      "url": "https://cdn-assets-sign.socialbakers.com/dev/content-hub/collection/account/172196/team-testing/aosdijaosid.mov?Expires=1604056447&Key-Pair-Id=APKAIEJK4DOLCYRB43WQ&Signature=O0d-BDJDatF~OAkRnl1~u8Fnu4L8S~q0~PVdkaRlBLTKdw9xFr8svwqJjw0tRN9wAh5eDDbDldLN2UYMCXs~3wxOXF7RvC0uhX~73f7Dgtbs7eQkWov-4drco-IpUSrykbKAARULxCZBNWEnXXNa6CghWpP3rgWnrGI8FKAwoZ4BTsaIX-z~cae3~sXSrG6r-3xH7XbxDQpzLxLjSJN9YDuPnpuqiXbiiLt4X8hm5G6qa93WoUDtj2s3zc0ik6r5xARGRN0dJM7sh2~ewDE3NOhAP5GC0lXc6mwC52TYMP7-cmSlPPw6LsH7~jPvF8zrw5vMaze2hE3~5APe1GXgWQ__",
      "labels": []
    },
    {
      "id": "-e1Bu3QBrFWnaVYeX7Uh",
      "userId": "d1961087",
      "accountId": "172196",
      "description": "aaaa something or other",
      "createdTime": "2020-09-23T13:57:37.696Z",
      "updatedTime": "2020-09-23T13:57:37.696Z",
      "collectionId": "_MzdunQBrFWnaVYeXuI8",
      "type": "video",
      "url": "https://cdn-assets-sign.socialbakers.com/dev/content-hub/collection/account/172196/team-testing/aosdijaosid.mov?Expires=1604056447&Key-Pair-Id=APKAIEJK4DOLCYRB43WQ&Signature=O0d-BDJDatF~OAkRnl1~u8Fnu4L8S~q0~PVdkaRlBLTKdw9xFr8svwqJjw0tRN9wAh5eDDbDldLN2UYMCXs~3wxOXF7RvC0uhX~73f7Dgtbs7eQkWov-4drco-IpUSrykbKAARULxCZBNWEnXXNa6CghWpP3rgWnrGI8FKAwoZ4BTsaIX-z~cae3~sXSrG6r-3xH7XbxDQpzLxLjSJN9YDuPnpuqiXbiiLt4X8hm5G6qa93WoUDtj2s3zc0ik6r5xARGRN0dJM7sh2~ewDE3NOhAP5GC0lXc6mwC52TYMP7-cmSlPPw6LsH7~jPvF8zrw5vMaze2hE3~5APe1GXgWQ__",
      "labels": []
    }
  ]
}

Example request (single asset)


GET /3/collections/assets?collectionId=<collection_id>&assetId=<asset_id> HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth

Example response


{
  "success": true,
  "data": {
    "id": "NOo5u3QBrFWnaVYeCNdn",
    "userId": "d1961087",
    "accountId": "172196",
    "description": "aaaa something or other something",
    "createdTime": "2020-09-23T13:48:31.206Z",
    "updatedTime": "2020-09-23T13:48:31.206Z",
    "collectionId": "_MzdunQBrFWnaVYeXuI8",
    "type": "video",
    "url": "https://cdn-assets-sign.socialbakers.com/dev/content-hub/collection/account/172196/team-testing/aosdijaosid.mov?Expires=1604056447&Key-Pair-Id=APKAIEJK4DOLCYRB43WQ&Signature=O0d-BDJDatF~OAkRnl1~u8Fnu4L8S~q0~PVdkaRlBLTKdw9xFr8svwqJjw0tRN9wAh5eDDbDldLN2UYMCXs~3wxOXF7RvC0uhX~73f7Dgtbs7eQkWov-4drco-IpUSrykbKAARULxCZBNWEnXXNa6CghWpP3rgWnrGI8FKAwoZ4BTsaIX-z~cae3~sXSrG6r-3xH7XbxDQpzLxLjSJN9YDuPnpuqiXbiiLt4X8hm5G6qa93WoUDtj2s3zc0ik6r5xARGRN0dJM7sh2~ewDE3NOhAP5GC0lXc6mwC52TYMP7-cmSlPPw6LsH7~jPvF8zrw5vMaze2hE3~5APe1GXgWQ__",
    "labels": []
  }
}
Delete Asset
Required OAuth2 scope: 
api.write

Delete an asset in a collection from suite. Please be extremely cautious when using this endpoint as this action is not reversible.

Parameters

Name Description
collectionId string. The collection id.
assetId string. The asset id.

Example request


DELETE /3/collections/assets HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8

{
  "collectionId": "_MzdunQBrFWnaVYeXuI8",
  "assetId": "13QGlHUBN8G-fcdJO6ZX"
}

Example response


{
  "success": true,
  "data":
  {
    "status": "ok"
  }
}

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

Content

Required OAuth2 scope: 
api.read

Returns a set of messages in Community created during the specified date range for specified profiles.

Parameters

Name Description
date_start, date_end string, the beginning / end of the period you want to get the data for in the ISO date-time format without timezone.
listening_queries array of strings. You can get the listening queries from the List of Listening Queries section. Request can contain either listening_queries or profiles, not both.
profiles array of objects, consists of profile IDs and platforms. You can get the profiles from the List of Connected Profiles section. Request can contain either listening_queries or profiles, not both.
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 100.
sort (optional), 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 (optional), You can filter results by providing the filter parameter with field and value. See the list of fields allowed for filtering.

Parameter for Pagination

after string, value of the next property from previous response.
Fields
Name Type Example Description
author object 
{"id": "1784142059xxxxxxx", "name": "Emplifi", "url": "https://www.instagram.com/emplifi"}
 Information about author of the post.
community_type string 
post
 Type of the post in community.
content_type string 
post
 Content type of the post.
created_time datetime 
2021-09-23T16:01:57+02:00
 Date and time the post was created.
id string 
17873624615551014
 Post id.
message string 
hello
 Message of the post.
messages array 
[{"id": "143293293014xxxxxxx", "message": "hi", "created_time": "2021-09-25T13:35:13+02:00", "origin": "User-Generated Content"}, {"id": "173291295019xxxxxxx", "message": "greetings", "created_time": "2021-09-26T09:22:37+02:00", "origin": "Brand's Content"}]
 Messages in a conversation post (only for content of type conversation).
origin string 
Brand's Content
 Source of the post.
parent_post object 
{"id": "183693293517xxxxxxx", "message": "greetings", "post_labels": [{"id": "fc3f23a18df14xxxxxxx", "name": "Label A"}]}
 Parent post (e.g. for a comment).
platform string 
instagram
 Platform, where the post was created.
post_labels array 
[{"id": "785c242afee7418e9877bb885xxxxxxx", "name": "Label B"}, {"id": "fc3fa9ff8df14xxxxxxx", "name": "Label C"}]
 Labels assigned to the post.
profileId string 
1784142059xxxxxxx
 Id of the profile associated with the post.
response_first object 
{"id": "163293297011xxxxxxx", "message": "ahoy", "response_time": "216798", "response_time_real": "1056753", "account_id": "387xxx", "user_id": "1207xxx", "first_name": "John", "last_name": "Doe"}
 First response to the post (e.g. first reply in a comment thread).
sentiment string 
no_sentiment
 Users sentiment towards the post.
url string 
https://www.instagram.com/p/CUKrCG1rxNi/
 Link to the post.

Sort
Basic Fields
  • created_time

Filter
Field Allowed values Description Advanced filter support
content_type comment
conversation
post
shared
story		 Content type of the post. ✅ Supported operators:
  • match_any
origin User-Generated Content
Brand's Content		 Source of the post. ✅ Supported operators:
  • match_any
post_labels *
Pattern: .+		 Labels assigned to the post. ✅ Supported operators:
  • match_all
  • match_any

Limits

There is a 90 day data retention limit for community data. So the date of date_start and date_end can not be more than 90 days in the past.

Response

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

Example request

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

{
  "profiles": [
    {
      "id": "1784142059xxxxxxx",
      "platform": "facebook"
    }
  ],
  "date_start": "2021-09-23T12:00:00",
  "date_end": "2021-09-23T18:00:00",
  "fields": [
    "author",
    "community_type",
    "content_type",
    "created_time",
    "id",
    "message",
    "messages",
    "origin",
    "parent_post",
    "platform",
    "post_labels",
    "profileId",
    "response_first",
    "sentiment",
    "url"
  ],
  "limit": 10,
  "sort": [
    {
      "field": "created_time",
      "order": "desc"
    }
  ],
  "filter": [
    {
      "field": "content_type",
      "value": "comment"
    },
    {
      "field": "origin",
      "value": "Brand's Content"
    },
    {
      "match_all": [
        {
          "field": "post_labels",
          "value": [
            "fc3fa9ff8df14xxxxxxx",
            "785c242afee7418e9877bb885xxxxxxx"
          ]
        }
      ]
    }
  ]
}

Example response

{
  "success": true,
  "data": {
    "posts": [
      {
        "author": {
          "id": "1784142059xxxxxxx",
          "name": "Emplifi",
          "url": "https://www.facebook.com/Emplifi/"
        },
        "community_type": "comment",
        "content_type": "comment",
        "created_time": "2021-09-23T16:01:57+02:00",
        "id": "1787362461xxxxxxx",
        "message": "hello",
        "messages": [],
        "origin": "Brand's Content",
        "parent_post": {
          "id": "183693293517xxxxxxx",
          "message": "greetings",
          "post_labels": [
            {"id": "fc3f23a18df14xxxxxxx", "name": "Label A"}
          ]
        },
        "platform": "facebook",
        "post_labels": [
          {"id": "785c242afee7418e9877bb885xxxxxxx", "name": "Label B"},
          {"id": "fc3fa9ff8df14xxxxxxx", "name": "Label C"}
        ],
        "profileId": "1784142059xxxxxxx",
        "response_first": {
          "id": "163293297011xxxxxxx",
          "message": "ahoy",
          "response_time": "216798",
          "response_time_real": "1056753",
          "account_id": "387xxx",
          "user_id": "1207xxx",
          "first_name": "John",
          "last_name": "Doe"
        },
        "sentiment": "no_sentiment",
        "url": "https://www.facebook.com/135454333xxxxxxx"
      }
    ],
    "next": "eyJuZXh0IjoiZXlKeGRXVnllU0k2ZXlKbVpXVmtWSGx3WlNJNkluVnpaWEpHWldWa0lpd2labWxsYkdSeklqcGJJbWxrSWl3aVkzSmxZWFJsWkZScGJXVWlMQ0poZFhSb2IzSkpibVp2SWl3aVkyOXVQ==",
    "remaining": 72
  }
}

Metrics

Required OAuth2 scope: 
api.read

Returns Community related metrics for requested profiles.

Request

Parameters

Name Description
date_start, date_end string, the beginning / end of the period you want to get the data for in the ISO date-time format without timezone.
listening_queries array of strings. You can get the listening queries from the List of Listening Queries section. Request can contain either listening_queries or profiles, not both.
profiles array of objects, consists of profile IDs and platforms. You can get the profiles from the List of Connected Profiles section. Request can contain either listening_queries or profiles, not both.
metrics array of objects. See parameters of the object in table below. Only one metric can be specified in a single request.
dimensions (optional) array of objects. The data of the metric can be split by a specific dimension. See the table of available dimensions.
filter (optional) array of objects. You can filter the results using simple or advanced post filters. See the table of fields allowed for filtering.

Metrics

Only one metric can be specified in a single request.
Parameters
Name Description
metric string, table of available metrics is displayed below.
Available metrics
Name Dimensions Aggregation Metric Description
content_count community_type
date
post_label
profile
profile_label
resolve_status
sentiment		 sum The total number of available content.
message_count community_type
date
post_label
profile
profile_label
resolve_status
sentiment		 sum The total number of messages in content of type conversation.
response_time community_type
post_label
profile
profile_label
resolve_status
response_date
sentiment		 median The message response time for content of type conversation.
response_time_business_hours community_type
post_label
profile
profile_label
resolve_status
response_date
sentiment		 median The message response time, in business hours only, for content of type conversation.
salesforce_lead_count community_type
post_label
profile
profile_label
resolve_status
sentiment
response_date
user_actions_created_time		 sum The total number of escalated Salesforce lead in available content.
salesforce_case_count community_type
post_label
profile
profile_label
resolve_status
sentiment
response_date
user_actions_created_time		 sum The total number of escalated Salesforce cases in available content.

Dimensions

Parameters
Name Description
type string, table of available dimension types is displayed below.
aggregation (optional) string, can be used only with date/response_date/user_actions_created_time dimensions, which use aggregation parameter instead of group.
group (optional) object, can be used to limit and sort the result buckets. See parameters of the object in table below.
Group parameters
Name Description
sort object, can be used to define sorting logic. Consists of parameters key and order.
sort.key string, possible values are value or name.
sort.order (optional) string, possible values are desc (default) or asc.
limit integer, limits number of result buckets in response. Default is 10.
Available dimension aggregations
Name Aggregation
date hour
day
month
quarter
week
year
response_date hour
day
month
quarter
week
year
user_actions_created_time hour
day
month
quarter
week
year

Filter
Field Allowed values Description Advanced filter support
community_type ad_comment
comment
direct_message
facebook_group
mention_comment
mention_post
mention_story_mention
wall_post		 ✅ Supported operators:
  • match_all
  • match_any
origin Brand's Content
User-Generated Content		 Source of the content. ✅ Supported operators:
  • match_all
  • match_any
post_labels *
Pattern: .+		 Labels assigned to the post. ✅ Supported operators:
  • match_all
  • match_any
profile_labels *
Pattern: .+		 Labels assigned to the profile. ✅ Supported operators:
  • match_all
  • match_any

Response

Parameters

Name Description
success boolean, status of the response. Possible values are true or false.
header array of objects. Result format depends on request parameters.
data array of arrays. Result format depends on request parameters.

Example request

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

{
  "profiles": [
    {
      "id": "164929xxxxxx",
      "platform": "facebook"
    },
    {
      "id": "1784140102xxxxxx",
      "platform": "instagram"
    }
  ],
  "date_start": "2021-11-14T14:30:00",
  "date_end": "2021-11-15T11:59:59",
  "dimensions": [
    {
      "type": "profile"
    },
    {
      "type": "community_type",
      "group": {
        "sort": {
          "key": "value",
          "order": "asc"
        },
        "limit": 2
      }
    },
    {
      "type": "date",
      "aggregation": "day"
    }
  ],
  "metrics": [
    {
      "metric": "content_count"
    }
  ],
  "filter": [
    {
      "field": "origin",
      "value": "Brand's Content"
    },
    {
      "match_all": [
        {
          "field": "post_labels",
          "value": [
            "fc3fa9ff8df14xxxxxxx",
            "785c242afee7418e9877bb885xxxxxxx"
          ]
        }
      ]
    }
  ]
}

Example response

{
  "success": true,
  "header": [
    {
      "type": "profile",
      "rows": [
        {
          "id": "164929xxxxxx",
          "platform": "facebook"
        },
        {
          "id": "1784140102xxxxxx",
          "platform": "instagram"
        }
      ]
    },
    {
      "type": "community_type",
      "rows": [
        "direct_message",
        {
          "other": [
            "ad_comment",
            "comment",
            "mention_comment",
            "mention_post",
            "mention_story_mention",
            "wall_post"
          ]
        }
      ]
    },
    {
      "type": "date",
      "rows": [
        "2021-11-14",
        "2021-11-15"
      ]
    },
    {
      "type": "metric",
      "rows": [
        "content_count"
      ]
    }
  ],
  "data": [
    [
      [
        [
          3
        ],
        [
          45
        ]
      ],
      [
        [
          5
        ],
        [
          98
        ]
      ]
    ],
    [
      [
        [
          2
        ],
        [
          230
        ]
      ],
      [
        [
          1
        ],
        [
          73
        ]
      ]
    ]
  ]
}

Listening

Content

Required OAuth2 scope: 
api.read

Returns a set of posts created during the specified date range and matched by the requested Listening queries.

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. 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. The last day will be also included in the response.
listening_queries array of strings, consists of listening query IDs. You can get the listening query IDs from the List of Listening Queries section.
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 and maximum value is 100.
sort (optional), You can sort the results by specifying a field and sorting order in the sort object: "field": "interactions" and "order": "desc". See the list of fields allowed for sorting.
filter (optional), You can filter results by providing the filter parameter with field and value. See the list of fields allowed for filtering.

Parameter for Pagination

after string, value of the next property from previous response.
Basic Fields
Name Type Example Description
attachments array 
{"url": "https://www.instagram.com/p/CdI4TI-xxxx/", "image_url": "https://scontent-lax3-2.cdninstagram.com/…", "type": "photo"}
 Post attachments. Objects contain fields depending on platform and attachment type: "title", "description", "url", "type", "image_url", "video_url".
author object 
{"id": "1784142059xxxxxxx", "name": "Emplifi", "url": "https://www.instagram.com/emplifi"}
 Information about author of the post.
authorId string 
1784142059xxxxxxx
 Id of the author of the post.
comments integer 
4
 Comment count of the post.
content_type string 
post
 Content type of the post.
country string 
US
 Country of origin of the post.
created_time datetime 
2022-05-17T14:52:32+02:00
 Date and time the post was created.
id string 
17873624615551014
 Post id.
interactions integer 
33
 Number of post interactions.
language string 
en
 Language of the post.
listening_queries array 
["LNQ_302015_60894bf0f78e8dxxxxxxxxxx"]
 Listening queries associated with this post.
media_type string 
status
 Media type of the post.
mentions array 
["876011587617918977"]
 Ids of mentioned profiles in the post (Twitter only).
message string 
Hello from Emplifi!
 Message of the post.
platform string 
instagram
 Platform, where the post was created.
post_labels array 
[{"id": "785c242afee7418e9877bb885xxxxxxx", "name": "Label B"}, {"id": "fc3fa9ff8df14xxxxxxx", "name": "Label C"}]
 Content labels assigned to the post.
potential_impressions integer 
18972
 Potential impressions of the post.
profileId string 
1784142059xxxxxxx
 Id of the profile associated with the post.
sentiment string 
no_sentiment
 Users sentiment towards the post.
shares integer 
14
 Number of times the post was shared on the platform.
site string 
example.net
 Website from which the post was obtained.
url string 
https://www.instagram.com/p/CUKrCG1rxNi/
 Link to the post.

Fields that might be used to sort Listening posts:
Basic Fields
  • comments
  • interactions
  • potential_impressions
  • shares

Fields that might be used to filter Listening posts:
Field Allowed values Description Advanced filter support
content_type post
comment		 Content type of the post. ✅ Supported operators:
  • match_any
country *
Pattern: .+		 Country of origin of the post. ✅ Supported operators:
  • match_any
language *
Pattern: .+		 Language of the post. ✅ Supported operators:
  • match_any
media_type album
animated_gif
carousel
link
note
offer
photo
poll
reel
status
video		 Media type of the post. ✅ Supported operators:
  • match_any
platform blogs
facebook
forums
instagram
news
twitter
youtube		 Platform, where the post was created. ✅ Supported operators:
  • match_any
post_labels *
Pattern: .+		 Content labels assigned to the post. ✅ Supported operators:
  • match_all
  • match_any
sentiment positive
negative
neutral		 Users sentiment towards the post. ✅ Supported operators:
  • match_any

Response

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

Example request

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

{
  "listening_queries": [
    "LNQ_394957_62a11038bcd2c60422edb994",
    "LNQ_394957_6241c597857f917a0529975d"
  ],
  "date_start": "2022-06-01",
  "date_end": "2022-06-30",
  "fields": [
    "id",
    "created_time",
    "author",
    "content_type",
    "comments",
    "interactions"
  ],
  "sort": [
    {
      "field": "comments",
      "order": "desc"
    }
  ],
  "filter": [
    {
      "field": "platform",
      "value": "facebook"
    }
  ],
  "limit": 5
}

Example response

{
  "success": true,
  "data": {
    "posts": [
      {
        "id": "164929129743_10155892118379744",
        "created_time": "2022-06-04T16:06:00+00:00",
        "author": {
          "id": "164929129743",
          "name": "Emplifi",
          "url": "https://www.facebook.com/Emplifi"
        },
        "content_type": "post",
        "comments": 153,
        "interactions": 5628
      }
    ],
    "next": "eyJuZXh0IjoiZXlKeGRXVnllU0k2ZXlKbVpXVmtWSGx3WlNJNkluVnpaWEpHWldWa0lpd2labWxsYkdSeklqcGJJbWxrSWl3aVkzSmxZWFJsWkZScGJXVWlMQ0poZFhSb2IzSkpibVp2SWl3aVkyOXVQ==",
    "remaining": 194
  }
}

Metrics

Required OAuth2 scope: 
api.read

Returns metrics for requested listening queries.

Request

Parameters
Name Description
date_start, date_end string, the beginning / end of the period you want to get the data for in the ISO date-time format without timezone.
listening_queries array of strings, consists of listening query IDs. You can get the listening query IDs from the List of Listening Queries section.
metrics array of objects. See parameters of the object in table below.
dimensions (optional) array of objects. The data of the metric can be split by a specific dimension. See the metrics table below for list of available dimensions.
filter (optional) array of objects. You can filter the results using simple or advanced post filters. See the table of fields allowed for filtering.
Metrics
Parameters

Name Description
metric string, table of available metrics is displayed below.
Available metrics

Name Dimensions Aggregation Metric Description
authors content_type,
country,
hashtag,
keyword,
language,
location,
media_type,
organization,
person,
platform,
post_label,
profession,
sentiment,
topic,
url 		sum The number of users who produced content.
comments content_type,
country,
hashtag,
keyword,
language,
location,
media_type,
organization,
person,
platform,
post_label,
profession,
sentiment,
topic,
url 		sum The number of comments.
content_count content_type,
country,
hashtag,
keyword,
language,
location,
media_type,
organization,
person,
platform,
post_label,
profession,
sentiment,
topic,
url 		sum The number of total available content.
interactions content_type,
country,
hashtag,
keyword,
language,
location,
media_type,
organization,
person,
platform,
post_label,
profession,
sentiment,
topic,
url 		sum The number of interactions.
potential_impressions content_type,
country,
hashtag,
keyword,
language,
location,
media_type,
organization,
person,
platform,
post_label,
profession,
sentiment,
topic,
url 		sum The number of potential impressions.
shares content_type,
country,
hashtag,
keyword,
language,
location,
media_type,
organization,
person,
platform,
post_label,
profession,
sentiment,
topic,
url 		sum The number of shares.
Dimensions
Parameters

Name Description
type string, table of available dimension types is displayed below.
group (optional) object, can be used to limit and sort the result buckets. See parameters of the object in table below.
Group parameters

Name Description
sort object, can be used to define sorting logic. Consists of parameters key and order.
sort.key string, possible values are value or name.
sort.order (optional) string, possible values are desc (default) or asc.
limit integer, limits number of result buckets in response. Default is 10.

Filter
Field Allowed values Description Advanced filter support
author [platform]-[profile_id]

Example:
facebook-1649291xxxxx		 ✅ Supported operators:
  • match_any
content_type post
comment
share		 ✅ Supported operators:
  • match_any
country GB
FR
CA
NE
...		 List of codes from ISO 3166-1 alpha-2 ✅ Supported operators:
  • match_any
language en
fr
de
es
...		 List of codes from ISO 639-1 (or ISO 639-2 if missing in ISO 639-1) ✅ Supported operators:
  • match_any
media_type album
animated_gif
carousel
link
note
offer
photo
poll
reel
status
video		 ✅ Supported operators:
  • match_any
platform facebook
instagram
linkedin
pinterest
tiktok
twitter
youtube
blogs
forums
news		 ✅ Supported operators:
  • match_any
post_labels *
Pattern: .+		 See List of Content Labels ✅ Supported operators:
  • match_all
  • match_any
sentiment positive
negative
neutral
no_sentiment		 ✅ Supported operators:
  • match_any

Response

Parameters
Name Description
success boolean, status of the response. Possible values are true or false.
header array of objects. Result format depends on request parameters.
data array of arrays. Result format depends on request parameters.

Example request

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

{
  "date_start": "2022-01-01T00:30:00",
  "date_end": "2022-12-31",
  "listening_queries": [
    "LNQ_394xxx_6241c636857f917a0xxxxxxx",
    "LNQ_394xxx_62a11038bcd2c6042xxxxxxx"
  ],
  "metrics": [
    {
      "metric": "comments"
    }
  ],
  "dimensions": [
    {
      "type": "platform",
      "group": {
        "sort": {
          "key": "value",
          "order": "asc"
        },
        "limit": 3
      }
    },
    {
      "type": "content_type"
    }
  ],
  "filter": [
    {
      "field": "sentiment",
      "value": "positive"
    }
  ]
}

Example response

{
  "success": true,
  "header": [
    {
      "type": "platform",
      "rows": [
        "blogs",
        "forums",
        {
          "other": {
            "length": 3
          }
        }
      ]
    },
    {
      "type": "content_type",
      "rows": [
        "comment",
        "post"
      ]
    },
    {
      "type": "metric",
      "rows": [
        "comments"
      ]
    }
  ],
  "data": [
    [
      [
        21
      ],
      [
        3
      ]
    ],
    [
      [
        0
      ],
      [
        null
      ]
    ],
    [
      [
        4
      ],
      [
        51
      ]
    ]
  ]
}

Facebook Ads

Content

Required OAuth2 scope: 
api.read

Returns a set of Facebook ads active during the specified date range for specified ad accounts.

Parameters

Name Description
date_start, date_end string, the beginning / end of the period you want to get the data for in the ISO date-time format without timezone.
ad_accounts array of strings. Max. limit is 500 account strings.
ad_campaigns array of compound strings (optional). Use pattern AdAccountId#CampaignId (e.g. 123#456). Max. limit is 500 campaign strings.
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. The default value is 10 and the maximal value is 500.
sort object (optional). You can sort the results by specifying a field and sorting order in the sort object: "field": "impressions" and "order": "desc". See the list of fields allowed for sorting.
filter array of objects (optional). 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
ad_account_id string 
102777873000666
 Ad account unique identifier.
ad_account_name string 
My Account Name
 Ad account name.
ad_campaign_id string 
202777873000666
 Ad campaign unique identifier.
ad_campaign_name string 
My Campaign Name
 Ad campaign name.
ad_set_id string 
2257776664444777
 Ad set unique identifier.
ad_set_name string 
IG_platform_October
 Ad set name.
ad_type string 
boosted
 Ad type.
attachments array 
[{"title": "string", "description": "string", "url": "string", "image_url": "string", "type": "string", "link": "string", "call_to_action": {"type": "string"}}]
 Ad attachments types are "photo", "video", "link". A special type is "carousel" which contains nested "attachments"
clicks integer 
13114
 The number of clicks on your ad.
cost_per_post_engagement float 
0.515
 The cost per post engagement.
cpc float 
0.39
 The cost per click.
cpm float 
1.071
 The cost per 1,000 impressions.
created_time datetime 
2016-10-24T16:15:04+00:00
 Date and time the ad was created in Facebook.
ctr float 
0.275
 The percentage of times that people saw your ad and performed a click.
engagement_rate float 
0.208
 The rate at which your ad receives interactions.
id string 
3572600736736
 Ad unique identifier.
impressions integer 
4770556
 The number of times your ad was on-screen.
inline_link_clicks integer 
9914
 The number of clicks on links within the ad that led to advertiser-specified destinations, on or off Facebook.
interaction_count integer 
8732
 The total number of reactions, comments and shares on your ad.
landing_page_view integer 
517
 The number of times users clicked on your ad link and successfully loaded the intended destination webpage.
lead integer 
27
 A submission of information by a customer with the understanding that they may be contacted at a later date by your business. For example, submitting a form or signing up for a trial.
message string 
Hello #world
 The text message of your ad.
name string 
Photo03
 The name of your ad.
objective string 
POST_ENGAGEMENT
 Ad objective.
placements object 
{"instagram": ["feed", "instagram_explore"]}
 Relations between platforms and placements.
post_engagement integer 
9914
 The total number of actions that people take involving your ad.
post_labels array 
[{"id": "1293uhzxc912u3", "name": "My label"}]
 An array of post label ids and names.
spend float 
5109.667
 The estimated total amount of money you've spent on your campaign, ad set or ad during its schedule.
status string 
ACTIVE
 Ad status.
video_play_view integer 
221
 The number of times that your video started to play. This is counted for each impression of a video, and excludes replays. This metric is in development.
Clarification of objective field
Name Description
APP_INSTALLSSend people to the shop where they can download your business's app.
BRAND_AWARENESSIncrease people's awareness of your business, brand or service.
CONVERSIONSEncourage people to take a specific action on your business's site, such as having them to add items to a cart, download your app, register for your site, or make a purchase.
EVENT_RESPONSESDrive awareness and attendance of a FB event.
LEAD_GENERATIONCollect leads for your business. Create ads that collect info from people interested in your product, such as sign-ups for newsletters.
LINK_CLICKSDrive people from Facebook to any URL you choose, such as your website's landing page, a blog post, app etc.
LOCAL_AWARENESSIncrease local awareness of your business, brand or service.
MESSAGESConnect with people on Facebook, communicate with potential or existing customers to encourage interest in your business.
MOBILE_APP_ENGAGEMENTDrive people to app events.
MOBILE_APP_INSTALLSDrive people to install your app.
OFFER_CLAIMSSuch sorts of ads enable advertisers to share coupon codes and discounts with their target audiences.
OUTCOME_APP_PROMOTIONFind new people to install your app and continue using it. New ODAX objective beneficial for App Installs and App Events.
OUTCOME_AWARENESSShow your ads to people who are mostlikely to remember them. New ODAX objective beneficial for Reach, Video views and Brand awareness objective.
OUTCOME_ENGAGEMENTGet more video views, post engagement, page likes or event responses. New ODAX objective beneficial for messsages, video views, likes, comments an shares.
OUTCOME_LEADSCollect leads for your bussines or brand. New ODAX objective beneficial for instant forms, messages, calls, sign ups.
OUTCOME_SALESFind people likely to purchase your product or service. New ODAX objective beneficial for conversions, catalogue sales, messages.
OUTCOME_TRAFFICSend people to a destination, like your website, app or Facebook event. New ODAX objective beneficial for link clicks and landing page views.
PAGE_LIKESDrive people from Facebook to like your FB page.
POST_ENGAGEMENTReach people more likely to engage with your post. Engagement includes likes, comments and shares but can also include offers claimed from your Page.
PRODUCT_CATALOG_SALESShow products from your e-commerce store's catalogue to generate sales.
REACHShow your ad to as many people as possible in your target audience.
STORE_VISITSPromote your brick-and-mortar business locations to people that are nearby.
VIDEO_VIEWSShare videos of your business with people on Facebook most likely to watch it.
Clarification of placements field
Placement Description facebook instagram messenger audience_network unknown
all_placementsMessenger: All placementsX
an_classicNative, Banner and InterstitialX
facebook_groups_feedGroups feedX
facebook_storiesStoriesX
feedFeedXX
instagram_exploreExplore feedX
instagram_igtvIGTVX
instagram_reelsReelsX
instagram_storiesStoriesX
instant_articleInstant articlesX
instream_videoInstream videosXX
marketplaceMarketplaceX
messenger_inboxInboxX
messenger_storiesStoriesX
rewarded_videoRewarded videosX
right_hand_columnRight columnX
searchSearchX
unknownUnknown placementX
video_feedsVideo feedX

Sort
Basic Fields
  • clicks
  • cost_per_post_engagement
  • cpc
  • cpm
  • ctr
  • engagement_rate
  • impressions
  • inline_link_clicks
  • interaction_count
  • landing_page_view
  • lead
  • post_engagement
  • spend
  • video_play_view

Filter
Field Allowed values Description Advanced filter support
ad_type boosted
catalog
dynamic
standard
variations		 Ad type. ✅ Supported operators:
  • match_any
country US
GB
MX
... More than 240 country codes ...		 Country value is based on results, not targeting. ✅ Supported operators:
  • match_any
objective APP_INSTALLS
BRAND_AWARENESS
CONVERSIONS
EVENT_RESPONSES
LEAD_GENERATION
LINK_CLICKS
LOCAL_AWARENESS
MESSAGES
MOBILE_APP_ENGAGEMENT
MOBILE_APP_INSTALLS
OFFER_CLAIMS
OUTCOME_APP_PROMOTION
OUTCOME_AWARENESS
OUTCOME_ENGAGEMENT
OUTCOME_LEADS
OUTCOME_SALES
OUTCOME_TRAFFIC
PAGE_LIKES
POST_ENGAGEMENT
PRODUCT_CATALOG_SALES
REACH
STORE_VISITS
VIDEO_VIEWS		 Ad objective. ✅ Supported operators:
  • match_any
placements all_placements
an_classic
facebook_groups_feed
facebook_stories
feed
instagram_explore
instagram_igtv
instagram_reels
instagram_stories
instant_article
instream_video
marketplace
messenger_inbox
messenger_stories
rewarded_video
right_hand_column
search
video_feeds
unknown		 Relations between platforms and placements. ✅ Supported operators:
  • match_any
platform audience_network
facebook
instagram
messenger		 Publishing Platform of the ad. Audience Network extends Facebook's people-based advertising beyond the Facebook platform. With Audience Network, publishers can make money by showing ads from Facebook advertisers in their apps. ✅ Supported operators:
  • match_any
post_labels *
Pattern: .+		 An array of post label ids and names. ✅ Supported operators:
  • match_all
  • match_any

Clarification of platform filter field

Audience Network extends Facebook's people-based advertising beyond the Facebook platform. With Audience Network, publishers can make money by showing ads from Facebook advertisers in their apps.

Response

Name Description
success Status of the response. Possible values are true or false.
data object containing the following properties:
  • posts: array, containing posts

Example request

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

{
  "date_start": "2022-05-01",
  "date_end": "2022-06-01",
  "ad_accounts": ["827395000927082"],
  "ad_campaigns": ["827395000927082#231299220370118"],
  "fields": [
    "ad_account_name",
    "ad_type",
    "attachments",
    "clicks",
    "created_time",
    "id",
    "impressions",
    "message",
    "name",
    "objective",
    "placements",
    "post_labels",
    "status"
  ],
  "filter": [
    {
      "field": "placements",
      "value": "feed"
    },
    {
      "field": "platform",
      "value": ["facebook", "instagram"]
    },
    {
      "match_any": [
        {
          "field": "ad_type",
          "value": ["standard", "boosted"]
        }
      ]
    }
  ],
  "sort": {
    "field": "impressions",
    "order": "desc"
  },
  "limit": 1
}

Example response

{
  "success": true,
  "data": {
    "posts": [
      {
        "ad_account_name": "testing API",
        "ad_type": "standard",
        "attachments": [
          {
            "type": "photo",
            "image_url": "https://www.facebook.com/ads/image/?d=AQJ_jLw7AgR_T22WoqvLBgqASGmfU5crSXqGiPhRULCgln8OCvGulZgOR4iY670vaQIfT6eupw5hg0VUxBZXYz5Lh9wgIwO4R9ZeJ1mDOn6IquIJLpSetQoa0wLV2lOCoG3JJvU_o4PcIGx6Lx00bn_3"
          }
        ],
        "clicks": 71,
        "created_time": "2022-06-01T08:28:18.000Z",
        "id": "23851631725210369",
        "impressions": 20735,
        "message": "Brace yourself the winter is coming!",
        "name": "COM-698 ad",
        "objective": "OUTCOME_AWARENESS",
        "placements": {
          "facebook": [
            "feed"
          ],
          "instagram": [
            "feed"
          ]
        },
        "post_labels": [
          {
            "id": "1e7948c0abc74d20b2725e9a3303a7a1",
            "name": "api test"
          }
        ],
        "status": "ACTIVE"
      }
    ]
  }
}

Metrics

Required OAuth2 scope: 
api.read

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.
ad_accounts array of strings. Max. limit is 500 account strings.
ad_campaigns array of strings. Max. limit is 500 campaign strings.
metrics array of objects. See parameters of the object in table 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. A maximum of 2 dimensions can be used. See the table of allowed dimension combinations.
filter array of objects. You can filter the results using simple or advanced post filters. See the table of fields allowed for filtering.

Metrics

Parameters
Name Description
metric string, table of available metrics is displayed below.
aggregation string, specifies aggregation used for calculation of metric results. In table below are default values used for each metric. Not all metrics support multiple aggregation types.
alias string, alias for metric name in response header. Also allows querying for same metric with different aggregation.
Available metrics

The provided results are in USD, for all types of currency metrics.

Name Dimensions Aggregation Metric Description
impressions ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of times that your ads were on-screen.
spend ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The estimated total amount of money you've spent on your campaign, ad set or ad during its schedule. This metric is estimated.
clicks ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of clicks on your ads.
cpc ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 avg The average cost for each click (all).
ctr ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 avg The percentage of times that people saw your ads and performed a click (all).
cpm ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 avg The average cost per 1,000 impressions.
page_engagement ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The total number of actions that people took on your Facebook Page and its posts, attributed to your ads.
page_likes ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of likes of your Facebook Page attributed to your ads.
comment_count ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of comments on your ads.
post_engagement ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The total number of actions that people take involving your ads.
like_count ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of reactions on your ads. The reactions button on an ad allows people to share different reactions to its content: like, love, haha, wow, sad or angry.
interaction_count ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The total number of reactions, comments and shares on your ads.
reaction_anger ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of anger reactions on your ads.
reaction_like ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of like reactions on your ads.
reaction_love ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of love reactions on your ads.
reaction_haha ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of haha reactions on your ads.
reaction_wow ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of wow reactions on your ads.
reaction_sorry ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of sorry reactions on your ads.
reaction_pride ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of pride reactions on your ads.
reaction_thankful ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of thankful reactions on your ads.
reaction_care ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of care reactions on your ads.
onsite_conversion_post_save ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The total number of times your ads have been saved. This metric is in development.
share_count ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of shares of your ads. People can share your ads or posts on their own or friends' Timelines, in groups and on their own Pages.
photo_view ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of views of photos on your Page or posts that are attributed to your ads. Photo views are counted when people click on photos to view them.
video_view ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of views of videos on your Page or posts that are attributed to your ads. Video views are counted when people click on video to view them.
rsvp ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of people who responded with Interested or Going to your Facebook event, attributed to your ads.
checkin ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of check-ins to your Facebook Page that are attributed to your ads. If your Page has a physical address associated with it, people can check in to your Page when they update their status in their Facebook News Feed or Timeline.
full_view_impressions ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of times that your entire ad was viewed.
cost_per_page_engagement ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 avg The average cost for each Page engagement.
cost_per_page_like ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 avg The average cost for each Facebook Page like.
cost_per_post_engagement ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 avg The average cost for each post engagement.
cost_per_rsvp ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 avg The average cost for each event response.
video_thruplay_watched ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of times that your video was played to completion, or for at least 15 seconds.
video_p25_watched ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of times your video was played at 25% of its length, including plays that skipped to this point.
video_p50_watched ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of times your video was played at 50% of its length, including plays that skipped to this point.
video_p75_watched ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of times your video was played at 75% of its length, including plays that skipped to this point.
video_p95_watched ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of times your video was played at 95% of its length, including plays that skipped to this point.
video_p100_watched ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of times your video was played at 100% of its length, including plays that skipped to this point.
video_avg_time_watched ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 avg The average time that a video was played for, including any time spent replaying the video for a single impression.
video_play_view ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of times that your video started to play. This is counted for each impression of a video, and excludes replays. This metric is in development.
canvas_avg_view_time ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 avg The average total time, in seconds, that people spent viewing an Instant Experience. An Instant Experience is a screen that opens after someone interacts with your ad on a mobile device. It may include a series of interactive or multimedia components, including a videos, images product catalogue and more.
canvas_avg_view_percent ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 avg The average percentage of the Instant Experience that people saw. An Instant Experience is a screen that opens after someone has interacted with your ad on a mobile device. It may include a series of interactive or multimedia components, including a video, images product catalogue and more.
cost_per_thruplay ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 avg The average cost of each ThruPlay.
inline_link_clicks ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of clicks on links within the ad that led to destinations or experiences, on or off Facebook. For ads promoting Instagram profile views, link clicks include clicks on the ad header or comments that led to the advertiser's profile.
outbound_clicks ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of clicks on links that take people off Facebook-owned properties.
inline_link_click_ctr ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 avg The percentage of times people saw your ads and performed a link click.
outbound_clicks_ctr ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 avg The percentage of times that people saw your ads and performed an outbound click.
instant_experience_clicks_to_open ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of clicks on your ads that open an Instant Experience. This metric is in development.
instant_experience_clicks_to_start ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of times that an interactive component in an Instant Experience starts. This metric is in development.
instant_experience_outbound_clicks ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of clicks on links in an Instant Experience that take people off Facebook-owned properties. This metric is in development.
cost_per_inline_link_click ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 avg The average cost for each link click.
cost_per_outbound_click ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 avg The average cost for each outbound click.
omni_achievement_unlocked ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of unlock achievement events attributed to your ads, based on information received from one or more of your connected Facebook Business Tools.
add_payment_info ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The addition of customer payment information during a checkout process. For example, a person clicks on a button to save their billing information.
omni_add_to_cart ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The addition of an item to a shopping cart or basket. For example, clicking an Add to Cart button on a website.
add_to_wishlist ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The addition of items to a wishlist. For example, clicking an Add to Wishlist button on a website.
omni_activate_app ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of times your app was activated from mediums attributed to your ads.
omni_app_install ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of times your app was installed from mediums attributed to your ads.
omni_initiated_checkout ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of initiate checkout events on mediums attributed to your ads.
omni_view_content ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of view content events on mediums attributed to your ads.
omni_spend_credits ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of credit spent on a particular ad.
app_custom_event ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of Facebook Pixel Custom events. Custom events are actions that fall outside those covered by Facebook standard events (Add to cart, Complete Registration, Contatct, Purchase,..).
app_engagement ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of desktop app events recorded on mediums attributed to your ads.
app_story ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of actions related to the desktop app story that were recorded as app events and attributed to your ads.
app_use ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of uses of your desktop app that were recorded as app events and attributed to your ads.
games_plays ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of times a game was played that resulted from mediums attributed to your ads.
landing_page_view ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of times users clicked on your ad link and successfully loaded the intended destination webpage.
lead ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum A submission of information by a customer with the understanding that they may be contacted at a later date by your business. For example, submitting a form or signing up for a trial.
omni_level_achieved ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of achieve level events that are tracked by one of your Facebook Business Tools (such as a Facebook pixel, app SDK or offline event set) and attributed to your ads.
onsite_conversion_flow_complete ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of times a workflow was completed within a Facebook-owned property (such as Pages or Messenger) and attributed to your ads.
purchase_roas_omni_purchase ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 avg The total return on ad spend (ROAS) from website purchases. This is based on the value of all conversions recorded by the Facebook pixel on your website and attributed to your ads.
omni_purchase ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The completion of a purchase, usually signified by receiving order or purchase confirmation, or a transaction receipt. For example, landing on a Thank You or confirmation page.
omni_rate ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of ratings submitted events on mediums attributed to your ads.
omni_complete_registration ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of completed registration events on mediums attributed to your ads.
omni_search ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum A search performed on your website, app or other property. For example, product or travel searches.
store_visit_with_dwell ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of times users visited your stores from mediums attributed to your ads. This metric is estimated.
subscribe ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The start of a paid subscription for a product or service you offer.
omni_tutorial_completion ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 sum The number of completed tutorial events that are tracked by one of your Facebook Business Tools (such as a Facebook pixel, app SDK or offline event set) and attributed to your ads.
engagement_rate ad_account
age
campaign
country
date.day
date.month
date.quarter
date.week
gender
objective
placement
publisher_platform		 avg The rate at which your ads receive interactions.

Dimensions

Parameters
Name Description
type string, table of available dimension types and their combinations is displayed below.
fields (optional) array of strings. Allow extending response with additional data. See available fields in table below.
group (optional) object, can be used to limit and sort the result buckets. See parameters of the object in table below.
other (optional) boolean, allows aggregation of result buckets over defined limit into last cumulative result bucket.
Group parameters
Name Description
sort object, can be used to define sorting logic. Consists of parameters key, order and valueIndex.
sort.key string, possible values are value, sortIndex, name and field
sort.order (optional) string, possible values are desc (default) and asc
sort.valueIndex (optional) integer, defines which metric's results will be used for sorting. Starts with 0 for first metric.
limit integer, limits number of result buckets in response. Default is 10.
Dimension combinations
ad_account campaign age gender country objective placement publisher_platform date
ad_account
campaign
age
gender
country
objective
placement
publisher_platform
date
Dimension fields
ad_account_name campaign_name
ad_account
campaign
Limits
Dimension Type Limit
campaign Max. group.limit is 2000.
country Max. group.limit is 250.
date.day Max. allowed day interval between request's date_start and date_end is 31 days.
date.week Max. allowed day interval between request's date_start and date_end is 365 days.
campaign + country Max. 50 000 possible result buckets is allowed. Multiplication of group.limit for combination of these two dimensions can't be greater than 50 000.

Valid
dimensions: [{ type: 'campaign', group: { limit: 1000 }}, { type: 'country', group: { limit: 10 }}]

Invalid
dimensions: [{ type: 'campaign', group: { limit: 501 }}, { type: 'country', group: { limit: 100 }}]
Clarification of objective field
Name Description
APP_INSTALLSSend people to the shop where they can download your business's app.
BRAND_AWARENESSIncrease people's awareness of your business, brand or service.
CONVERSIONSEncourage people to take a specific action on your business's site, such as having them to add items to a cart, download your app, register for your site, or make a purchase.
EVENT_RESPONSESDrive awareness and attendance of a FB event.
LEAD_GENERATIONCollect leads for your business. Create ads that collect info from people interested in your product, such as sign-ups for newsletters.
LINK_CLICKSDrive people from Facebook to any URL you choose, such as your website's landing page, a blog post, app etc.
LOCAL_AWARENESSIncrease local awareness of your business, brand or service.
MESSAGESConnect with people on Facebook, communicate with potential or existing customers to encourage interest in your business.
MOBILE_APP_ENGAGEMENTDrive people to app events.
MOBILE_APP_INSTALLSDrive people to install your app.
OFFER_CLAIMSSuch sorts of ads enable advertisers to share coupon codes and discounts with their target audiences.
OUTCOME_APP_PROMOTIONFind new people to install your app and continue using it. New ODAX objective beneficial for App Installs and App Events.
OUTCOME_AWARENESSShow your ads to people who are mostlikely to remember them. New ODAX objective beneficial for Reach, Video views and Brand awareness objective.
OUTCOME_ENGAGEMENTGet more video views, post engagement, page likes or event responses. New ODAX objective beneficial for messsages, video views, likes, comments an shares.
OUTCOME_LEADSCollect leads for your bussines or brand. New ODAX objective beneficial for instant forms, messages, calls, sign ups.
OUTCOME_SALESFind people likely to purchase your product or service. New ODAX objective beneficial for conversions, catalogue sales, messages.
OUTCOME_TRAFFICSend people to a destination, like your website, app or Facebook event. New ODAX objective beneficial for link clicks and landing page views.
PAGE_LIKESDrive people from Facebook to like your FB page.
POST_ENGAGEMENTReach people more likely to engage with your post. Engagement includes likes, comments and shares but can also include offers claimed from your Page.
PRODUCT_CATALOG_SALESShow products from your e-commerce store's catalogue to generate sales.
REACHShow your ad to as many people as possible in your target audience.
STORE_VISITSPromote your brick-and-mortar business locations to people that are nearby.
VIDEO_VIEWSShare videos of your business with people on Facebook most likely to watch it.

Filter
Field Allowed values Description Advanced filter support
age 13-17
18-24
25-34
35-44
45-54
55-64
65+		 Age is based on results, not targeting. ✅ Supported operators:
  • match_any
country US
GB
MX
... More than 240 country codes ...		 List of codes from ISO 3166-1 alpha-2. ✅ Supported operators:
  • match_any
gender female
male		 Gender is based on results, not targeting. ✅ Supported operators:
  • match_any
objectives CONVERSIONS
LINK_CLICKS
APP_INSTALLS
REACH
POST_ENGAGEMENT
PRODUCT_CATALOG_SALES
LEAD_GENERATION
VIDEO_VIEWS
BRAND_AWARENESS
PAGE_LIKES
STORE_VISITS
MESSAGES
EVENT_RESPONSES
MOBILE_APP_INSTALLS
MOBILE_APP_ENGAGEMENT
OFFER_CLAIMS
OUTCOME_AWARENESS
OUTCOME_ENGAGEMENT
OUTCOME_LEADS
OUTCOME_SALES
OUTCOME_TRAFFIC
OUTCOME_APP_PROMOTION		 Objectives used within publishing platform. For more details see Clarification of objective fields under FB ads content section. ✅ Supported operators:
  • match_any
placement feed
instagram_stories
instagram_explore
video_feeds
marketplace
facebook_stories
search
instream_video
instant_article
an_classic
right_hand_column
messenger_inbox
messenger_stories
rewarded_video
facebook_groups_feed
instagram_igtv
instagram_reels
all_placements		 Ad placement used within publishing platform. For more details see Clarification of placement fields under FB ads content section. ✅ Supported operators:
  • match_any
publisher_platform facebook
instagram
audience_network
messenger		 Publishing Platform of the ad. Audience Network extends Facebook's people-based advertising beyond the Facebook platform. With Audience Network, publishers can make money by showing ads from Facebook advertisers in their apps. ✅ Supported operators:
  • match_any

Response

Parameters

Name Description
success boolean, status of the response. Possible values are true or false.
header array of objects. Result format depends on request parameters.
data array of arrays. Result format depends on request parameters.

Dimensions

Dimension Possible values
ad_account *
Example:
227555088172XXX
campaign *
Example:
227555088172XXX#23847159232150XXX
date *
Format:
YYYY-MM-DD
Example:
2021-01-01
gender female
male
unknown
age 13-17
18-24
25-34
35-44
45-54
55-64
65+
unknown
objective CONVERSIONS ‐ Encourage people to take a specific action on your business's site, such as having them to add items to a cart, download your app, register for your site, or make a purchase.
LINK_CLICKS ‐ Drive people from Facebook to any URL you choose, such as your website's landing page, a blog post, app etc.
APP_INSTALLS ‐ Send people to the shop where they can download your business's app.
REACH ‐ Show your ad to as many people as possible in your target audience.
POST_ENGAGEMENT ‐ Reach people more likely to engage with your post. Engagement includes likes, comments and shares but can also include offers claimed from your Page.
PRODUCT_CATALOG_SALES ‐ Show products from your e-commerce store's catalogue to generate sales.
LEAD_GENERATION ‐ Collect leads for your business. Create ads that collect info from people interested in your product, such as sign-ups for newsletters.
VIDEO_VIEWS ‐ Share videos of your business with people on Facebook most likely to watch it.
BRAND_AWARENESS ‐ Increase people's awareness of your business, brand or service.
PAGE_LIKES ‐ Drive people from Facebook to like your FB page.
STORE_VISITS ‐ Promote your brick-and-mortar business locations to people that are nearby.
MESSAGES ‐ Connect with people on Facebook, communicate with potential or existing customers to encourage interest in your business.
EVENT_RESPONSES ‐ Drive awareness and attendance of a FB event.
MOBILE_APP_INSTALLS ‐ Drive people to install your app.
MOBILE_APP_ENGAGEMENT ‐ Drive people to app events.
OFFER_CLAIMS ‐ Such sorts of ads enable advertisers to share coupon codes and discounts with their target audiences.
OUTCOME_AWARENESS ‐ Awareness (ODAX)
OUTCOME_ENGAGEMENT ‐ Engagement (ODAX)
OUTCOME_LEADS ‐ Leads (ODAX)
OUTCOME_SALES ‐ Sales (ODAX)
OUTCOME_TRAFFIC ‐ Traffic (ODAX)
OUTCOME_APP_PROMOTION ‐ App Promotion (ODAX)
unknown
publisher_platform facebook
instagram
audience_network ‐ Audience Network extends Facebook's people-based advertising beyond the Facebook platform. With Audience Network, publishers can make money by showing ads from Facebook advertisers in their apps.
messenger
unknown
placement feed
instagram_stories
instagram_explore
video_feeds
marketplace
facebook_stories
search
instream_video
instant_article
an_classic
right_hand_column
messenger_inbox
messenger_stories
rewarded_video
facebook_groups_feed
instagram_igtv
instagram_reels
all_placements
unknown
country US
GB
MX
unknown
... More than 240 country codes ...

Example request

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

{
  "date_start": "2020-01-01",
  "date_end": "2021-01-01",
  "ad_accounts": ["2233445566778899"],
  "filter": [
    {
        "field": "objectives",
        "value": [
            "VIDEO_VIEWS",
            "REACH"
        ]
    },
    {
        "match_all": [
            {
                "field": "age",
                "value": [
                    "13-17",
                    "18-24",
                    "25-34",
                    "35-44"
                ]
            }
        ]
    }
  ],
  "dimensions": [
    {
        "type": "campaign",
        "fields": [
            "ad_account_name",
            "campaign_name"
        ],
        "group": {
            "sort": {
                "key": "value",
                "order": "asc",
                "valueIndex": 0
            },
            "limit": 3
        },
        "other": true
    },
    {
        "type": "gender"
    }
  ],
  "metrics": [
    {
        "metric": "clicks"
    },
    {
        "metric": "cpc"
    }
  ]
}

Example response


{
  "success": true,
  "header": [
      {
          "type": "campaign",
          "rows": [
              "2233445566778899#231123222333234423",
              "2233445566778899#255525662577258825",
              {
                  "other": {
                      "length": 11
                  }
              }
          ],
          "fields": [
              {
                  "ad_account_name": "SocialBakers",
                  "campaign_name": "SocialBakers API"
              },
              {
                  "ad_account_name": "SocialBakers",
                  "campaign_name": "Facebook Ads endpoint"
              },
              {
                  "ad_account_name": null,
                  "campaign_name": null
              }
          ]
      },
      {
          "type": "gender",
          "rows": [
              "female",
              "male",
              "unknown"
          ]
      },
      {
          "type": "metric",
          "rows": [
              "clicks",
              "cpc"
          ]
      }
  ],
  "data": [
      [
          [
              460,
              0.49
          ],
          [
              317,
              0.53
          ],
          [
              4,
              0.222
          ]
      ],
      [
          [
              481,
              0.571
          ],
          [
              350,
              0.736
          ],
          [
              4,
              0.137
          ]
      ],
      [
          [
              30335,
              0.228
          ],
          [
              19741,
              0.275
          ],
          [
              65,
              0.238
          ]
      ]
  ]
}

Tableau Web Data Connector (Tableau WD Connector)

Tableau is a data visualization tool used to simplify raw data into an easily understandable format, in the form of dashboards and worksheets that feature interactive graphs, tables, and more.

Emplifi Tableau WD Connector allows you to access the Emplifi API and use it as a data source for your Tableau dashboards and worksheets.

Need help connecting Emplifi Tableau WD Connector?

Please visit the Tableau Help center and read this article.

Emplifi Tableau Connector is available at this address: https://api.emplifi.io/tableau-wdc-v3.

In order to log in please use your API credentials (Token/Secret). If you don’t have your own, please check the Security and Authentication section.

The majority of metrics available in the API v3 are also available in Tableau Connector. For more details, please visit our help center.

Looker Studio Connector (previously known as Google Data Studio)

Looker Studio is a tool that converts your analytics data into informative reports and dashboards which are easy to read, share, and customize.

Emplifi Looker Studio Connector allows you to access the Emplifi API and use it as a data source for your reports and dashboards.

Need help connecting Emplifi Looker Studio Connector?

You can find the Emplifi API 3.0 Connector in the Gallery or using this direct link.

In order to authorize access, please use your API credentials (Token = Username / Secret = Token). If you don’t have your own, please check the Security and Authentication section.

The majority of metrics available in the API v3 are also available in Looker Studio. For more details, please visit our help center.

If you are using the previous version of the Connector, please check the API v1 documentation.

Power BI Connector (PBI Connector)

Power BI Desktop allows you to connect, transform, and visualize your data. You can integrate multiple data sources and combine them to build visual representations, gather them in collections, and share them as reports and dashboards.

Emplifi PBI Connector allows you to access the Emplifi API and use it as a data source for your reports and dashboards.

Need help connecting Emplifi to Power BI?

To connect to data in Power BI Desktop, select Get data from the Home ribbon, and search for “Emplifi connector”.

If you need assistance to connect your data, please visit the Power BI Documentation.

To log in, use your API credentials (Token/Secret). If you don’t have your own, check the Security and Authentication section.

The majority of metrics available in the API v3 are also available in Power BI Connector. For more details, please visit our help center.

Changelog

v3.43 (2024/03/27)

  • /3/facebook/metrics
    • Fixed support to historical data for deprecated Facebook metric + dimension combinations:
      • Dimension like_source + insights_fan_adds metric.
      • Dimension like_source + insights_fan_adds_unique metric.
      • Dimension unlike_source + insights_fans_lifetime metric.
      • Dimension gender_age + insights_fan_adds metric.
      • Dimension frequency_distribution + insights_post_reach metric.

v3.42 (2024/03/12)

  • /3/community/posts
    • Fixes an error when requesting posts for platforms not available in Community. The list of supported platforms stays:
      • facebook
      • instagram
      • linkedin
      • tiktok
      • twitter
      • youtube
  • /2/facebook/page/posts
    • Facebook has updated deprecation list for 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_interactions
        • insights_interactions_by_interaction_type

v3.41 (2024/03/07)

  • /3/facebook/metrics
  • /3/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
      • Additional deprecated metrics:
        • insights_activity
        • insights_activity_unique
        • insights_interactions
        • insights_interactions_by_interaction_type

v3.40 (2024/02/28)

  • /3/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.
      • Combination of dimension and metric:
        • Dimension like_source + insights_fan_adds metric.
        • Dimension like_source + insights_fan_adds_unique metric.
        • Dimension unlike_source + insights_fans_lifetime metric.
        • Dimension gender_age + insights_fan_adds metric.
        • Dimension frequency_distribution + insights_post_reach metric.
      • Metrics:
        • insights_positive_feedback
        • insights_post_clicks
        • insights_reach_engagement
        • insights_engaged_users
        • insights_reactions

v3.39 (2024/02/14)

v3.38 (2023/11/28)

  • Breaking change: Facebook has deprecated audience_locale metric (more info here). Alternative metric is N/A. Make sure to update your reports accordingly.
  • Affected metrics
    locale can no longer be used as a dimension for the following metric:
    • insights_followers
  • Affected endpoints

v3.37 (2023/09/20)

  • /3/pinterest/profile/posts
    • Additional metrics have been added to Pinterest pins - insights_avg_time_watched, insights_engagements, insights_impressions, insights_impressions_engagement_rate, insights_link_clicks, insights_post_clicks, insights_post_saves, insights_reactions, insights_save_rate, insights_video_completed_views, insights_video_starts, insights_video_views, insights_video_views_10s, insights_view_time.
  • /3/aggregated-metrics
    • Metrics now support new Pinterest data - insights_avg_time_watched, insights_engagements, insights_impressions, insights_impressions_engagement_rate, insights_post_clicks, insights_post_saves, insights_video_views, insights_view_time, likes.
    • New metrics added:
      • insights_link_clicks
      • insights_save_rate
      • insights_video_completed_views
      • insights_video_views_10s
      • insights_video_starts
  • Breaking change: Removed shares metric from Pinterest pins. Pinterest no longer provides a Shares metric. A similar alternative would be the insights_post_saves metric which tracks the number of times people saved your Pin to a board. Affected Endpoints:

v3.36 (2023/08/07)

v3.35 (2023/08/24)

v3.34 (2023/07/27)

  • /3/{network}/profiles
    • Now supports Snapchat profiles under /3/snapchat/profiles
  • /3/snapchat/profile/posts
  • /3/aggregated-metrics
    • Added snap as content_type filter option.
    • Metrics page_posts, number_of_comments, insights_video_views, insights_engagements, insights_media_views, insights_reach_per_content, insights_reach_engagement, insights_avg_time_watched, insights_impressions, insights_impressions_engagement_rate and insights_view_time now support Snapchat Insights data.
    • New metrics available for Snapchat:
      • insights_swipe_up
      • insights_swipe_down
      • insights_screenshots
      • insights_media_view_time

v3.33 (2023/06/29)

v3.32 (2023/06/01)

v3.31 (2023/05/04)

v3.30 (2023/04/06)

  • /3/linkedin/profile/posts
    • Fixed behavior of LinkedIn posts when requesting the data with an expired insights - it returns empty data now as other platforms.

v3.29 (2023/03/22)

v3.28 (2023/03/08)

  • /3/instagram/profile/posts
    • Added origin field and filter.
    • Fixed issue when both user generated content and brand generated content were returned.

v3.27 (2023/02/09)

v3.26 (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 /3/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.
    • POST /3/instagram/profile/posts will return content with media_type=video instead of media_type=video_igtv which now also includes the video_igtv content. All previous requests with filter media_type=video_igtv will be automatically converted to media_type=video so no changes on your end are necessary.
  • Endpoint GET /3/tiktok/profiles now returns also community_enabled flag.

v3.25 (2022/11/23)

  • Fixed the incorrect Facebook Ads metrics metric page_like to be page_likes for The number of likes of your Facebook Page attributed to your ads.
  • Rename Google Data Studio Connector to Looker Studio Connector.

v3.24 (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
  • /3/community/metrics
    • Added new metric response_time_business_hours. This metric is a replacement for metric parameter options in future major versions of API.

v3.23 (2022/09/14)

v3.22 (2022/08/04)

v3.21 (2022/07/21)

v3.20 (2022/07/12)

  • LinkedIn Insights are now supported
    • /3/linkedin/metrics
      • Added profile metrics for LinkedIn - insights_post_clicks, insights_engagements, insights_impressions, insights_reach, insights_reach_engagement_rate, insights_impressions_engagement_rate.
      • Requesting insights data with a profile without insights access will result in an error with code 7.
    • /3/linkedin/profile/posts
      • Additional metrics have been added to LinkedIn posts - insights_comments, insights_reactions, insights_clicks, insights_engagements, insights_content_impressions, insights_video_views, insights_view_time, insights_video_views_unique, insights_impressions_engagement_rate.
    • /3/aggregated-metrics
      • Metrics now supporting new LinkedIn data - insights_engagements, insights_impressions, insights_video_views, insights_view_time, insights_impressions_engagement_rate, likes.
      • New metrics added:
        • insights_post_clicks
        • insights_video_views_unique

v3.19 (2022/06/27)

v3.18 (2022/06/27)

v3.17 (2022/06/09)

v3.16 (2022/05/11)

  • Added Facebook ODAX objectives to Facebook Ads endpoint.
    ODAX stands for Outcome-driven ad experience. Objectives marked with ODAX reflect Facebook's new, simplified campaign objectives mapped to broader marketing goals.

v3.15 (2022/04/27)

v3.14 (2022/04/20)

  • Vkontakte data is no longer supported under
  • List of connected profiles no longer returns VK profiles

v3.13 (2022/04/20)

v3.12 (2022/02/16)

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

v3.11 (2022/01/20)

v3.10 (2021/10/05)

  • /3/facebook/page/posts
    • insights_engagements - new field for Engagements added. Learn more.
    • insights_reach_engagement_rate - calculation for this metrics has been upgraded. Learn More. The previous metric was resulting from Engaged Users divided by Reach.
    • insights_impressions_engagement_rate - new field for Impressions ER added. Learn more.
  • /3/instagram/profile/posts
    • insights_engagement - calculation for Engagements was upgraded. It now includes also Story Replies. Learn more.
    • insights_reach_engagement_rate - new field for Reach ER. Learn more.
    • insights_impressions_engagement_rate - new field for Impressions ER added. Learn more.
  • /3/youtube/profile/videos
    • insights_engagement - new field for Engagements added. Learn more.
  • /3/aggregated-metrics
    • insights_engagements - 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
    • insights_impressions_engagement_rate - new field for Impressions ER added. Learn more.

v3.9 (2021/09/17)

v3.8 (2021/08/23)

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

    • v3.7 (2021/07/13)

  • New Power BI Connector

    • v3.6 (2021/07/13)

  • Added a new Facebook Ads endpoint

    • v3.5 (2021/02/04)

  • New Google Data Studio & Tableau Connectors

    • v3.4.1 (2021/01/25)

  • Added a new Content Label Groups endpoint

    • v3.4 (2021/01/07)

  • Removed content_type and media_type from twitter tweets post endpoint to comply with Twitter T&Cs

    • v3.3 (2020/12/14)

  • Profiles limit for metrics request was increased from 25 to 100 profiles
  • Date range limit for metrics request was increased from 3 to 12 months
  • Profiles and date range limits are now enforced on posts endpoints

    • v3.2 (2020/11/26)

    • Added 2 new Facebook Post Metrics: insights_video_view_time_by_country and insights_video_view_time_by_gender_age
    • Introduced new Assets API to manage collections and assets
    • Redesigned the API documentation

    v3.1 (2020/10/29)

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

    v3.0 (2020/09/16)

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

    v2.17 (2024/03/27)

    • /2/facebook/metrics
      • Fixed support to historical data for deprecated Facebook metric + dimension combinations:
        • Dimension like_source + insights_fan_adds metric.
        • Dimension like_source + insights_fan_adds_unique metric.
        • Dimension unlike_source + insights_fans_lifetime metric.
        • Dimension gender_age + insights_fan_adds metric.
        • Dimension frequency_distribution + insights_post_reach metric.

    v2.16 (2024/03/07)

    • /2/facebook/metrics
    • /2/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
        • Additional deprecated metrics:
          • insights_activity
          • insights_activity_unique

    v2.15 (2024/02/28)

    • /2/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.
        • Combination of dimension and metric:
          • Dimension like_source + insights_fan_adds metric.
          • Dimension like_source + insights_fan_adds_unique metric.
          • Dimension unlike_source + insights_fans_lifetime metric.
          • Dimension gender_age + insights_fan_adds metric.
          • Dimension frequency_distribution + insights_post_reach metric.
        • Metrics:
          • insights_positive_feedback
          • insights_post_clicks
          • insights_reach_engagement
          • insights_engaged_users
          • insights_reactions

    v2.13 (2023/08/24)

    v2.12 (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 /2/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.

    v2.11 (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

    v2.10

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

    v2.9

    v2.8

    • Vkontakte data is no longer supported under
    • List of connected profiles no longer returns VK profiles

    v2.7

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

    v2.6

    v2.5

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

    v2.4

    • /2/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.
    • /2/instagram/profile/posts
      • insights_engagement - no longer supported. We have introduced a new version of the Engagements in the latest version of the API. This field will still be return for the time being.
    • /2/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

    v2.3

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

      • Affected endpoints:

    v2.2

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

    • v2.1

    v2.0

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

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