Emplifi API Documentation
Introduction
The Emplifi REST API allows access to the data points used in Emplifi suite. Access to the API is available on request for Emplifi clients only.
If you are interested in the API access, please contact our support team (support@emplifi.io).
Security and Authentication
The API is secured with HTTPS. Authentication is made using Basic HTTP Authorization by token and secret or by OAuth2.0 authorization framework. The authorization is sent in the HTTP headers.
Basic HTTP Authorization using token and secret
Basic HTTP Authorization uses a token and secret with a colon between them encoded to base64 format.
Example: if we use "Aladdin" as a token and "OpenSesame" as a secret, then "Aladdin:OpenSesame" produces "QWxhZGRpbjpPcGVuU2VzYW1l" when encoded to base64 format.
The parameter in the HTTP header would be then: Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l
The token and secret are linked to a specific user of a Emplifi Suite account. Get in touch with our Support team at support@emplifi.io to get yours.
Example request
GET /1/facebook/profiles HTTPS
Host: api.emplifi.io
Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l
Content-Type: application/json; charset=utf-8
Using OAuth 2.0 to access Emplifi API
Emplifi API uses the OAuth 2.0 framework to authorize users to make API request. Emplifi API supports the Oauth 2.0 Authorization code flow.
Before you begin create a new Custom integration in the Emplifi Settings.
OAuth2 endpoints are located at https://api.emplifi.io/oauth2/0/
.
The OAuth2 configuration is available at https://api.emplifi.io/oauth2/0/.well-known/openid-configuration.
How to get access to OAuth 2.0
OAuth 2.0 access has to be enabled by our support team, even if you have Emplifi API Integration purchased. Please send oAuth activation request to support@emplifi.io
OAuth2.0 Authorization code flow
Steps to get API access
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 Scopes requirements of each endpoint are shown in its documentation. |
state |
An opaque value that you can use to maintain state between the your authorization request and the authorization server's response.
The authorization server includes this value when redirecting the user-agent back to your app.
Your application should compare the locally stored state with the one sent back from the Emplifi API
to prevent CSRF attacks.
|
prompt |
Must be set to consent if the refresh token should be issued together with access token. |
When the user approves the request, the Emplifi API will redirect the user back to the redirect_uri
with an authorization code in the query string as "code".
Exchange authorization code for access token
Once you received authorization code from the previous step you can exchange it for access token and optionally refresh token.
To do so, you have to make POST request to the https://api.emplifi.io/oauth2/0/token
endpoint of the OAuth2 authorization server with the following Request Headers and Request Body information:
Request Header
Header | Value |
---|---|
Authorization |
Basic authentication where username is the Client ID and password the Client Secret. The string "Basic" with your Client ID and Client Secret separated with colon (:), Base64-encoded. For example, client_id:client_secret The final value is Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ= . |
Content-Type |
application/x-www-form-urlencoded |
Request Body
Parameter | Value |
---|---|
code |
The authorization code supplied to the callback URI from previous step. |
grant_type |
authorization_code |
redirect_uri |
Your application redirect URI. Has to be same URI as specified in authorization code request. In our example https://my-example-app.com/auth/callback . |
Response
Parameter | Value |
---|---|
access_token |
Access token to be used for accessing the Emplifi API. |
token_type |
Only supported type is bearer |
expires_in |
Access token expiration time in seconds. |
refresh_token |
Refresh token to be used for refreshing the access token.
Only present when scope contains offline_access .
|
scope |
Scopes that were granted by the user. Space delimited string. e.g. api.read offline_access |
Request URL to obtain the authorization code
https://api.emplifi.io/oauth2/0/auth?response_type=code&client_id={CLIENT_ID}&state=ed56BgdY64aswDC&redirect_uri=https%3A%2F%2Fmy-example-app.com%2Fauth%2Fcallback&scope=api.read%20offline_access&prompt=consent
The URL user is sent to after they approve the request
https://my-example-app.com/auth/callback?code=derfDST4r5sGNY_425sDW3wf&state=ed56BgdY64aswDC&iss=https://3348d0628f75ab43fe445e17eb650c1b.sbksapps.com
Request to exchange authorization code for access token
curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic Y1xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
-d "grant_type=authorization_code&code=derfDST4r5sGNY_425sDW3wf&redirect_uri=https://my-example-app.com/auth/callback"
https://api.emplifi.io/oauth2/0/token
Example response with the access_token and refresh_token
{
"access_token": "Imu6FyXyiATtf529qX5QsbZeamylWlg5wM50KingLoM",
"token_type": "bearer",
"refresh_token": "C8DEVlA-RuOlRhKiyvvWLQlc0cNZ2wk1K5uySKey7Yw",
"expires_in": 7200,
"scope": "api.read offline_access"
}
Full example using passport and passport-oauth2 NPM packages to get an access_token (Javascript)
const passport = require('passport')
const OAuth2Strategy = require('passport-oauth2')
const express = require('express')
const session = require('express-session')
const fetch = require('node-fetch')
const app = express()
app.use(
session({
secret: 'example_app_session_secret',
resave: false,
saveUninitialized: true,
})
)
const EmplifiStrategy = new OAuth2Strategy(
{
authorizationURL: 'https://api.emplifi.io/oauth2/0/auth',
tokenURL: 'https://api.emplifi.io/oauth2/0/token',
clientID: 'CLIENT_ID',
clientSecret:
'CLIENT_SECRET',
callbackURL: 'http://localhost:3000/auth/example/callback',
},
async function verify(accessToken, refreshToken, profile, next) {
const userInfoResponse = await fetch('https://api.emplifi.io/1/user/me', {
headers: {
Authorization: `Bearer ${accessToken}`,
},
})
if (userInfoResponse.status !== 200) {
const { statusText, status } = userInfoResponse
next(
new Error(`Failed to fetch user information ${status} - ${statusText}`)
)
}
const userInfo = await userInfoResponse.json()
// find the user in your application based on the received data and pass it to the next
next(null, { accessToken, refreshToken, user: userInfo.userInfo })
}
)
// when offline_access scope is requested, the prompt parameter is required to be set to consent
EmplifiStrategy.authorizationParams = function (options) {
return {
...options,
prompt: 'consent',
}
}
app.use(passport.session())
app.use(passport.initialize())
passport.use('emplifi', EmplifiStrategy)
passport.serializeUser((user, next) => next(null, user))
passport.deserializeUser((id, next) => next(null, id))
app.get(
'/auth/example',
passport.authenticate('emplifi', {
// offline_access is necessary to receive refresh_token. Required scopes are listed in the Emplifi API documentation
scope: ['api.read', 'offline_access'],
})
)
app.get(
'/auth/example/callback',
passport.authenticate('emplifi', { failureRedirect: '/failed' }),
function (req, res) {
// Successful authentication, redirect home.
res.redirect('/')
}
)
app.get('/failed', (req, res) => {
res.send('Failed to authenticate')
})
app.get('/', (req, res) => {
if (req.user) {
res.send(req.user)
} else {
res.send("<a href='/auth/example'>Login</a>")
}
})
app.listen(3000, () => {
console.log('Server is running on port 3000')
})
Using the access token
Send request to Emplifi API with access_token
in HTTP authorization
header.
"Authorization": "Bearer <ACCESS_TOKEN>"
An access token is a randomly generated string with a minimum length of 43 characters. It should be stored safely and used exclusively for secure communication between Emplifi and Custom Integration. The access token is valid for 30 days and needs to be refreshed.
cURL request example
curl -X GET \
-H "Authorization: Bearer Imu6FyXyiATtf519qX5QsbZeamylWlg5wM50KingLoM" \
-H "Content-Type: application/json; charset=utf-8" \
https://api.emplifi.io/1/facebook/profiles
Access token refreshing
The access token live time is limited. Refer to expires_in
property of the exchange authorization code to access token.
Once access token expires, you will have to refresh it by using refresh token.
The refresh token is returned by https://api.emplifi.io/oauth2/0/token
endpoint if the scope
property of the /auth
endpoint contains offline_access
.
To refresh access token make POST
request to /token
endpoint with following Request header and Request body.
Request Header
Header | Value |
---|---|
Authorization |
Basic authentication where username is the Client ID and password the Client Secret.
The string "Basic" with your Client ID and Client Secret separated with colon (:), Base64-encoded. For example, client_id:client_secret The final value is Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ= .
|
Content-Type |
application/x-www-form-urlencoded |
Request Body
Parameter | Value |
---|---|
refresh_token |
The refresh token obtained when asking for access token in step 3. In our example C8DEVlA-RuOlRhKiyvvWLQlc0cNZ1wk1K5uySKey7Yw |
grant_type |
refresh_token |
Refresh token expires in 180 days.
cURL request example
curl -X POST \
-H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token&refresh_token=C8DEVlA-RuOlRhKiyvvWLQlc0cNZ1wk1K5uySKey7Yw" \
https://api.emplifi.io/oauth2/0/token
Example response
{
"access_token": "JWefwbpGr3PJyBJjGP3DMaLe5ooX75StcfEb7bgaosn",
"expires_in": 7200,
"refresh_token": "C8DEVlA-RuOlRhKiyvvWLQlc0cNZ1wk1K5uySKey7Yw",
"scope": "api offline_access",
"token_type": "Bearer"
}
Access token revoking
To revoke access token, make a POST
request to
https://api.emplifi.io/oauth2/0/token/revocation
endpoint with following request headers and request body.
Request Header
Header | Value |
---|---|
Authorization |
Basic authentication where username is the Client ID and password the Client Secret.
The string "Basic" with your Client ID and Client Secret separated with colon (:), Base64-encoded. For example, client_id:client_secret The final value is Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ= .
|
Content-Type |
application/x-www-form-urlencoded |
Request Body
Parameter | Value |
---|---|
token |
The access token to be revoked. In our example JWefwbpGr3PJyBJjGP3DMaLe5ooX75StcfEb7bgaosn |
The OAuth2 provider will always response with HTTP status 200
.
cURL request example
curl -X POST \
-H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=JWefwbpGr3PJyBJjGP3DMaLe5ooX75StcfEb7bgaosn" \
https://api.emplifi.io/oauth2/0/token/revocation
Limits
Rate limits are defined for account and for user:
- Account: 1000 requests per hour
- User: 500 requests per hour
Each metrics request is limited by maximum number of:
- Profiles: 25
- Metrics: 25
- Date range: 3 months
If you need to query with more profiles, metrics or date range than the limits allow, you can split it into multiple requests.
Sometimes, your request may return Complexity error (code:4)
even if you did not reach any of the limits. This is because the amount of data to return is too large. Try to split your request into multiple smaller ones.
Date range is not relative to current date, so you are able to query historical data.
The oldest historical data you are able to request for is limited by your subscription package.
Rate limit headers with Oauth 2.0 Authorization
When using Oauth 2.0 Authorization, each request to the API will additionally return the following headers to let you know the current state of your quota usage:
HTTP/1.1 200 OK X-RateLimit-Limit: 500, 500;window=3600, 1000;window=3600 X-RateLimit-Remaining: 20 X-RateLimit-Reset: 1201
The X-RateLimit-Limit
header contains the maximum number of requests
you are permitted to make.
There can be multiple entries separated by comma followed by space (,
) in the header.
- The entry is always a number and contains the lowest number of requests you can make for this resource in the current window.
- Starting with the second entry each entry corresponds to a limit that affects this resource.
It is always in format
number_of_requests;window=size_of_the_window_in_seconds
. e.g.500;window=3600
means 500 requests can be made every hour (3600 seconds)
The X-RateLimit-Remaining
header tells you how many requests you have
left to use in the current window.
The X-RateLimit-Reset
header tells you how many seconds until the
current window resets.
The example above shows that the current window resets in 1201 seconds and you can make 20 more requests until then. It also shows that the called endpoint is subject to 2 different limits: one with 500 calls every 3600 seconds and one with 1000 calls every 3600 seconds. It also shows that the closest limit to be hit is the one with 500 calls per 3600 seconds.
Requests failing with status code 429 Too Many Requests
When the number of allowed requests gets exceeded the response
will contain additional header Retry-After
with the number of seconds
until the current window resets.
HTTP/1.1 429 Too Many Requests X-RateLimit-Limit: 500, 500;window=3600, 1000;window=3600 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 800 Retry-After: 800
Errors
If error occurs in any endpoint, standardized error response will be returned.
Error codes
Code | Endpoint | Description | HTTP Status Code |
---|---|---|---|
3 | all |
Input validation error | 200 |
4 | all |
Profiles, metrics or date range limit exceeded | 200 |
5 | all |
Profiles not allowed for user | 200 |
6 | all |
Start date is before history limit date | 200 |
7 |
POST /1/facebook/metrics
|
Profiles do not have insights enabled | 200 |
8 | all |
Labels used for filtering do not exists | 200 |
10 | all |
Account request limit exceeded | 200 |
11 | all |
User request limit exceeded | 200 |
13 | all |
Labeled content or conversation does not exist in Community. | 200 |
99 | all |
An unknown error occurred | 200 |
400 | all |
Bad request | 400 |
401 | all |
Missing authorization header, invalid secret or token | 401 |
403 | all |
Action is not permitted | 403 |
404 | all |
Resource not allowed | 404 |
405 | all |
HTTP method not allowed | 405 |
500 | all |
Internal server error | 500 |
Example response
{
"success": false,
"errors": [
{
"code": 3,
"errors": [
"Input validation error.",
"Invalid metrics requested: metric1"
]
},
{
"code": 5,
"errors": [
"Profiles not allowed for user.",
"Profiles [164929129743] not allowed."
]
}
]
}
Pagination
Endpoints that support pagination have the limit
parameter available. It is used to specify how
many results you want to get in the response.
When the response contains remaining
and next
keys, more data is available using
pagination.
The key remaining
contains the number of items that are available after the last item in the
response.
The key next
is used as a parameter for the next page.
To request the next page, all parameters from previous request need to be sent along with parameter after
set to value of the next
key from the previous response.
Example request
POST /1/facebook/page/posts HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"profiles": ["164929129743", "354335677"],
"date_start": "2010-01-01",
"date_end": "2016-10-25",
"fields": ["id"],
"limit": 5
}
Example response
{
"success": true,
"data": {
"posts": [
{
"id": "164929129743_10154736430664744"
}, ...
],
"next": "eyJjdXJzb3IiOlt7ImZpZWxkIjoiY3JlYXRlZF90aW1lIiwidmFsdWUiOiIyMDE2LTEwLTI1VDEzOjAwOjA2LjAwMFoiLCJvcmRlciI6ImRlc2MifV0sImlkcyI6WyIxNjQ5MjkxMjk3NDNfMTAxNTQ3MDUwODA3Mzk3NDQiXX0=",
"remaining": 3276
}
}
Next page request
POST /1/facebook/page/posts HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"profiles": ["164929129743", "45674325789"],
"date_start": "2010-01-01",
"date_end": "2016-10-25",
"fields": ["id"],
"limit": 5,
"after": "eyJjdXJzb3IiOlt7ImZpZWxkIjoiY3JlYXRlZF90aW1lIiwidmFsdWUiOiIyMDE2LTEwLTI1VDEzOjAwOjA2LjAwMFoiLCJvcmRlciI6ImRlc2MifV0sImlkcyI6WyIxNjQ5MjkxMjk3NDNfMTAxNTQ3MDUwODA3Mzk3NDQiXX0="
}
Reference Data
Lists of values allowed to be used by other endpoints as data sources or filters.
List of Connected Profiles
Returns the list of connected Facebook, Instagram, Twitter, YouTube or Pinterest profiles for your account. You will need the profile ID later to call metrics endpoints.
Response fields
Name | Description |
---|---|
id | string , profile unique identifier on the social network. |
name | string , profile name |
profile_name | string , profile unique name on the social network. |
picture | string , profile picture on the social network. |
timezone | string , timezone selected for this profile in Emplifi product. |
profile_labels | array , list of labels assigned to a given profile in the account. |
insights_enabled | boolean , available for facebook and instagram networks only, true
if insights metrics are available for profile. |
community_enabled | boolean , true if community content is available for profile. |
Example request
GET /1/{network}/profiles HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
Supported values for {network}
: facebook
, instagram
, twitter
,
youtube
, pinterest
Example response
{
"success": true,
"profiles": [
{
"id": "164929129743",
"name": "Profile #1 name",
"profile_name": "profile1name",
"picture": "https://example.cdn.com/picture.hash.png",
"timezone": "America/Los_Angeles",
"insights_enabled": true
},
{
"id": "477018229123929",
"name": "Profile #2 name",
"picture": "https://example.cdn.com/picture.hash.png",
"profile_name": "profile2name",
"timezone": "Europe/Prague",
"community_enabled": true
},
...
]
}
List of Content Labels
Content labels are used to label content (posts, videos) across multiple platforms in Suite. The endpoint returns the list of all private, global, and shared content labels visible to your user in your account. These labels are identified by name and ID.
You can use the content label IDs to filter the posts or the results of the aggregated post metrics.
Response fields
Name | Description |
---|---|
id | string , content label unique identifier |
name | string , content label name |
Example request
POST /1/post/labels HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
Example response
{
"success": true,
"data": [
{
"id": "5d879004a44a4cbcb13e",
"name": "Content Label 1"
},
{
"id": "ffc196eb056b42fd9b03",
"name": "Content Label 2"
},
...
]
}
Profile Metrics
Profile metrics endpoints return daily values for the specified set of metrics and profiles.
Profile metrics attribute data to the profile/page, focusing on when engagement happened, regardless if a post was published during the analyzed date range or not. Data is aggregated by when it happened, and it is not related to a specific piece of content.
Facebook Metrics
Returns daily metrics for each requested Facebook profile.
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
The response uses a timezone assigned to a profile in Suite settings of the account.
The last day will be also included in the response.
|
profiles | object , the list of string values. Each is ID of the profile available
from the /1/facebook/profiles endpoint. |
metrics | object , the list of metrics that will be returned in the response. Available metrics are
listed in the table below. |
Basic Metrics
Name | Type | Example | Description |
---|---|---|---|
comments |
integer
|
|
Number of comments on page posts. |
comments_by_ppd_status |
object
|
|
Number of comments on page posts by paid status (organic/paid/unknown) based on PPD. |
comments_by_type |
object
|
|
Number of comments on page posts by post type. |
engagement_rate |
float
|
|
Engagement Rate displays the average number of Interactions per Fan per Post. Engagement Rate is therefore calculated by dividing the number of Interactions of posts published a particular day by the number of Fans on that day and finally by the number of posts on that day. The final Engagement Rate figure is multiplied by 100 and should be displayed as a percentage (Interactions / Fans / Posts * 100). The Engagement Rate for a time period should be calculated as the average of all the Engagement Rate values for all of the days that are being examined. |
fans_change |
integer
|
|
Absolute change of fans count of a page. |
fans_lifetime |
integer
|
|
Total number of likes (=fans) of a page. |
interactions |
integer
|
|
Number of interactions on page posts. |
interactions_by_ppd_status |
object
|
|
Number of interactions on page posts by paid status (organic/paid/unknown) based on PPD. |
interactions_by_type |
object
|
|
Number of interactions on page posts by post type. |
interactions_per_1000_fans |
float
|
|
Number of interactions per thousand fans. |
interactions_per_1000_fans_by_type |
object
|
|
Number of interactions per thousand fans by type. |
page_posts |
integer
|
|
Number of page posts. |
page_posts_by_app |
object
|
|
Number of page posts by application via it was posted (any facebook app is "web"). |
page_posts_by_ppd_status |
object
|
|
Number of page posts by paid status (organic/paid/unknown) based on PPD. |
page_posts_by_type |
object
|
|
Number of page posts by post type. |
reactions |
integer
|
|
Number of reactions on page posts. |
reactions_by_ppd_status |
object
|
|
Number of reactions on page posts by paid status (organic/paid/unknown) based on PPD. |
reactions_by_reaction_type |
object
|
|
Number of reactions on page posts by reaction type (like, love, haha, etc...). |
reactions_by_type |
object
|
|
Number of reactions on page posts by post type. |
shares |
integer
|
|
Number of shares on page posts. |
shares_by_ppd_status |
object
|
|
Number of shares on page posts by paid status (organic/paid/unknown) based on PPD. |
shares_by_type |
object
|
|
Number of shares on page posts by post type. |
user_posts |
integer
|
|
Number of user posts. |
user_posts_average_response_time |
integer
|
|
Average reponse time (mins) of responded user posts. |
user_posts_by_app |
object
|
|
Number of user posts by application via it was posted (any facebook app is "web"). |
user_posts_responded |
integer
|
|
Number of user posts that are responded (at least 1 page comment). |
user_posts_responded_by_time |
object
|
|
Number of responded user posts by response time category. |
user_posts_response_rate |
float
|
|
Ratio of user posts and responded user posts. |
user_questions |
integer
|
|
Number of user posts that are marked as a question. |
user_questions_average_response_time |
integer
|
|
Average reponse time (mins) of responded user questions. |
user_questions_responded |
integer
|
|
Number of user posts that are marked as a question and that are responded (at least 1 page comment). |
user_questions_responded_by_time |
object
|
|
Number of responded user questions by response time category. |
user_questions_response_rate |
float
|
|
Ratio of user questions and responded user questions. |
Insights Metrics
Metrics prefixed with insights_
can only be used for profiles that have insights_enabled
property set to true
in the response of the /1/facebook/profiles
endpoint.
Name | Type | Example | Description |
---|---|---|---|
insights_fan_adds |
integer
|
|
Number of new people who have liked your Page. |
insights_fan_adds_by_paid_non_paid_unique |
object
|
|
New likes by paid and non-paid : Number of new people who have liked your page broken down by paid and non-paid. (Unique Users) |
insights_fan_adds_unique |
integer
|
|
New Likes : Number of new people who have liked your Page (Unique Users) |
insights_fan_removes |
integer
|
|
Number of Unlikes of your Page (Total Count) |
insights_fan_removes_unique |
integer
|
|
Number of Unlikes of your Page (Unique Users) |
insights_fans_by_like_source |
object
|
|
Breakdown of Number of Page likes from the most common places where people can like your Page. (Total Count) |
insights_fans_by_like_source_unique |
object
|
|
Number of people who liked your Page, broken down by the most common places where people can like your Page. (Unique Users) |
insights_fans_by_unlike_source_unique |
object
|
|
Number of people who unliked your Page, broken down by the most common places where people can unlike your Page. (Unique Users) |
insights_fans_city |
object
|
|
Aggregated location data, sorted by city, number of people who like your Page. (Unique Users) |
insights_fans_lifetime |
integer
|
|
Number of people who have liked your Page. (Unique Users) |
insights_fans_lifetime_by_country |
object
|
|
Lifetime value of number of fans grouped by country. |
insights_fans_locale_lifetime |
object
|
|
Aggregated language data about the people who like your Page based on the default language setting selected when accessing Facebook. (Unique Users) |
insights_fans_online |
integer
|
|
Number of people who liked your Page and when they are online (Unique Users) |
insights_fans_online_by_hour |
object
|
|
Number of your fans who saw any posts on Facebook on a given day, broken down by hour of day in PST (Pacific Standard Time) |
insights_impressions |
integer
|
|
Number of impressions seen of any content associated with your Page. (Total Count) |
insights_impressions_by_paid_non_paid |
object
|
|
Number of impressions seen of any content associated with your page broken down by paid and non-paid. (Total Count) |
insights_impressions_organic |
integer
|
|
Number of times your posts were seen in News Feed or ticker or on visits to your Page. These impressions can be by people who have liked your Page and people who haven't. (Total Count) |
insights_impressions_paid |
integer
|
|
Number of impressions of a Sponsored Story or Ad pointing to your Page. (Total Count) |
insights_impressions_viral |
integer
|
|
Number of impressions of an activity published by a friend about your Page. These activities include liking your Page, posting to your page's Wall, liking, commenting on or sharing one of your Page posts, answering a Question you posted, RSVPing to one of your events, mentioning your Page, phototagging your Page or checking in at your Place. (Total Count) |
insights_impressions_viral_frequency_distribution |
object
|
|
Number of people your Page reached from a story published by a friend, broken down by how many times people saw activities about your Page. (Unique Users) |
insights_negative_feedback |
integer
|
|
Number of times people have given negative feedback to your Page. (Total Count) |
insights_post_clicks_unique |
integer
|
|
Number of people who clicked on any of your content. Clicks that create activity are included in "Other Clicks." Activities that are created without clicking on Page content (ex, liking the Page from timeline) are not included. (Unique Users) |
insights_post_clicks_unique_by_type |
object
|
|
Number of of people who clicked on any of your content, by type. Clicks that create activity are included in "Other Clicks." Activities that are created without clicking on Page content (ex, liking the Page from timeline) are not included. (Unique Users) |
insights_post_impressions |
integer
|
|
Number of impressions that came from all of your posts. (Total Count) |
insights_post_impressions_by_paid_non_paid |
object
|
|
Number of impressions that came from all of your posts broken down by paid and non-paid. (Total Count) |
insights_post_impressions_frequency_distribution |
object
|
|
Number of people who saw your Page posts, broken down by how many times people saw your posts. (Unique Users) |
insights_post_impressions_paid |
integer
|
|
Number of impressions of your Page posts in an Ad or Sponsored Story. (Total Count) |
insights_post_reach |
integer
|
|
Number of people who saw any of your Page posts. (Unique Users) |
insights_post_reach_by_paid_non_paid |
object
|
|
Number of impressions that came from all of your posts broken down by paid and non-paid. (Unique Users) |
insights_post_reach_organic |
integer
|
|
Number of people who saw your Page posts in news feed or ticker, or on your Page's timeline. (Unique Users) |
insights_post_reach_paid |
integer
|
|
Number of people who saw your Page posts in an ad or sponsored story. (Unique Users) |
insights_reach |
integer
|
|
Number of people who have seen any content associated with your Page. (Unique Users) |
insights_reach_by_age_gender |
object
|
|
Total Page Reach by age and gender. (Unique Users) |
insights_reach_by_paid_non_paid |
object
|
|
Number of impressions seen of any content associated with your page broken down by paid and non-paid. (Unique Users) |
insights_reach_organic |
integer
|
|
Number of people who visited your Page, or saw your Page or one of its posts in news feed or ticker. These can be people who have liked your Page and people who haven't. (Unique Users) |
insights_reach_paid |
integer
|
|
Number of people who saw a sponsored story or ad pointing to your Page. (Unique Users) |
insights_reach_viral |
integer
|
|
Number of people who saw your Page or one of its posts from a activity shared by a friend. These activities include liking your Page, posting to your page's timeline, liking, commenting on or sharing one of your Page posts, answering a question you posted, responding to one of your events, mentioning your Page, tagging your Page in a photo or checking in at your location. (Unique Users) |
insights_reactions |
integer
|
|
Number of reactions on any of your content. |
insights_reactions_by_type |
object
|
|
Number of reactions on any of your content by type. |
insights_video_complete_views_30s |
integer
|
|
Number of times page's videos have been viewed for more than 30 seconds |
insights_video_complete_views_30s_autoplayed |
integer
|
|
Number of times page's autoplayed videos have been viewed for more than 30 seconds |
insights_video_complete_views_30s_click_to_play |
integer
|
|
Number of times page's videos have been viewed after the user clicks on play for more than 30 seconds |
insights_video_complete_views_30s_organic |
integer
|
|
Number of times page's videos have been viewed for more than 30 seconds by organic reach |
insights_video_complete_views_30s_repeat_views |
integer
|
|
Number of times that people replay a page's videos for more than 30 seconds |
insights_video_complete_views_30s_unique |
integer
|
|
Number of times page's videos have been played for unique people for more than 30 seconds |
insights_video_repeat_views |
integer
|
|
Number of times that people replay a page's videos for more than 3 seconds |
insights_video_views |
integer
|
|
Number of times page's videos have been viewed for more than 3 seconds |
insights_video_views_autoplayed |
integer
|
|
Number of times page's autoplayed videos have been viewed for more than 3 seconds |
insights_video_views_click_to_play |
integer
|
|
Number of times page's videos have been viewed after the user clicks on play for more than 3 seconds |
insights_video_views_organic |
integer
|
Number of times page's videos have been viewed for more than 3 seconds by organic reach | |
insights_video_views_paid |
integer
|
|
Number of times page's promoted videos have been viewed for more than 3 seconds |
insights_video_views_unique |
integer
|
|
Number of times page's videos have been played for unique people for more than 3 seconds |
insights_views |
integer
|
|
Page views (Total Count) |
Example request
POST /1/facebook/metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"date_start": "2016-01-01",
"date_end": "2016-01-02",
"profiles": ["164929129743", "477018229123929"],
"metrics": ["fans_lifetime", "fans_change", ...]
}
Example response
{
"success": true,
"profiles": [
{
"id": "164929129743",
"data": [
{
"date": "2016-01-01 00:00:00",
"fans_lifetime": 123456,
"fans_change": 123,
...
},
{
"date": "2016-01-02 00:00:00",
"fans_lifetime": 654321,
"fans_change": 654,
...
}
]
},
{
"id": "477018229123929",
"data": [
{
"date": "2016-01-01 00:00:00",
"fans_lifetime": 111222,
"fans_change": 1122,
...
},
{
"date": "2016-01-02 00:00:00",
"fans_lifetime": 222111,
"fans_change": 2211,
...
}
]
}
]
}
Instagram Metrics
Returns daily metrics for each requested Instagram profile.
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
The response uses a timezone assigned to a profile in Suite settings of the account.
The last day will be also included in the response.
|
profiles | The list of string values. Each is ID of the profile available from the /1/instagram/profiles endpoint. |
metrics | The list of metrics that will be returned in the response. Available metrics are listed in the table below. |
Basic Metrics
Name | Type | Example | Description |
---|---|---|---|
comments |
integer
|
|
Number of comments of profile posts. |
comments_by_image_filter
No longer supported
|
object
|
|
Number of comments of profile posts by used image filter of that post. |
comments_by_type |
object
|
|
Number of comments of profile posts by post type. |
comments_by_video_filter
No longer supported
|
object
|
|
Number of comments of profile posts by used video filter of that post. |
engagement_rate |
float
|
|
Engagement Rate displays the average number of Interactions per Fan per Post. Engagement Rate is therefore calculated by dividing the number of Interactions of posts published a particular day by the number of Fans on that day and finally by the number of posts on that day. The final Engagement Rate figure is multiplied by 100 and should be displayed as a percentage (Interactions / Fans / Posts * 100). The Engagement Rate for a time period should be calculated as the average of all the Engagement Rate values for all of the days that are being examined. |
followers_change |
integer
|
|
Absolute change of followers count lifetime. |
followers_lifetime |
integer
|
|
Followers count - lifetime value. |
following_change |
integer
|
|
Absolute change of following count lifetime. |
following_lifetime |
integer
|
|
Following count - lifetime value. |
interactions |
integer
|
|
Number of interactions (likes and comments) of profile posts. |
interactions_by_image_filter
No longer supported
|
object
|
|
Number of interactions of profile posts by used image filter of that post. |
interactions_by_type |
object
|
|
Number of interactions of profile posts by post type. |
interactions_by_video_filter
No longer supported
|
object
|
|
Number of interactions of profile posts by used video filter of that post. |
interactions_per_1000_followers |
float
|
|
Number of interactions (likes and comments) per thousand followers. |
interactions_per_1000_followers_by_image_filter
No longer supported
|
object
|
|
Number of interactions (likes and comments) per thousand followers by used image filter. |
interactions_per_1000_followers_by_type |
object
|
|
Number of interactions (likes and comments) per thousand followers by used post type. |
interactions_per_1000_followers_by_video_filter
No longer supported
|
object
|
|
Number of interactions (likes and comments) per thousand followers by used video filter. |
likes |
integer
|
|
Number of likes of profile posts. |
likes_by_image_filter
No longer supported
|
object
|
|
Number of likes of profile posts by used image filter of that post. |
likes_by_post_type |
object
|
|
Number of likes of profile posts by post type. |
likes_by_video_filter
No longer supported
|
object
|
|
Number of likes of profile posts by used video filter of that post. |
profile_posts |
integer
|
|
Number of profile posts. |
profile_posts_by_image_filter
No longer supported
|
object
|
|
Number of profile posts by used image filter of that post. |
profile_posts_by_type |
object
|
|
Number of profile posts by post type. |
profile_posts_by_video_filter
No longer supported
|
object
|
|
Number of profile posts by used video filter of that post. |
Insights Metrics
Metrics prefixed with insights_
can only be used for profiles that have insights_enabled
property set to true
in the response of the /1/instagram/profiles
endpoint.
Name | Type | Example | Description |
---|---|---|---|
insights_followers_by_city_by_day |
object
|
|
The cities of the Business Account's followers. |
insights_followers_by_country_by_day |
object
|
|
The countries of the Business Account's followers. |
insights_followers_by_gender_by_age_by_day |
object
|
|
The gender and age distribution of the Business Account's followers. |
insights_post_engagement_by_day |
integer
|
|
Total number of likes and comments on the posts. |
insights_post_engagement_by_type_by_day |
object
|
|
Total engagement (likes and comments) broken down by post type (video, carousel album, carousel, image). |
insights_post_impressions_by_day |
integer
|
|
The number of times posts have been seen. |
insights_post_impressions_by_type_by_day |
object
|
|
The number of times posts have been seen, broken down by post type. |
insights_post_interactions_by_day |
integer
|
|
The number of Likes, Comments and Saves posts received. The data source of this chart is different from the post_engagement. As a result, the number of interactions may vary. |
insights_post_interactions_by_int_type_by_day |
object
|
|
The number of Likes, Comments and Saves posts received, broken down by the type of Interactions. The data source of this chart is different from the post_engagement. As a result, the number of interactions may vary. |
insights_post_saves_by_day |
integer
|
|
Total number of saves on the posts. |
insights_post_saves_by_type_by_day |
object
|
|
Total number of saves broken down by post type (video, carousel album, carousel, image). |
insights_post_video_views_by_day |
integer
|
|
The number of times videos have been viewed. |
insights_post_video_views_by_type_by_day |
object
|
|
The number of times videos have been viewed, broken down by video type. |
insights_profile_all_clicks_by_day |
integer
|
|
The number of times user clicked on a specific contact on your Business Account's profile. |
insights_profile_email_contacts_by_day |
integer
|
|
Total number of taps on the email link in the Business Account's profile. |
insights_profile_get_directions_clicks_by_day |
integer
|
|
Total number of taps on the directions link in the Business Account's profile. |
insights_profile_impressions_by_day |
integer
|
|
Total number of times the Business Account's media objects (i.e. posts, stories and promotions) have been viewed. Does not include profile views. |
insights_profile_phone_call_clicks_by_day |
integer
|
|
Total number of taps on the call link in the Business Account's profile. |
insights_profile_reach_by_day |
integer
|
|
Unique Impressions (Reach) refers to the number of different people who see your post. One person can see your post 5 times but is only counted once toward Reach. |
insights_profile_text_message_clicks_by_day |
integer
|
|
Total number of taps on the text message link in the Business Account's profile. |
insights_profile_views_by_day |
integer
|
|
Total number of unique users who have viewed the Business Account's profile. |
insights_profile_website_clicks_by_day |
integer
|
|
Total number of taps on the website link in the Business Account's profile. |
Example request
POST /1/instagram/metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"date_start": "2016-01-01",
"date_end": "2016-01-02",
"profiles": ["4108894671", "337453282"],
"metrics": ["followers_lifetime", "followers_change", ...]
}
Example response
{
"success": true,
"profiles": [
{
"id": "4108894671",
"data": [
{
"date": "2016-01-01 00:00:00",
"followers_lifetime": 123456,
"followers_change": 123,
...
},
{
"date": "2016-01-02 00:00:00",
"followers_lifetime": 654321,
"followers_change": 654,
...
}
]
},
{
"id": "337453282",
"data": [
{
"date": "2016-01-01 00:00:00",
"followers_lifetime": 111222,
"followers_change": 1122,
...
},
{
"date": "2016-01-02 00:00:00",
"followers_lifetime": 222111,
"followers_change": 2211,
...
}
]
}
]
}
Twitter Metrics
Returns daily metrics for each requested Twitter profile.
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
The response uses a timezone assigned to a profile in Suite settings of the account.
The last day will be also included in the response.
|
profiles | The list of string values. Each is ID of the profile available from the /1/twitter/profiles endpoint. |
metrics | The list of metrics that will be returned in the response. Available metrics are listed in the table below. |
Metrics
Name | Type | Example | Description |
---|---|---|---|
engagement_rate |
float
|
|
Engagement Rate displays the average number of Interactions per Fan per Post. Engagement Rate is therefore calculated by dividing the number of Interactions of posts published a particular day by the number of Fans on that day and finally by the number of posts on that day. The final Engagement Rate figure is multiplied by 100 and should be displayed as a percentage (Interactions / Fans / Posts * 100). The Engagement Rate for a time period should be calculated as the average of all the Engagement Rate values for all of the days that are being examined. |
ff_ratio |
float
|
|
Absolute change of following count lifetime. |
followers_change |
integer
|
|
Absolute change of followers count lifetime. |
followers_lifetime |
integer
|
|
Followers count - lifetime value. |
following_change |
integer
|
|
Absolute change of following count lifetime. |
following_lifetime |
integer
|
|
Following count - lifetime value. |
incoming |
integer
|
|
Number of all incoming activities (mentions + retweets + replies) created by others mentioning this profile. |
incoming_questions |
integer
|
|
Number of user tweets that are also marked as a question. |
incoming_questions_average_response_time |
float
|
|
Average reponse time (mins) of responded user questions. |
incoming_questions_responded |
integer
|
|
Number of user tweets that are marked as a question and that are responded (profile reply). |
incoming_questions_responded_by_time |
object
|
|
Number of responded user questions by response time category. |
incoming_questions_response_rate |
float
|
|
Ratio of user questions and responded user questions. |
incoming_replies |
integer
|
|
Number of replies made by others. |
incoming_retweets |
integer
|
|
Number of retweets made by others. |
incoming_tweets |
integer
|
|
Number of user tweets. User tweet is considered any incoming activity (mention, reply), exluding retweets. |
incoming_tweets_average_response_time |
float
|
|
Average reponse time (mins) of responded user tweets. |
incoming_tweets_responded |
integer
|
|
Number of user tweets that are responded (profile reply). |
incoming_tweets_responded_by_time |
object
|
|
Number of responded user tweets by response time category. |
incoming_tweets_response_rate |
float
|
|
Ratio of user tweets and responded user tweets. |
interactions |
integer
|
|
Number of interactions on profile tweets and replies. |
interactions_per_1000_followers |
float
|
|
Number of interactions per thousand followers. |
likes |
integer
|
|
Number of likes on profile tweets and replies. |
listed_change |
integer
|
|
Absolute change of listed count lifetime. |
listed_lifetime |
integer
|
|
Listed count - lifetime value (how many times profile has been listed). |
profile_activities |
integer
|
|
Number of all activities (tweets + retweets + replies) created by the profile. |
profile_activities_by_app |
object
|
|
Number of all activities posted by profile by application via it was posted. |
profile_replies |
integer
|
|
Number of replies made by profile. |
profile_retweets |
integer
|
|
Number of retweets made by profile. |
profile_tweets |
integer
|
|
Number of tweets made by profile. |
replies |
integer
|
|
Number of replies on profile tweets and replies. |
retweets |
integer
|
|
Number of retweets on profile tweets and replies. |
Example request
POST /1/twitter/metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"date_start": "2016-01-01",
"date_end": "2016-01-02",
"profiles": ["78569316", "3311741584"],
"metrics": ["followers_lifetime", "followers_change", ...]
}
Example response
{
"success": true,
"profiles": [
{
"id": "78569316",
"data": [
{
"date": "2016-01-01 00:00:00",
"followers_lifetime": 123456,
"followers_change": 123,
...
},
{
"date": "2016-01-02 00:00:00",
"followers_lifetime": 654321,
"followers_change": 654,
...
}
]
},
{
"id": "3311741584",
"data": [
{
"date": "2016-01-01 00:00:00",
"followers_lifetime": 111222,
"followers_change": 1122,
...
},
{
"date": "2016-01-02 00:00:00",
"followers_lifetime": 222111,
"followers_change": 2211,
...
}
]
}
]
}
YouTube Metrics
Returns daily metrics for each requested YouTube profile.
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
The response uses a timezone assigned to a profile in Suite settings of the account.
The last day will be also included in the response.
|
profiles | The list of string values. Each is ID of the profile available from the /1/youtube/profiles endpoint. |
metrics | The list of metrics that will be returned in the response. Available metrics are listed in the table below. |
Metrics
Name | Type | Example | Description |
---|---|---|---|
comments_change |
integer
|
|
Absolute change of comments count on uploaded videos. |
dislikes_change |
integer
|
|
Absolute change of dislikes count on uploaded videos. Dislike count is no longer available as of December 13, 2021 Learn more |
engagement_rate |
float
|
|
Engagement Rate displays the average number of Interactions per Fan per Post. Engagement Rate is therefore calculated by dividing the number of Interactions of posts published a particular day by the number of Fans on that day and finally by the number of posts on that day. The final Engagement Rate figure is multiplied by 100 and should be displayed as a percentage (Interactions / Fans / Posts * 100). The Engagement Rate for a time period should be calculated as the average of all the Engagement Rate values for all of the days that are being examined. Dislike count is no longer available for this metric as of December 13, 2021 Learn more. |
interaction_change |
integer
|
|
Absolute change of interactions (likes + dislikes + comments) count on uploaded videos. Dislike count is no longer available for this metric as of December 13, 2021 Learn more. |
interactions_per_1000_subscribers |
float
|
|
Daily growth of interactions per thousand subscribers on all uploaded videos by the channel on a given day. Number is aggregated by day to the midnight of UTC timezone. Dislike count is no longer available for this metric as of December 13, 2021 Learn more. |
likes_change |
integer
|
|
Absolute change of likes count on uploaded videos. |
subscribers_change |
integer
|
|
Absolute change of subscribers count lifetime. |
subscribers_count_lifetime |
integer
|
|
Subscribers count - lifetime value. |
video_change |
integer
|
|
Absolute change of videos count lifetime. |
video_count_lifetime |
integer
|
|
Video count - lifetime value. |
viewed_time_change |
integer
|
|
Absolute change of viewed time (in seconds) lifetime. Viewed time for each video is number of views multiplied by length of the video. |
viewed_time_lifetime |
integer
|
|
Viewed time (in seconds) of all uploaded videos - lifetime value. Viewed time for each video is number of views multiplied by length of the video. |
views_change |
integer
|
|
Absolute change of views count lifetime. |
views_count_lifetime |
integer
|
|
Views count of all uploaded videos - lifetime value. |
Example request
POST /1/youtube/metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"date_start": "2016-01-01",
"date_end": "2016-01-02",
"profiles": ["UCA6AG33Zac0xi6f9VMTxkFQ", "UCCAg0pGh47apFzefcJN6x3w"],
"metrics": ["subscribers_lifetime", "subscribers_change", ...]
}
Example response
{
"success": true,
"profiles": [
{
"id": "UCA6AG33Zac0xi6f9VMTxkFQ",
"data": [
{
"date": "2016-01-01 00:00:00",
"subscribers_lifetime": 123456,
"subscribers_change": 123,
...
},
{
"date": "2016-01-02 00:00:00",
"subscribers_lifetime": 654321,
"subscribers_change": 654,
...
}
]
},
{
"id": "UCCAg0pGh47apFzefcJN6x3w",
"data": [
{
"date": "2016-01-01 00:00:00",
"subscribers_lifetime": 111222,
"subscribers_change": 1122,
...
},
{
"date": "2016-01-02 00:00:00",
"subscribers_lifetime": 222111,
"subscribers_change": 2211,
...
}
]
}
]
}
Pinterest Metrics
Returns daily metrics for each requested Pinterest profile.
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
The response uses a timezone assigned to a profile in Suite settings of the account.
The last day will be also included in the response.
|
profiles | The list of string values. Each is ID of the profile available from the /1/pinterest/profiles endpoint. |
metrics | The list of metrics that will be returned in the response. Available metrics are listed in the table below. |
Metrics
Name | Type | Example | Description |
---|---|---|---|
boards_change |
integer
|
|
Absolute change of boards count lifetime. |
boards_lifetime |
integer
|
|
Boards count - lifetime value. |
comments |
integer
|
|
Number of comments on profile pins. |
followers_change |
integer
|
|
Absolute change of followers count lifetime. |
followers_lifetime |
integer
|
|
Followers count - lifetime value. |
following_change |
integer
|
|
Absolute change of following count lifetime. |
following_lifetime |
integer
|
|
Following count - lifetime value. |
interactions |
integer
|
|
Number of interactions on profile pins. |
likes |
integer
|
|
Number of likes on profile pins. |
pins_change |
integer
|
|
Absolute change of pins count lifetime. |
pins_lifetime |
integer
|
|
Pins count - lifetime value |
repins |
integer
|
|
Number of repins on profile pins. |
Example request
POST /1/pinterest/metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"date_start": "2016-01-01",
"date_end": "2016-01-02",
"profiles": ["376684093741466051", "484348272333315815"],
"metrics": ["pins_change", "boards_change", ...]
}
Example response
{
"success": true,
"profiles": [
{
"id": "376684093741466051",
"data": [
{
"date": "2016-01-01 00:00:00",
"pins_change": 123,
"boards_change": 12,
...
},
{
"date": "2016-01-02 00:00:00",
"pins_change": 23,
"boards_change": 10
...
}
]
},
{
"id": "484348272333315815",
"data": [
{
"date": "2016-01-01 00:00:00",
"pins_change": 50,
"boards_change": 7,
...
},
{
"date": "2016-01-02 00:00:00",
"pins_change": 43,
"boards_change": 11,
...
}
]
}
]
}
Posts
The endpoints in this section return a list of posts/videos/tweets, accompanied by the fields you specify. It can be an attribute of the post (text, created time, author, id, paid status) or metric (Number of comments, Number of Likes).
Facebook Page Posts Metrics
Returns a set of posts created during the specified date range for each requested Facebook profile. Facebook posts endpoint returns lifetime values of the metrics.
Parameters
Name | Description |
---|---|
profiles |
array , list of profile IDs of the profiles available from the /1/facebook/profiles endpoint.
|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
Your request is transformed using the time zone assigned to a profile in the Suite settings of your account.
The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct
timezone using the timezone of each individual profile from the /1/facebook/profiles endpoint.
The last day will be also included in the response.
|
fields |
array , the list of fields that will be returned in the response. Available fields are listed in
the table below.
|
limit |
integer , (optional). The number of results per page. The default value is 10 and the maximal value is 500.
|
after |
string , (optional). Pagination cursor. Points to the end of the page that has been returned.
|
sort |
You can sort the results by specifying a field and sorting order in the sort object: "field": "created_time"
and "order": "desc" . See the list of fields allowed
for sorting.
|
filter |
You can filter results by providing the filter parameter with field and value . See
the list of fields allowed for filtering.
|
Basic Fields
Name | Type | Example | Description |
---|---|---|---|
attachments |
array
|
|
Array of objects containing details about post attachments. Fields: title, description, url, image_url. |
author_id |
string
|
|
Facebook page post author profile id. |
comments |
integer
|
|
Facebook post comments count. |
created_time |
datetime
|
|
Facebook post created time. |
engagement_rate |
float
|
|
Engagement Rate for a particular post displays the average number of Interactions per Fan. Engagement Rate is therefore calculated by dividing the number of Interactions of a post by the number of Fans on that day. |
id |
string
|
|
Facebook post id. |
interactions |
integer
|
|
Facebook post interaction count. |
is_published |
boolean
|
|
Is post published |
message |
string
|
|
Facebook post contents. |
page_id |
string
|
|
Facebook page id for the published post. |
post_labels |
array
|
|
Array of content labels (formally post labels) for given post and account |
ppd_status |
string
|
|
Indicates whether the post was organic, paid or unknown based on PPD algorithm. |
reactions |
integer
|
|
Facebook post reactions count. |
reactions_by_type |
object
|
|
Object containing Facebook post reactions number. |
shares |
integer
|
|
Facebook post share count. |
story |
string
|
|
Text from stories not intentionally generated by users, such as those generated when two people become friends, or when someone else posts on the person's wall. |
type |
string
|
|
Facebook post type. |
universal_video_id |
string
|
|
The publishers asset management code for this video. Only available in case the post type is a video. |
url |
string
|
|
Link to facebook post. |
video_id |
string
|
|
The id of the video object. Only available in case the post type is a video. |
video_length |
float
|
|
Duration of the video in seconds. Only available in case the post type is a video. |
Insights Fields
Metrics prefixed with insights_
can only be used for profiles that have insights_enabled
property set to true
in the response of the /1/facebook/profiles
endpoint.
Name | Type | Example | Description |
---|---|---|---|
insights_engaged_fan |
integer
|
|
People who have liked your page and engaged with your post. |
insights_engaged_users |
integer
|
|
The number of people who clicked anywhere in your posts |
insights_engagement_rate
No longer supported
|
float
|
|
Reach shows you how many people were exposed to your content and Reach Engagement Rate shows you how many of those reached people actually interacted with it. We have updated and improved this metric and it is available for you to use from the latest API version. The older version of this metric will still return data for the time being but please bear in mind that this will show different values in comparison to the new one. If you are interested about the details of the new metric, please check this article. |
insights_impressions |
integer
|
|
The number of impressions for your Page post |
insights_impressions_by_paid_non_paid |
object
|
|
The number of impressions for your Page post, broken down by total, paid, and non-paid |
insights_impressions_fan |
integer
|
|
The number of impressions for your Page post by people who have liked your Page |
insights_impressions_organic |
integer
|
|
The number of impressions of your post in Newsfeed, Ticker, or on your Page's Wall |
insights_impressions_paid |
integer
|
|
The number of impressions for your Page post in an Ad or Sponsored Story |
insights_negative_feedback |
integer
|
|
The number of times people took a negative action in your post (e.g. hid it) |
insights_negative_feedback_unique |
integer
|
|
The number of people who took a negative action in your post (e.g., hid it) |
insights_paid_status |
string
|
|
Whether the post has been promoted (received any paid impression) or not |
insights_post_clicks |
integer
|
|
The number of times people clicked on anywhere in your posts without generating an activity |
insights_post_clicks_by_type |
object
|
|
The number of times people clicked on anywhere in your posts without generating an activity, broken-down by post click type. |
insights_post_clicks_by_type_unique |
object
|
|
The number of people who clicked anywhere in your post without generating an activity, broken-down by post click type. |
insights_post_clicks_unique |
integer
|
|
The number of people who clicked anywhere in your post without generating an activity. |
insights_reach |
integer
|
|
The number of people who saw your Page post |
insights_reach_by_paid_non_paid |
object
|
|
The number of people who saw your Page post, broken down by total, paid, and non-paid |
insights_reach_fan |
integer
|
|
The number of people who have like your Page who saw your Page post |
insights_reach_fan_paid |
integer
|
|
The number of people who have like your Page and saw your Page post in an Ad or Sponsored Story |
insights_reach_organic |
integer
|
|
The number of people who saw your post in their Newsfeed or Ticker or on your Page's Wall |
insights_reach_paid |
integer
|
|
The number of people who saw your Page post in an Ad or Sponsored Story |
insights_reactions_by_type_total |
object
|
|
The number of reactions to a Page's post by reaction type. |
insights_reactions_like_total |
integer
|
|
The number of "like" reactions to a post. |
insights_stories |
integer
|
|
The number of stories created about your Page (Stories) |
insights_story_adds |
integer
|
|
The number of stories generated about your Page post. |
insights_storytellers |
integer
|
|
The number of people sharing stories about your page ("People Talking About This" / PTAT). These stories include liking your Page, posting to your Page's Wall, liking, commenting on or sharing one of your Page posts, answering a Question you posted, RSVPing to one of your events, mentioning your Page, phototagging your Page or checking in at your Place |
insights_video_avg_time_watched |
integer
|
|
The average length of time (in milliseconds) people spent viewing your video |
insights_video_complete_views_30s |
integer
|
|
Total number of times Page's videos have been viewed for more than 30 seconds |
insights_video_complete_views_30s_autoplayed |
integer
|
|
Total number of times Page's autoplayed videos have been viewed to the end, or viewed for more than 30 seconds |
insights_video_complete_views_30s_clicked_to_play |
integer
|
|
Total number of times Page's videos have been viewed to the end, or viewed after the user clicks on play for more than 30 seconds |
insights_video_complete_views_30s_organic |
integer
|
|
Total number of times Page's videos have been viewed to the end, or viewed for more than 30 seconds by organic reach |
insights_video_complete_views_30s_paid |
integer
|
|
Total number of times Page's promoted videos have been viewed to the end, or for more than 30 seconds |
insights_video_complete_views_30s_unique |
integer
|
|
Total number of times Page's videos have been played for unique people to the end, or viewed for more than 30 seconds |
insights_video_complete_views_organic |
integer
|
|
The number of times your video was organically viewed from the beginning to 95% of its length |
insights_video_complete_views_organic_unique |
integer
|
|
The number of people who viewed your video organically from the beginning to 95% of its length |
insights_video_complete_views_paid |
integer
|
|
The number of times your video was viewed via paid impression from the beginning to 95% of its length |
insights_video_complete_views_paid_unique |
integer
|
|
The number of people who viewed your video via paid impression from the beginning to 95% of its length |
insights_video_retention_graph |
array
|
|
Percentage of viewers at each interval. Video length is divided into short buckets. Each key in response represents a bucket. Values are percent of people saw the video in that bucket |
insights_video_retention_graph_autoplayed |
array
|
|
Percentage of viewers at each interval where the video started playing automatically. Video length is divided into short buckets. Each key in response represents a bucket. Values are percent of people saw the video in that bucket |
insights_video_view_time |
integer
|
|
The total number of milliseconds your video was watched, including replays and views less than 3 seconds. |
insights_video_view_time_by_age_bucket_and_gender |
object
|
|
The total time, in milliseconds, your video played for your Top Audiences, age and gender |
insights_video_view_time_by_country_id |
object
|
|
The total number of minutes your video played for your Top 45 Locations - Countries |
insights_video_view_time_organic |
integer
|
|
Total time (in milliseconds) video has been viewed without paid promotion |
insights_video_view_time_paid |
integer
|
|
Total time (in milliseconds) video has been viewed with paid promotion |
insights_video_views |
integer
|
|
The number of times your video was watched for an aggregate of at least 3 seconds, or for nearly its total length, whichever happened first. |
insights_video_views_autoplayed |
integer
|
|
Number of times your video started automatically playing and people viewed it for more than 3 seconds |
insights_video_views_clicked_to_play |
integer
|
|
Number of times people clicked to play your video and viewed it more than 3 seconds |
insights_video_views_organic |
integer
|
|
The number of times your video was organically viewed for 3 seconds or more |
insights_video_views_organic_unique |
integer
|
|
The number of people who viewed at least 3 seconds of your video organically |
insights_video_views_paid |
integer
|
|
The number of times your video was viewed via paid impression for 3 seconds or more |
insights_video_views_paid_unique |
integer
|
|
The number of people who viewed at least 3 seconds of your video via paid impression |
insights_video_views_unique |
integer
|
|
The number of distinct people who viewed your video at least once. |
Fields that might be used to sort Facebook posts:
Basic Fields- comments
- created_time
- interactions
- reactions
- reactions_by_type.anger
- reactions_by_type.haha
- reactions_by_type.like
- reactions_by_type.love
- reactions_by_type.sorry
- reactions_by_type.wow
- shares
- insights_engaged_users
- insights_engagement_rate
No longer supported
- insights_impressions
- insights_impressions_organic
- insights_impressions_paid
- insights_post_clicks
- insights_post_clicks_by_type_unique.link clicks
- insights_post_clicks_by_type_unique.photo view
- insights_post_clicks_by_type_unique.video play
- insights_reach
- insights_reach_organic
- insights_reach_paid
- insights_video_avg_time_watched
- insights_video_complete_views_30s
- insights_video_view_time
- insights_video_views
- insights_video_views_organic
- insights_video_views_paid
- insights_video_views_unique
Fields that might be used to filter Facebook posts:
Basic Fields- post_labels - This field supports advanced post filters.
- ppd_status
- type
- insights_paid_status
Response
Name | Description |
---|---|
success | Status of the response. Possible values are true or false. |
data |
object containing the following properties:
|
Example request
POST /1/facebook/page/posts HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"profiles": ["164929129743", "543567853435"],
"date_start": "2017-07-01",
"date_end": "2017-10-25",
"fields": [
"id",
"created_time",
"message",
"comments",
"shares",
"reactions",
"interactions",
"url",
"author_id",
"page_id",
"attachments",
"type",
"reactions_by_type",
"story",
"insights_impressions",
"insights_impressions_paid",
"insights_paid_status",
"insights_engaged_users",
"insights_video_avg_time_watched",
"insights_engagement_rate",
"insights_post_clicks_by_type",
"insights_post_clicks_by_type_unique",
"universal_video_id",
"video_id",
"ppd_status",
"video_length",
"post_labels"
],
"sort": [
{
"field": "created_time",
"order": "desc"
}
],
"filter":
[
{
"field": "type",
"value": ["video"]
},
{
"field": "insights_paid_status",
"value": "paid",
},
{
"match_any": [
{
"field": "post_labels",
"value": [
"fa14dde7e4f041e3a646",
"890c135d9cee4cf89b42"
]
}
]
}
],
"limit": 5
}
Example response
{
"success": true,
"data": {
"posts": [
{
"id": "164929129743_10154736430664744",
"created_time": "2016-11-04T13:00:08+00:00",
"message": "Brainstorming on your social media content? This tool will help ↓",
"comments": 10,
"shares": 20,
"reactions": 70,
"interactions": 100,
"url": "https://www.facebook.com/socialbakers/posts/10154736430664744",
"author_id": "164929129743",
"page_id": "164929129743",
"attachments": [
{
"title": "Looking to Get Inspired For Your Next Campaign or Post?",
"description": "Coming up with ideas for new posts and campaigns is a challenge for every marketer...",
"url": "https://goo.gl/28ZEjD",
"image_url": "https://external.xx.fbcdn.net/safe_image.php?d=AQDCqVXSjdGWUTu5&url=https%3A%2F%2Fwww.facebook.com%2Fads%2Fimage%2F%3Fd%3DAQJAeqUrvHG_eEQJrlnw0oLjbP7j0uio9f72hrlJ-8VWCVEc2tV_wkWj3XOLkWrB3R0KYlA09NYIwj1KGgpqOkDtsYkAg49xZVltN_OQloQpjk0smGZC9CwkDTZn9XbotqP5G6MYA8bEjlnhgdc84Exm"
}
],
"type": "link",
"reactions_by_type": {
"like": 10,
"love": 20,
"wow": 30,
"haha": 5,
"sorry": 3,
"anger": 2
},
"post_labels": [
{
"id": "fa14dde7e4f041e3a646",
"name": "Content Label 1"
}
],
"story": "Emplifi published a note",
"insights_impressions": 3583,
"insights_impressions_paid": 496,
"insights_paid_status": "paid",
"insights_engaged_users": 50,
"insights_video_avg_time_watched": 60000,
"video_id": "1072177562941323",
"ppd_status": "organic",
"video_length": 125.481,
"universal_video_id": "164929129743_10154736430664744",
"insights_post_clicks_by_type": {
"other clicks": 381,
"link clicks": 48,
"video play": 530
},
"insights_post_clicks_by_type_unique": {
"other clicks": 302,
"link clicks": 43,
"video play": 506
},
"insights_engagement_rate": 0.017567734751948533
}, ...
],
"next": "eyJjdXJzb3IiOlt7ImZpZWxkIjoiY3JlYXRlZF90aW1lIiwidmFsdWUiOiIyMDE2LTEwLTI1VDEzOjAwOjA2LjAwMFoiLCJvcmRlciI6ImRlc2MifV0sImlkcyI6WyIxNjQ5MjkxMjk3NDNfMTAxNTQ3MDUwODA3Mzk3NDQiXX0=",
"remaining": 3276
}
}
Instagram Profile Posts Metrics
Returns a set of posts created during the specified date range for each requested Instagram profile. Instagram posts endpoint returns lifetime values of the metrics.
Parameters
Name | Description |
---|---|
profiles |
array , list of profile IDs of the profiles available from the /1/instagram/profiles endpoint.
|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
Your request is transformed using the time zone assigned to a profile in the Suite settings of your account.
The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct
timezone using the timezone of each individual profile from the /1/instagram/profiles endpoint.
The last day will be also included in the response.
|
fields |
array , the list of fields that will be returned in the response. Available fields are listed in
the table below.
|
limit |
integer , (optional). The number of results per page. The default value is 10 and the maximal value is 500.
|
after |
string , (optional). Pagination cursor. Points to the end of the page that has been returned.
|
sort |
You can sort the results by specifying a field and sorting order in the sort object: "field": "created_time"
and "order": "desc" . See the list of fields allowed
for sorting.
|
filter |
You can filter results by providing the filter parameter with field and value . See
the list of fields allowed for filtering.
|
Basic Fields
Name | Type | Example | Description |
---|---|---|---|
attachments |
array
|
|
Array of objects containing details about post attachments. Fields: url, type, width, height |
author_id |
string
|
|
Author profile ID. |
comments |
integer
|
|
Total number of comments on the media object. |
created_time |
datetime
|
|
Instagram media created time. |
engagement_rate |
float
|
|
Engagement Rate for a particular post displays the average number of Interactions per Fan. Engagement Rate is therefore calculated by dividing the number of Interactions of a post by the number of Fans on that day. |
id |
string
|
|
Instagram media ID. |
interactions |
integer
|
|
Total number of interactions on the media object. |
likes |
integer
|
|
Total number of likes on the media object. |
message |
string
|
|
Instagram media contents. |
post_labels |
array
|
|
Array of content labels (formally post labels) for given post and account |
type |
string
|
|
Media post type. |
url |
string
|
|
Link to instagram post. |
Insights Fields
Metrics prefixed with insights_
can only be used for profiles that have insights_enabled
property set to true
in the response of the /1/instagram/profiles
endpoint.
Name | Type | Example | Description |
---|---|---|---|
insights_engagement
No longer supported
|
integer
|
|
Total number of likes and comments on the media object. We have updated and improved this metric and it is available for you to use from the latest API version. The older version of this metric will still return data for the time being but please bear in mind that this will show different values in comparison to the new one. If you are interested about the details of the new metric, please check this article. |
insights_impressions |
integer
|
|
Total number of times the media object has been seen. |
insights_reach |
integer
|
|
Total number of unique accounts that have seen the media object. |
insights_saved |
integer
|
|
Total number of unique accounts that have saved the media object. |
insights_video_views |
integer
|
|
(Videos only) Total number of times the video has been seen. Returns 0 for videos in carousel albums. |
Fields that might be used to sort Instagram posts:
Basic Fields- comments
- created_time
- interactions
- likes
- insights_engagement
No longer supported
- insights_impressions
- insights_reach
- insights_saved
- insights_video_views
Fields that might be used to filter Instagram posts:
Basic Fields- post_labels - This field supports advanced post filters.
- type
Response
Name | Description |
---|---|
success | Status of the response. Possible values are true or false. |
data |
object containing the following properties:
|
Example request
POST /1/instagram/profile/posts HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"profiles": ["490402220", "55674325"],
"date_start": "2018-06-01",
"date_end": "2018-08-31",
"fields": [
"interactions",
"comments",
"likes",
"insights_engagement",
"insights_saved",
"insights_reach",
"insights_video_views",
"insights_impressions",
"id",
"author_id",
"created_time",
"type",
"message",
"attachments",
"post_labels",
"url"
],
"sort": [
{
"field": "created_time",
"order": "desc"
}
],
"filter": [
{
"field": "type",
"value": ["image"]
},
{
"match_any": [
{
"field": "post_labels",
"value": [
"fa14dde7e4f041e3a646",
"890c135d9cee4cf89b42"
]
}
]
}
],
"limit": 5
}
Example response
{
"success": true,
"data": {
"posts": [
{
"id": "17966172199068623_490402220",
"created_time": "2018-08-23T09:59:27+00:00",
"message": "Stuck in a rut with your Instagram marketing? Don’t sweat it 🙅♀️. Freshen up your content with these tips for insta success 💥! See link in bio to unlock the full list 📝",
"comments": 9,
"likes": 86,
"author_id": "490402220",
"type": "video",
"interactions": 95,
"profile_id": "490402220",
"attachments": [
{
"images": [],
"videos": [
{
"url": "https://scontent.xx.fbcdn.net/v/t50.2886-16/39076708_281043816045474_2574583738604191744_n.mp4?_nc_cat=0&oh=2d1efdd181ee7d18d1be98d22afdb900&oe=5BF734E0"
}
]
}
],
"post_labels": [
{
"id": "890c135d9cee4cf89b42",
"name": "Content Label 1"
}
],
"insights_engagement": 148,
"insights_saved": 52,
"insights_reach": 3094,
"insights_video_views": 923,
"insights_impressions": 4178,
"url": "https://www.instagram.com/p/Bk4f5J_gypJ/"
}
],
"next": "eyJjdXJzb3IiOlt7ImZpZWxkIjoiY3JlYXRlZF90aW1lIiwidmFsdWUiOiIyMDE4LTA2LTI4VDEyOjM4OjM0KzAwOjAwIiwib3JkZXIiOiJkZXNjIn1dLCJpZHMiOlsiMTc4OTM5NTExNjIyMTY0NjRfNDkwNDAyMjIwIl19=",
"remaining": 15
}
}
Twitter Tweets Metrics
Returns tweets metrics for each requested Twitter profile.
Parameters
Name | Description |
---|---|
profiles |
array , list of profile IDs of the profiles available from the /1/twitter/profiles endpoint.
|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
Your request is transformed using the time zone assigned to a profile in the Suite settings of your account.
The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct
timezone using the timezone of each individual profile from the /1/twitter/profiles endpoint.
The last day will be also included in the response.
|
fields |
array , the list of fields that will be returned in the response. Available fields are listed in
the table below.
|
limit |
integer , (optional). The number of results per page. The default value is 10 and the maximal value is 500.
|
after |
string , (optional). Pagination cursor. Points to the end of the page that has been returned.
|
filter |
You can filter results by providing the filter parameter with field and value . See
the list of fields allowed for filtering.
|
Fields
Name | Type | Example | Description |
---|---|---|---|
attachments
No longer supported
|
array
|
|
Array of objects containing details about post attachments. |
author_id |
string
|
|
Tweet author profile id. |
coordinates
No longer supported
|
object
|
|
Represents the geographic location of this Tweet as reported by the user or client application. The inner coordinates array is formatted as geoJSON (longitude first, then latitude). |
created_time
No longer supported
|
datetime
|
|
Tweet created time. |
engagement_rate |
float
|
|
Engagement Rate for a particular post displays the average number of Interactions per Fan. Engagement Rate is therefore calculated by dividing the number of Interactions of a post by the number of Fans on that day. |
entities
No longer supported
|
object
|
|
Entities provide metadata and additional contextual information about content posted on Twitter. |
id |
string
|
|
Tweet id. |
in_reply_to_user_id
No longer supported
|
string
|
|
If the represented Tweet is a reply, this field will contain the integer representation of the original Tweet’s author ID. |
interactions
No longer supported
|
integer
|
|
Number of interactions. |
language
No longer supported
|
string
|
|
Indicates a BCP 47 language identifier corresponding to the machine-detected language of the Tweet text. |
likes
No longer supported
|
integer
|
|
Number of times tweet was liked (favorited). |
mentions
No longer supported
|
array
|
|
List of Twitter profile ids mentioned. |
message
No longer supported
|
string
|
|
Tweet content. |
post_labels |
array
|
|
Array of content labels (formally post labels) for given tweet and account |
replies
No longer supported
|
integer
|
|
Number of replies. |
retweeted_user_id
No longer supported
|
string
|
|
If the represented Tweet is a retweet, this field will contain the integer representation of the original Tweet’s author ID. |
shares
No longer supported
|
integer
|
|
Number of shares. |
source
No longer supported
|
object
|
|
id: HTML-formatted string linking to utility used to create the tweet; name: name of the utility |
type
No longer supported
|
string
|
|
List of tweet types. |
Fields that might be used to filter Twitter posts:
Basic Fields- post_labels - This field supports advanced post filters.
- type
No longer supported
Response
Name | Description |
---|---|
success | Status of the response. Possible values are true or false. |
data |
object containing the following properties:
|
Example request
POST /1/twitter/profile/tweets HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"profiles": ["1964904343", "8643567434"],
"date_start": "2016-01-01",
"date_end": "2017-01-01",
"fields": [
"id",
"author_id",
"post_labels"
],
"filter": [
{
"match_any": [
{
"field": "post_labels",
"value": [
"fa14dde7e4f041e3a646",
"890c135d9cee4cf89b42"
]
}
]
}
],
"limit": 5
}
Example response
{
"success": true,
"data": {
"posts": [
{
"id": "689427258210004992",
"post_labels": [
{
"id": "fa14dde7e4f041e3a646",
"name": "Content Label 1"
}
],
"author_id": "1964904343",
}
],
"remaining": 0
}
}
YouTube Profile Video Metrics
Returns a set of videos created during the specified date range for each requested YouTube channels. YouTube videos endpoint returns lifetime values of the metrics.
Parameters
Name | Description |
---|---|
profiles |
array , list of profile IDs of the profiles available from the /1/youtube/profiles endpoint.
|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
Your request is transformed using the time zone assigned to a profile in the Suite settings of your account.
The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct
timezone using the timezone of each individual profile from the /1/youtube/profiles endpoint.
The last day will be also included in the response.
|
fields |
array , the list of fields that will be returned in the response. Available fields are listed in
the table below.
|
limit |
integer , (optional). The number of results per page. The default value is 10 and the maximal value is 500.
|
after |
string , (optional). Pagination cursor. Points to the end of the page that has been returned.
|
sort |
You can sort the results by specifying a field and sorting order in the sort object: "field": "created_time"
and "order": "desc" . See the list of fields allowed
for sorting.
|
filter |
You can filter results by providing the filter parameter with field and value . See
the list of fields allowed for filtering.
|
Fields
Name | Type | Example | Description |
---|---|---|---|
author_id |
string
|
|
The ID that YouTube uses to uniquely identify the channel that the video was uploaded to. |
comments |
integer
|
|
The number of comments for the video. |
created_time |
datetime
|
|
The date and time when the uploaded video file was created. |
dislikes |
integer
|
|
Number of dislikes for the video. Dislike count is no longer available as of December 13, 2021 Learn more. |
duration |
integer
|
|
The length of the video [s]. |
engagement_rate |
float
|
|
Engagement Rate for a particular post displays the average number of Interactions per Fan. Engagement Rate is therefore calculated by dividing the number of Interactions of a post by the number of Fans on that day. Dislike count is no longer available for this metric as of December 13, 2021 Learn more. |
id |
string
|
|
The ID that YouTube uses to uniquely identify the video. |
interactions |
integer
|
|
Sum of likes and comments. Dislike count is no longer available for this metric as of December 13, 2021 Learn more. |
likes |
integer
|
|
The number of users who have indicated that they liked the video. |
message |
string
|
|
The video's description. |
post_labels |
array
|
|
Array of content labels (formally post labels) for given profile and account |
published_time |
datetime
|
|
The date and time when the video was published. |
video_view_time |
integer
|
|
The number of time the video has been viewed multiplied by duration [s]. |
video_views |
integer
|
|
The number of times the video has been viewed. |
Fields that might be used to sort YouTube profile video:
Basic Fields- comments
- created_time
- dislikes
- duration
- interactions
- likes
- published_time
- video_view_time
- video_views
Fields that might be used to filter YouTube profile video:
Basic Fields- post_labels - This field supports advanced post filters.
Response
Name | Description |
---|---|
success | Status of the response. Possible values are true or false. |
data |
object containing the following properties:
|
Example request
POST /1/youtube/profile/videos HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"profiles": ["UCA6AG33Zac0xi6f9VMTxkFQ", "455DFG232sdg677"],
"date_start": "2018-06-01",
"date_end": "2018-08-31",
"fields": [
"id",
"created_time",
"message",
"author_id",
"comments",
"duration",
"video_view_time",
"published_time",
"dislikes",
"video_views",
"likes",
"interactions",
"post_labels"
],
"sort": [
{
"field": "created_time",
"order": "desc"
}
],
"filter": [
{
"match_any": [
{
"field": "post_labels",
"value": [
"fa14dde7e4f041e3a646",
"890c135d9cee4cf89b42"
]
}
]
}
],
"limit": 5
}
Example response
{
"success": true,
"data": {
"posts": [
{
"id": "6Ol7dJtKcq0",
"created_time": "2018-06-15T14:41:32.000Z",
"message": "Get caught up on the most important social media news of the week!\nBeginner-friendly guide to Influencer Marketing: http://goo.gl/aTWHRV",
"author_id": "UCA6AG33Zac0xi6f9VMTxkFQ",
"comments": 0,
"likes": 6,
"duration": 114,
"video_view_time": 41040,
"published_time": "2018-06-15T14:41:32.000Z",
"dislikes": 0,
"video_views": 360,
"interactions": 6,
"post_labels": [
{
"id": "fa14dde7e4f041e3a646",
"name": "Content Label 1"
}
]
},
],
"next": "eyJjdXJzb3IiOlt7ImZpZWxkIjoiY3JlYXRlZF90aW1lIiwidmFsdWUiOiIyMDE4LTA2LTI4VDEyOjM4OjM0KzAwOjAwIiwib3JkZXIiOiJkZXNjIn1dLCJpZHMiOlsiMTc4OTM5NTExNjIyMTY0NjRfNDkwNDAyMjIwIl19=",
"remaining": 15
}
}
Aggregated Post Metrics
You can find this endpoint useful in case you want to get the aggregated metrics data of a set of posts. The set of posts is defined by the profiles and filtering parameters.
The set of posts is defined by the date range, the profiles, and the filtering parameters.
When requesting the data, the dimension of the data is required. Dimensions are common criteria that are used to aggregate data, such as the date on that the post has been published or the content label of the post.
You can use this endpoint to answer questions like: How many interactions (impressions, posts, reactions, etc.) relate to posts having a specific content label? How many interactions relate to a particular type of post? How many interactions were created by organic or paid posts?
Facebook Post Metrics
Returns a set of posts created during the specified date range for each requested Facebook profile. Facebook posts endpoint returns lifetime values of the metrics.
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
The response uses a timezone assigned to a profile in Suite settings of the account.
The last day will be also included in the response.
|
profiles | array of objects, consists of profile IDs and platforms. You can get the list of profile IDs from the /1/facebook/profiles endpoint. |
metric | string , the list of available metrics is displayed below. |
dimensions | array of objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimensions in the table of metrics below. |
filter | array of objects. You can filter the results using simple or advanced post filters. See the list of fields allowed for filtering. |
Metrics
Metrics prefixed with insights_
can only be used for profiles that have insights_enabled
property set to true
in the response of the /1/facebook/profiles
endpoint.
Name | Dimensions | Metrics Description |
---|---|---|
page_posts | date.day date.month date.quarter date.week date.year profile post_labels post_type ppd_status |
Number of page posts. |
interactions | date.day date.month date.quarter date.week date.year profile post_labels post_type ppd_status interaction_type |
Number of interactions on page posts. |
insights_impressions | date.day date.month date.quarter date.week date.year profile post_labels post_type |
The number of impressions for your posts. |
reactions | date.day date.month date.quarter date.week date.year profile post_labels post_type ppd_status reaction_type |
Number of reactions on page posts. |
insights_video_views | date.day date.month date.quarter date.week date.year profile post_labels |
Number of times page's videos have been viewed for more than 3 seconds. |
insights_post_clicks | date.day date.month date.quarter date.week date.year profile post_labels post_type |
The number of times people clicked on anywhere in your posts without generating an activity. |
insights_reach_engagement | date.day date.month date.quarter date.week date.year profile post_labels post_type |
Reach Engagement Rate informs about the percentage of users who engaged with a post during its lifetime given its reach. Learn More. |
Fields that might be used to filter Facebook posts:
Basic Fields- post_labels - This field supports advanced post filters.
Example request
POST /1/metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"profiles": [
{
"id": "164929129743",
"platform": "facebook"
}
],
"date_start": "2018-11-01",
"date_end": "2018-11-12",
"metric": "page_posts",
"dimensions": [
{
"type": "profile"
}
],
"filter": [
{
"field": "post_labels",
"value": [
"e3af7de2d2274393b86b"
]
}
]
}
Example response
{
"success": true,
"header": [
{
"type": "profile",
"rows": [
"164929129743"
]
},
{
"type": "metric",
"rows": [
"page_posts"
]
}
],
"data": [
[
3
]
]
}
Aggregated Post Metrics
Aggregated Post metrics display lifetime data from individual posts published during the selected time period of your analysis. All post data is aggregated and displayed for the day the post was published, regardless of when the engagement happened.
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
The response uses a timezone assigned to a profile in Suite settings of the account.
The last day will be also included in the response.
|
profiles | array of objects, consists of profile IDs and platforms. You can get the profiles from the List of Connected Profiles section. |
metric | string , the list of available metrics is displayed below. |
dimensions | array of objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimensions in the table of metrics below. |
filter | array of objects. You can filter the results using simple or advanced post filters. See the list of fields allowed for filtering. |
Metrics
Metrics prefixed with insights_
can only be used for profiles from platforms that have insights enabled. Not all metrics are available for all platforms.
All LinkedIn and Pinterest metrics can only be used for profiles that have insights_enabled
property set to true
in the response of their respective /${apiVersion}/{network}/profiles
endpoint.
Aggregation is the type of calculation used for grouping values of a specific metric.
Name | Dimensions | Aggregation | Metrics Description |
---|---|---|---|
engagement_rate
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type published_status |
avg | Engagement Rate for a particular post displays the average number of Interactions per Fan. Engagement Rate is therefore calculated by dividing the number of Interactions of a post by the number of Fans on that day. |
insights_completion_rate
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label media_type |
avg | The percentage of times a story impression was not interrupted by an exit, tap back, or tap forward. |
insights_engagements
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label media_type content_type |
sum | Engagements inform about how many times users engaged with a post during its lifetime. Learn More. |
insights_impressions
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type published_status |
sum | Number of impressions for your posts. |
insights_media_views
|
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
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type published_status |
sum | The number of times people clicked on anywhere in your posts without generating an activity. |
insights_post_saves
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label media_type content_type |
sum | Total number of saves on the posts. |
insights_reach_engagement
|
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
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type published_status |
avg | Number of people who have seen any content associated with your Page. (Unique Users) |
insights_story_exits
|
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
|
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
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label media_type |
sum | The number of times users clicked forward to skip to the next story. |
insights_video_views
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type published_status |
sum | Number of times page's videos have been viewed for more than 3 seconds. For Instagram Reels number of plays are counted as video views. Plays are defined as video sessions with 1 ms + of playback, excluding replays. |
interactions
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type published_status interaction_type |
sum | Number of interactions on page posts. YouTube dislike count is no longer available for this metric as of December 13, 2021 Learn more. |
interactions_per_1k_fans
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type published_status |
sum | Number of interactions on page posts per 1k fans. |
likes
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label media_type |
sum | Number of likes of profile posts. |
number_of_comments
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type published_status |
sum | Number of comments on page posts. |
page_posts
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type published_status |
sum | Number of page posts. |
page_replies
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type |
avg | Ratio of responded user questions to user questions. |
Fields that might be used to filter posts:
Basic Fields- post_labels - This field supports advanced post filters.
Example request
POST /1/aggregated-metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"profiles": [
{
"id": "564919357",
"platform": "twitter"
},
{
"id": "164929129743",
"platform": "facebook"
}
],
"date_start": "2018-11-01",
"date_end": "2018-11-12",
"metric": "page_posts",
"dimensions": [
{
"type": "profile"
}
],
"filter": [
{
"field": "post_labels",
"value": [
"e3af7de2d2274393b86b"
]
}
]
}
Example response
{
"success": true,
"header": [
{
"type": "profile",
"rows": [
{
"id": "564919357",
"platform": "twitter"
},
{
"id": "164929129743",
"platform": "facebook"
}
]
},
{
"type": "metric",
"rows": [
"page_posts"
]
}
],
"data": [
[
3
],
[
6
]
]
}
Advanced Post Filters
Introduction
Some fields support advanced possibilities of filtering. It is possible to create filter rules as a combination of match_all
and match_any
clauses. A combination with simple filter definition is also possible.
The filter consists of two types of clauses:
Simple filter clauses
Specifies particular field(s) and its values. Posts having these values will be part of the results.
{
"field": "type",
"value": [
"photo",
"status"
]
}
Advanced filter clauses
The advanced filter is used to combine multiple filters in a logical meaning as AND
, and OR
.
match_all
- Represents logicalAND
. Items have to match in all criteria for each clausematch_any
- Represents logicalOR
. The result of this filter has to match at least in one criterion of the clause.
{
"match_all": [
{
"field": "post_labels",
"value": [
"fa14dde7e4f041e3a646",
"890c135d9cee4cf89b42"
]
}
]
}
Google Data Studio Connector
Introduction
Google Data Studio is an analytics dashboard report service which turns your analytics data into informative reports which are easy to read, share and customizable.
Official Google Data Studio Connector description: https://support.google.com/datastudio/answer/6268208.
The connector allows you to access Emplifi API and use it as a source of data for your reports.
To access the connector, please visit this address: Emplifi GDS Connector
For authorization, you’ll need to input a User name and Token. These are linked to a specific user of a Emplifi Suite account. Get in touch with our Support team at support@emplifi.io to get yours.
(Please note that name convention slightly differs on Emplifi’s side where ‘Token’ and ‘Secret’ is being used.
EXAMPLE of what you’ll use for input:
User Name: (called token on Emplifi side)
NjE5MTA4XzE3OTAyMTVfMTU0NTMxNDUyOTA4OV82MTRlODkxODAzNDI0ZmU5MTQwY2VkZTY4NzI2NmI1OA== (example only, not functional)
Token: (called secret on Emplifi side)
f0e2b4ca2fd76b8515265fd6b8bced5d (example only, not functional)
More info about authorization: Security and authentication
Available metrics
Network | Metrics |
---|---|
Facebook Metrics | all metrics |
Instagram Metrics | all metrics |
Twitter Metrics | all metrics |
YouTube Metrics | all metrics |
Pinterest Metrics | all metrics |
Community
Currently only content labeling endpoints are available for Community.
Content Labeling
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 IDt_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 ID10156439716079744
, 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 ID10156440099689744
, the resulting content ID will be:10156439716079744_10156440099689744
.
Note: You can verify post and comment IDs by inserting them as path to Facebook URL. For example
facebook.com/10156439716079744_10156440099689744
redirects to the comment.
These composite IDs are compatible with Graph API too.
Response
Name | Description |
---|---|
success | Status of the response. Possible values are true or false. |
data |
object containing the
contents object of responses per individual contents.
|
Example request
PUT /1/community/{network}/labels HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"content_ids": [
// Facebook conversation ID
"754387418054186-t_100022491363476",
// Facebook page post ID
"849715935050458_1520511894637588"
],
"labels": ["my label"]
}
Example response
{
"success": true,
"data": {
"contents": {
"754387418054186-t_100022491363476": {
"status": "ok"
},
"849715935050458_1520511894637588": {
"status": "ok"
}
}
}
}
Changelog
v1.20 (2024/10/02)
/1/facebook/metrics
- Breaking change: Removed the following deprecated Facebook page metrics.
insights_positive_feedback
insights_post_clicks
insights_post_clicks_by_type
insights_reach_engagement
insights_engaged_users
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
insights_fans_gender_age_lifetime
/1/facebook/page/posts
- Breaking change: Removed the following deprecated Facebook post metric.
insights_impressions_fan_paid
v1.19 (2024/06/26)
/3/aggregated-metrics
- Profiles from irrelevant networks no longer returned in response
v1.18 (2024/05/01)
/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.
- Deprecated metrics:
insights_impressions_fan_paid
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)
-
Pinterest data is now available exclusively for insights connected profiles. Affected endpoints:
v1.14 (2023/01/12)
-
video_igtv
media type is now merged together with the rest of themedia_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 returnvideo_igtv
as a separate bucket ofmedia_type
breakdown. Instead, it will include the results in thevideo
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 toapi.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
- Vkontakte data is no longer supported under
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:
-
/1/youtube/metrics
dislikes_change, engagement_rate, interaction_change, interactions_per_1000_subscribers
-
/1/youtube/profile/videos
dislikes, engagement_rate, interactions
-
/1/aggregated-metrics
engagement_rate, interactions, interactions_per_1k_fans
-
- 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
- Aggregated post metrics endpoint /1/aggregated-metrics now returns data sorted by value descending
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 Moreinsights_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 videosv1.3
- Fixed a bug where following endpoints were returning partial data when requesting insights metrics for profiles without insights permissions instead of failing with error
code 7, Profiles do not have insights enabled
. This is potentially a breaking change if data was not requested according to documentation.
Affected endpoints:
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
- some of Twitter Tweets Metrics are no longer supported to meet the Twitter Developer Policies
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
- interactions metric added for YouTube video
- posts can be filtered by Content Label (label IDs)
- new endpoint
/1/post/labels
to get a list of content labels available in the account - multiple profiles can be requested in bulk while using Facebook post, Instagram post, Twitter tweets, and YouTube video metrics
- label ID is returned for Facebook post, Instagram post, Twitter tweets, and YouTube video content labels in addition to a label name
- the timezone is (internally) applied to correspond with Suite data when using post level endpoints
- new metrics
insights_paid_status
,insights_video_view_time_by_country_id
, andinsights_video_view_time_by_age_bucket_and_gender
added to Facebook post endpoint - new filters,
ppd_status
, andinsights_paid_status
, available for Facebook post
v0.9
2021/06/16
-
Fixed a bug where following endpoints were returning partial data when requesting insights metrics for profiles without insights permissions instead of failing with error
code 7, Profiles do not have insights enabled
. This is potentially a breaking change if data was not requested according to documentation.Affected endpoints:
2019/06/22
- some of Twitter Tweets Metrics are no longer supported to meet the Twitter Developer Policies
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
- new filter field to filter Facebook post, Instagram post and Twitter tweets
- new sort field to sort Facebook post, Instagram post, Twitter tweets and YouTube video metrics
2018/09/10
- new video-related metrics and
paid_status
metric for Facebook post metrics - new endpoint YouTube video metrics
- new endpoint Instagram post metrics
2018/08/10
- new
insights_
prefixed metrics added for Instagram metrics
2018/02/22
- new response field
type
added to Twitter tweets metrics
2017/10/16
- new response field
sbks_labels
added to List of connected profiles
2017/08/16
- new response field
picture
added to List of connected profiles
2017/07/13
- new field
sbks_labels
added to Facebook post metrics
2017/05/04
- new metrics
insights_impressions_viral
,insights_impressions_viral_frequency_distribution
andinsights_impressions_viral_unique
added for Facebook metrics
2017/03/28
- new metrics
insights_
prefixed metrics for Facebook metrics - new metrics
insights_
prefixed metrics for Facebook post metrics - new endpoint Twitter tweet metrics
- new Tableau Web Data Connector
2016/11/23
- new network
pinterest
added for List of connected profiles - new endpoint Pinterest metrics
- new endpoint Facebook post metrics
2016/10/27
- new metrics
viewed_time_change
andviewed_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 |