Emplifi API Documentation
Introduction
The Emplifi REST API allows access to the data points used in Emplifi suite. Access to the API is available on request for Emplifi clients only.
If you are interested in API access, please contact our Emplifi Sales representative.
Security and Authentication
The API is secured with HTTPS. Authentication is made using Basic HTTP Authorization by token and secret or by OAuth2.0 authorization framework. The authorization is sent in the HTTP headers.
Basic HTTP Authorization using token and secret
Basic HTTP Authorization uses a token and secret with a colon between them encoded to base64 format.
Example: if we use "Aladdin" as a token and "OpenSesame" as a secret, then "Aladdin:OpenSesame" produces "QWxhZGRpbjpPcGVuU2VzYW1l" when encoded to base64 format.
The parameter in the HTTP header would be then: Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l
The token and secret are linked to a specific user of a Emplifi Suite account. Get in touch with our Support team at support@emplifi.io to get yours.
Example request
GET /3/facebook/profiles HTTPS
Host: api.emplifi.io
Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l
Content-Type: application/json; charset=utf-8
Using OAuth 2.0 to access Emplifi API
Emplifi API uses the OAuth 2.0 framework to authorize users to make API request. Emplifi API supports the Oauth 2.0 Authorization code flow.
Before you begin create a new Custom integration in the Emplifi Settings.
OAuth2 endpoints are located at https://api.emplifi.io/oauth2/0/
.
The OAuth2 configuration is available at https://api.emplifi.io/oauth2/0/.well-known/openid-configuration.
How to get access to OAuth 2.0
OAuth 2.0 access has to be enabled by our support team, even if you have Emplifi API Integration purchased. Please send oAuth activation request to support@emplifi.io
OAuth2.0 Authorization code flow
Steps to get API access
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/3/user/me', {
headers: {
Authorization: `Bearer ${accessToken}`,
},
})
if (userInfoResponse.status !== 200) {
const { statusText, status } = userInfoResponse
next(
new Error(`Failed to fetch user information ${status} - ${statusText}`)
)
}
const userInfo = await userInfoResponse.json()
// find the user in your application based on the received data and pass it to the next
next(null, { accessToken, refreshToken, user: userInfo.userInfo })
}
)
// when offline_access scope is requested, the prompt parameter is required to be set to consent
EmplifiStrategy.authorizationParams = function (options) {
return {
...options,
prompt: 'consent',
}
}
app.use(passport.session())
app.use(passport.initialize())
passport.use('emplifi', EmplifiStrategy)
passport.serializeUser((user, next) => next(null, user))
passport.deserializeUser((id, next) => next(null, id))
app.get(
'/auth/example',
passport.authenticate('emplifi', {
// offline_access is necessary to receive refresh_token. Required scopes are listed in the Emplifi API documentation
scope: ['api.read', 'offline_access'],
})
)
app.get(
'/auth/example/callback',
passport.authenticate('emplifi', { failureRedirect: '/failed' }),
function (req, res) {
// Successful authentication, redirect home.
res.redirect('/')
}
)
app.get('/failed', (req, res) => {
res.send('Failed to authenticate')
})
app.get('/', (req, res) => {
if (req.user) {
res.send(req.user)
} else {
res.send("<a href='/auth/example'>Login</a>")
}
})
app.listen(3000, () => {
console.log('Server is running on port 3000')
})
Using the access token
Send request to Emplifi API with access_token
in HTTP authorization
header.
"Authorization": "Bearer <ACCESS_TOKEN>"
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/3/facebook/profiles
Access token refreshing
The access token live time is limited. Refer to expires_in
property of the exchange authorization code to access token.
Once access token expires, you will have to refresh it by using refresh token.
The refresh token is returned by https://api.emplifi.io/oauth2/0/token
endpoint if the scope
property of the /auth
endpoint contains offline_access
.
To refresh access token make POST
request to /token
endpoint with following Request header and Request body.
Request Header
Header | Value |
---|---|
Authorization |
Basic authentication where username is the Client ID and password the Client Secret.
The string "Basic" with your Client ID and Client Secret separated with colon (:), Base64-encoded. For example, client_id:client_secret The final value is Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ= .
|
Content-Type |
application/x-www-form-urlencoded |
Request Body
Parameter | Value |
---|---|
refresh_token |
The refresh token obtained when asking for access token in step 3. In our example C8DEVlA-RuOlRhKiyvvWLQlc0cNZ1wk1K5uySKey7Yw |
grant_type |
refresh_token |
Refresh token expires in 180 days.
cURL request example
curl -X POST \
-H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token&refresh_token=C8DEVlA-RuOlRhKiyvvWLQlc0cNZ1wk1K5uySKey7Yw" \
https://api.emplifi.io/oauth2/0/token
Example response
{
"access_token": "JWefwbpGr3PJyBJjGP3DMaLe5ooX75StcfEb7bgaosn",
"expires_in": 7200,
"refresh_token": "C8DEVlA-RuOlRhKiyvvWLQlc0cNZ1wk1K5uySKey7Yw",
"scope": "api offline_access",
"token_type": "Bearer"
}
Access token revoking
To revoke access token, make a POST
request to
https://api.emplifi.io/oauth2/0/token/revocation
endpoint with following request headers and request body.
Request Header
Header | Value |
---|---|
Authorization |
Basic authentication where username is the Client ID and password the Client Secret.
The string "Basic" with your Client ID and Client Secret separated with colon (:), Base64-encoded. For example, client_id:client_secret The final value is Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ= .
|
Content-Type |
application/x-www-form-urlencoded |
Request Body
Parameter | Value |
---|---|
token |
The access token to be revoked. In our example JWefwbpGr3PJyBJjGP3DMaLe5ooX75StcfEb7bgaosn |
The OAuth2 provider will always response with HTTP status 200
.
cURL request example
curl -X POST \
-H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=JWefwbpGr3PJyBJjGP3DMaLe5ooX75StcfEb7bgaosn" \
https://api.emplifi.io/oauth2/0/token/revocation
Limits
Rate limits are defined for account and for user:
- Account: 1000 requests per hour
- User: 500 requests per hour
Each metrics request is limited by maximum number of:
- Profiles: 100
- Metrics: 25
- Date range: 12 months
If you need to query with more profiles, metrics or date range than the limits allow, you can split it into multiple requests.
Sometimes, your request may return Complexity error (code:4)
even if you did not reach any of the limits. This is because the amount of data to return is too large. Try to split your request into multiple smaller ones.
Date range is not relative to current date, so you are able to query historical data.
The oldest historical data you are able to request for is limited by your subscription package.
Rate limit headers with Oauth 2.0 Authorization
When using Oauth 2.0 Authorization, each request to the API will additionally return the following headers to let you know the current state of your quota usage:
HTTP/1.1 200 OK X-RateLimit-Limit: 500, 500;window=3600, 1000;window=3600 X-RateLimit-Remaining: 20 X-RateLimit-Reset: 1201
The X-RateLimit-Limit
header contains the maximum number of requests
you are permitted to make.
There can be multiple entries separated by comma followed by space (,
) in the header.
- The entry is always a number and contains the lowest number of requests you can make for this resource in the current window.
- Starting with the second entry each entry corresponds to a limit that affects this resource.
It is always in format
number_of_requests;window=size_of_the_window_in_seconds
. e.g.500;window=3600
means 500 requests can be made every hour (3600 seconds)
The X-RateLimit-Remaining
header tells you how many requests you have
left to use in the current window.
The X-RateLimit-Reset
header tells you how many seconds until the
current window resets.
The example above shows that the current window resets in 1201 seconds and you can make 20 more requests until then. It also shows that the called endpoint is subject to 2 different limits: one with 500 calls every 3600 seconds and one with 1000 calls every 3600 seconds. It also shows that the closest limit to be hit is the one with 500 calls per 3600 seconds.
Requests failing with status code 429 Too Many Requests
When the number of allowed requests gets exceeded the response
will contain additional header Retry-After
with the number of seconds
until the current window resets.
HTTP/1.1 429 Too Many Requests X-RateLimit-Limit: 500, 500;window=3600, 1000;window=3600 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 800 Retry-After: 800
Errors
If error occurs in any endpoint, standardized error response will be returned.
Error codes
Code | Endpoint | Description | HTTP Status Code |
---|---|---|---|
3 | all |
Input validation error | 200 |
4 | all |
Profiles, metrics, dimensions or date range limit exceeded | 200 |
5 | all |
Profiles not allowed for user | 200 |
6 | all |
Start date is before history limit date | 200 |
7 |
POST /3/linkedin/metrics
|
Profiles do not have insights enabled | 200 |
8 | all |
Labels used for filtering do not exists | 200 |
10 | all |
Account request limit exceeded | 200 |
11 | all |
User request limit exceeded | 200 |
13 | all |
Labeled content or conversation does not exist in Community. | 200 |
14 | POST /3/listening/metrics |
Listening queries not allowed for user | 403 |
15 | all |
Ad accounts not allowed for user | 200 |
16 | all |
Ad accounts have invalid tokens | 200 |
99 | all |
An unknown error occurred | 200 |
400 | all |
Bad request | 400 |
401 | all |
Missing authorization header, invalid secret or token | 401 |
403 | all |
Action is not permitted | 403 |
404 | all |
Resource not allowed | 404 |
405 | all |
HTTP method not allowed | 405 |
500 | all |
Internal server error | 500 |
Example response
{
"success": false,
"errors": [
{
"code": 3,
"errors": [
"Input validation error.",
"Invalid metrics requested: metric1"
]
},
{
"code": 5,
"errors": [
"Profiles not allowed for user.",
"Profiles [164929129743] not allowed."
]
}
]
}
Reference Data
Lists of values allowed to be used by other endpoints as data sources or filters.
List of Connected Profiles
Returns the list of connected Facebook, Instagram, Twitter, YouTube, LinkedIn, Pinterest, TikTok, Snapchat or WhatsApp profiles or Google Businesses for your account. You will need the profile ID later to call metrics endpoints.
Response fields
Name | Description |
---|---|
id | string , profile unique identifier on the social network. |
name | string , profile name |
profile_name | string , profile unique name on the social network. |
picture | string , profile picture on the social network. |
timezone | string , timezone selected for this profile in Emplifi product. |
profile_labels | array , list of labels assigned to a given profile in the account. |
insights_enabled | boolean , available for facebook and instagram networks only, true
if insights metrics are available for profile. |
community_enabled | boolean , true if community content is available for profile. |
Example request
GET /3/{network}/profiles HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
Supported values for {network}
: facebook
, instagram
, twitter
,
youtube
, linkedin
, pinterest
, tiktok
, snapchat
, whatsapp
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
GET /3/post/labels HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
Example response
{
"success": true,
"data": [
{
"id": "5d879004a44a4cbcb13e",
"name": "Content Label 1"
},
{
"id": "ffc196eb056b42fd9b03",
"name": "Content Label 2"
},
...
]
}
List of Content Label Groups
Each Content Label Group can have multiple Content Labels assigned to it. The endpoint returns the list of all private, global, and shared content label groups visible to your user in your account. These groups are identified by name and ID and each of them has an array of IDs of content labels that are assigned to the group.
In order to use this endpoint, you need to have a shared labels and label groups feature enabled in your account. Get in touch with customer support to do so, please.
Response fields
Name | Description |
---|---|
id | string , content label group unique identifier |
name | string , content label group name |
label_ids | array , list of IDs of content labels assigned to this group |
Example request
GET /3/post/label-groups HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
Example response
{
"success": true,
"data": [
{
"id": "138",
"name": "Content Label Group 1",
"label_ids": [
"02782bb93ba340ef9330",
"0134ebd3c6f44d888da5"
]
},
{
"id": "241",
"name": "Content Label Group 2",
"label_ids": [
"02782bb93ba340ef9330"
]
},
...
]
}
List of Profile Labels
Profile labels are used to label profiles across multiple platforms in Suite. The endpoint returns the list of all private, global and shared profile labels visible to your user in your account. These labels are identified by name and ID.
Response fields
Name | Description |
---|---|
id | string , profile label unique identifier |
name | string , profile label name |
profiles | array , information about profile tagged with the specific profile label |
Example request
GET /3/profile/labels HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
Example response
{
"success": true,
"data": [
{
"id": "5d879004a44a4cbcb13e",
"name": "Profile Label 1",
"profiles": [
{
"name": "Profile 1",
"platform": "facebook"
},
{
"name": "Profile 2",
"platform": "twitter"
}
]
},
{
"id": "ffc196eb056b42fd9b03",
"name": "Profile Label 2",
"profiles": [],
},
...
]
}
List of Listening Queries
Queries are keyword-based and they are defined by a name and one or more text-based conditions that specify what you want to monitor. The endpoint returns the list of all Listening queries visible to your user in your account, identified by a unique ID.
Response fields
Name | Description |
---|---|
id | string , Listening query unique identifier |
name | string , Listening query name |
community_enabled | boolean , true if community content is processed by the Listening query |
status | string , possible values are described in tables below |
Status
Active queriesStatus | Description |
---|---|
Running | The query is collecting data within the specified date range. |
Scheduled | The query will start collecting listening mentions on the scheduled date. |
Regulated | The query hit the annual mentions limit set for the query. The query is run again at the beginning of the next billing period. |
Suspended | The query isn’t collecting any data because of reaching the annual limit for the number of listening mentions. The data collection will be renewed at the beginning of the next billing period. |
Status | Description |
---|---|
Paused | The query was paused by the user and it isn’t collecting any listening mentions. |
Done | The query has reached the end date and it isn’t collecting any listening mentions. |
Example request
GET /3/listening/queries HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
Example response
{
"success": true,
"queries": [
{
"id": "LNQ_172196_6241c597857f917a0529975d",
"name": "Listening Query 1",
"community_enabled": false,
"status": "Running",
},
{
"id": "LNQ_172196_6241c5c4dbd2b023b9d97221",
"name": "Listening Query 2",
"community_enabled": true,
"status": "Paused",
},
...
]
}
List of Ad Accounts
The endpoint returns the list of all Ad accounts available to your account and user in specified date range.
Parameters
Name | Description |
---|---|
date_start, date_end |
string , the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
|
Response fields
Name | Description |
---|---|
id | string , ad account unique identifier. |
name | string , ad account name. |
Example request
POST /3/ads/accounts HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"date_start": "2021-01-01",
"date_end": "2022-01-01"
}
Example response
{
"success": true,
"ad_accounts": [
{
"id": "640875043xxxxxx",
"name": "Emplifi 1.0",
},
...
]
}
Profile Metrics
Profile metrics endpoints return daily values for the specified set of metrics and profiles.
Profile metrics attribute data to the profile/page, focusing on when engagement happened, regardless if a post was published during the analyzed date range or not. Data is aggregated by when it happened, and it is not related to a specific piece of content.
Aggregation is the type of calculation used for grouping values of a specific metric.
Facebook Metrics
Returns daily metrics for each requested Facebook profile.
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
The response uses a timezone assigned to a profile in Suite settings of the account.
The last day will be also included in the response.
|
profiles | object , the list of string values. Each is ID of the profile available
from the /3/facebook/profiles endpoint. |
metrics | array , the list of metrics that will be returned in the response. Available metrics are
listed in the table below. |
dimensions | array of {type: dimensionType} objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimension types for each metric in the table below. Dimensions marked with an asterisk* must be last, and only one such dimension can be used. |
Basic Metrics
Name | Dimensions | Aggregation | Metric description |
---|---|---|---|
fans_change |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Absolute change of fans count of a page. |
fans_lifetime |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Total number of likes (=fans) of a page. |
Insights Metrics
Metrics prefixed with insights_
can only be used for profiles that have insights_enabled
property set to true
in the response of the /3/facebook/profiles
endpoint.
Name | Dimensions | Aggregation | Metric description |
---|---|---|---|
insights_fan_adds |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Number of new people who have liked your Page. |
insights_fan_adds_unique |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | New Likes : Number of new people who have liked your Page (Unique Users) |
insights_fan_removes |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Number of Unlikes of your Page (Total Count) |
insights_fan_removes_unique |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Number of Unlikes of your Page (Unique Users). |
insights_fans_lifetime |
date.day ,date.month ,date.week ,profile ,profile_label ,country *,city *,locale *
|
avg | The total number of people who have liked your Page. (Unique Users) |
insights_fans_online
No longer supported
|
date.day ,date.month ,date.week ,profile ,profile_label ,hour_of_day *
|
sum | Number of fans who saw any posts on a given day. |
insights_impressions |
date.day ,date.month ,date.week ,profile ,profile_label ,activity_type *,post_attribution *
|
sum | Total number of times any content associated with your page has been seen |
insights_negative_feedback
No longer supported
|
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | The number of times people have given negative feedback to your Page. (Total Count). |
insights_post_clicks_unique
No longer supported
|
date.day ,date.month ,date.week ,profile ,profile_label ,click_type *
|
avg | The number of people who clicked on any of your content. Clicks that create stories are included in "Other Clicks." Stories that are created without clicking on Page content (ex, liking the Page from timeline) are not included. (Unique Users) |
insights_post_impressions |
date.day ,date.month ,date.week ,profile ,profile_label ,post_attribution *
|
sum | The total number of impressions that came from all of your posts. |
insights_post_reach |
date.day ,date.month ,date.week ,profile ,profile_label ,post_attribution *
|
avg | The number of people who saw any of your Page posts. (Unique Users). Note: The sum of each breakdown from the dimension frequency_distribution will not equal the total of insights_post_reach metric. |
insights_reach |
date.day ,date.month ,date.week ,profile ,profile_label ,post_attribution *,gender_age *
|
avg | The number of people who have seen any content associated with your Page. (Unique Users) |
insights_reach_28_days |
date.day ,date.month ,date.week ,profile ,profile_label ,gender_age *
|
avg | The number of people who have seen any content associated with your Page in the past 28 days. (Unique Users) |
insights_reach_7_days |
date.day ,date.month ,date.week ,profile ,profile_label ,gender_age *
|
avg | The number of people who have seen any content associated with your Page in the past 7 days. (Unique Users) |
insights_reactions |
date.day ,date.month ,date.week ,profile ,profile_label ,reaction_type *
|
sum | The number of reactions on any of your content |
insights_video_complete_views_30s |
date.day ,date.month ,date.week ,profile ,profile_label ,play_type *,post_attribution *
|
sum | Total number of times page's videos have been played for more than 30 seconds |
insights_video_complete_views_30s_repeat_views |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Number of times that people replay a page's videos for more than 30 seconds. |
insights_video_complete_views_30s_unique |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Number of times page's videos have been played for unique people for more than 30 seconds. |
insights_video_repeat_views |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Total number of times that people replay a page's videos for more than 3 seconds |
insights_video_views |
date.day ,date.month ,date.week ,profile ,profile_label ,play_type *,post_attribution *
|
sum | Total number of times page's videos have been played for more than 3 seconds |
insights_video_views_unique |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Total number of times page's videos have been played for unique people for more than 3 seconds |
insights_views |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | The number of times a Page's profile has been viewed by logged in and logged out people. |
Example request
POST /3/facebook/metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"date_start": "2016-01-01",
"date_end": "2016-01-02",
"profiles": [
"164929129743"
],
"metrics": ["fans_lifetime"],
"dimensions": [
{
"type": "date.day"
}
]
}
Example response
{
"success": true,
"header": [
{
"type": "date.day",
"rows": [
"2016-01-01",
"2016-01-02"
]
},
{
"type": "metric",
"rows": [
"fans_lifetime"
]
}
],
"data": [
[
209119
],
[
209171
]
]
}
Instagram Metrics
Returns daily metrics for each requested Instagram profile.
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
The response uses a timezone assigned to a profile in Suite settings of the account.
The last day will be also included in the response.
|
profiles | The list of string values. Each is ID of the profile available from the
/3/instagram/profiles endpoint. |
metrics | The list of metrics that will be returned in the response. Available metrics are listed in the table below. |
dimensions | array of {type: dimensionType} objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimension types for each metric in the table below. Dimensions marked with an asterisk* must be last, and only one such dimension can be used. |
Basic Metrics
Name | Dimensions | Aggregation | Metric description |
---|---|---|---|
followers_change |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Absolute change of followers count lifetime. |
followers_lifetime |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Total number of followed-by of a user by day. Number is aggregated to the midnight of profile timezone. |
following_change |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Absolute change of follows of a user by day. Number is aggregated to the midnight of profile timezone. |
following_lifetime |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Total number of people profile follows. |
Insights Metrics
Metrics prefixed with insights_
can only be used for profiles that have insights_enabled
property set to true
in the response of the /3/instagram/profiles
endpoint.
Name | Dimensions | Aggregation | Metric description |
---|---|---|---|
insights_followers |
date.day ,date.month ,date.week ,profile ,profile_label ,country *,city *,gender_age *
|
avg | Total number of followed-by of a user by day. Total value from this metric may not equal the value from dimension. |
insights_impressions |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Total number of times your posts and stories were viewed. |
insights_impressions_28_days |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Total number of times your posts and stories were viewed in past 28 days. |
insights_impressions_7_days |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Total number of times your posts and stories were viewed in the past 7 days. |
insights_profile_clicks |
date.day ,date.month ,date.week ,profile ,profile_label ,click_target *
|
sum | The number of times user clicked on any contact links on your Business Account's profile. |
insights_profile_views |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | The number of unique accounts who've visited your business profile. |
insights_reach |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Number of unique accounts who viewed your posts and stories. |
insights_reach_28_days |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Total number of people who have viewed any of your posts and stories in the past 28 days. |
insights_reach_7_days |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Total number of people who have viewed any of your posts and stories in the past 7 days. |
Example request
POST /3/instagram/metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"date_start": "2016-01-01",
"date_end": "2016-01-02",
"profiles": ["4108894671", "337453282"],
"metrics": ["followers_change"],
"dimensions": [
{
"type": "date.day"
}
]
}
Example response
{
"success":true,
"header": [
{
"type":"date.day",
"rows": [
"2016-01-01",
"2016-01-02"
]
},
{
"type":"metric",
"rows": [
"followers_change"
]
}
],
"data": [
[
209119
],
[
209171
]
]
}
Twitter Metrics
Returns daily metrics for each requested Twitter profile.
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
The response uses a timezone assigned to a profile in Suite settings of the account.
The last day will be also included in the response.
|
profiles | The list of string values. Each is ID of the profile available from the
/3/twitter/profiles endpoint. |
metrics | The list of metrics that will be returned in the response. Available metrics are listed in the table below. |
dimensions | array of {type: dimensionType} objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimension types for each metric in the table below. Dimensions marked with an asterisk* must be last, and only one such dimension can be used. |
Basic Metrics
Name | Dimensions | Aggregation | Metric description |
---|---|---|---|
ff_ratio |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Ratio of total followers and total following aggregated by day. |
followers_change |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Absolute change of followers (=fans) of a profile. Number is aggregated by day. |
followers_lifetime |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Total number of followers (=fans) of a profile. Number is aggregated by day. |
following_change |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Absolute change of how many people profile follows. Number is aggregated by day. |
following_lifetime |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Total number of how many people profile follows |
listed_change |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Absolute change of on how many lists profile appears. |
listed_lifetime |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Total count of on how many lists profile appears. |
Example request
POST /3/twitter/metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"date_start": "2020-05-10",
"date_end": "2020-05-18",
"profiles": [ "78569316" ],
"metrics": [ "ff_ratio" ],
"dimensions": [
{ "type": "profile" },
{ "type": "date.day" }
]
}
Example response
{
"success": true,
"header": [
{
"type": "profile",
"rows": [
"78569316"
]
},
{
"type": "date.day",
"rows": [
"2020-05-10",
"2020-05-11",
"2020-05-12",
"2020-05-13",
"2020-05-14",
"2020-05-15",
"2020-05-16",
"2020-05-17",
"2020-05-18"
]
},
{
"type": "metric",
"rows": [
"ff_ratio"
]
}
],
"data": [
[
[
95.75070224719101
],
[
95.7436797752809
],
[
95.19622905027933
],
[
95.12351709699931
],
[
95.12072575017446
],
[
95.11235170969994
],
[
95.10118632240057
],
[
95.0907187718074
],
[
95.07327285415212
]
]
]
}
YouTube Metrics
Returns daily metrics for each requested YouTube profile.
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
The response uses a timezone assigned to a profile in Suite settings of the account.
The last day will be also included in the response.
|
profiles | The list of string values. Each is ID of the profile available from the /3/youtube/profiles endpoint. |
metrics | The list of metrics that will be returned in the response. Available metrics are listed in the table below. |
dimensions | array of {type: dimensionType} objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimension types for each metric in the table below. Dimensions marked with an asterisk* must be last, and only one such dimension can be used. |
Metrics
Name | Dimensions | Aggregation | Metric Description |
---|---|---|---|
interaction_change |
date.day ,date.month ,date.week ,profile ,profile_label ,interaction_type *
|
sum | Daily growth of interactions on all uploaded videos by the channel on a given day. Number is aggregated by day to the midnight of UTC timezone. Dislike count is no longer available for this metric as of December 13, 2021 Learn more. |
interactions_per_1k_fans |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Daily growth of interactions per 1000 fans on all uploaded videos by the channel on a given day. Number is aggregated by day to the midnight of UTC timezone. Dislike count is no longer available for this metric as of December 13, 2021 Learn more. |
subscribers_change |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Absolute change of subscribers count lifetime. |
subscribers_lifetime |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Total number of subscribers of the channel. |
video_lifetime |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Total number of uploaded videos by the channel on a given day. Number is aggregated by day to the UTC midnight. |
viewed_time_change |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Absolute daily growth of viewed time. Number is aggregated by day to the midnight of UTC. All values are provided in seconds. |
views_change |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | This is the absolute daily growth of views. Number is aggregated by day to the midnight of UTC timezone. |
Example request
POST /3/youtube/metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"date_start": "2016-01-01",
"date_end": "2016-01-02",
"profiles": [
"UCA6AG33Zac0xi6f9VMTxkFQ",
"UCCAg0pGh47apFzefcJN6x3w"
],
"metrics": ["subscribers_change"],
"dimensions": [
{
"type": "date.day"
}
]
}
Example response
{
"success": true,
"header": [
{
"type": "date.day",
"rows": [
"2016-01-01",
"2016-01-02"
]
},
{
"type": "metric",
"rows": [
"subscribers_change"
]
}
],
"data": [
[
-3
],
[
1
]
]
}
LinkedIn Metrics
Returns daily metrics for each requested LinkedIn profile.
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
The response uses a timezone assigned to a profile in Suite settings of the account.
The last day will be also included in the response.
|
profiles | The list of string values. Each is ID of the profile available from the /3/linkedin/profiles endpoint. |
metrics | The list of metrics that will be returned in the response. Available metrics are listed in the table below. |
dimensions | array of {type: dimensionType} objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimension types for each metric in the table below. Dimensions marked with an asterisk* must be last, and only one such dimension can be used. |
Basic metrics
Basic metrics for Linkedin profiles can be accessed only for profiles that have insights_enabled
property set to true
in the response of the /3/linkedin/profiles
endpoint.
Name | Dimensions | Aggregation | Metric Description |
---|---|---|---|
followers_change |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Absolute change of followers of a company by day. Number is aggregated to the midnight of selected timezone. |
followers_lifetime |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Total number of followers of a company by day. Number is aggregated to the midnight of selected timezone. |
Insights metrics
Metrics prefixed with insights_
can only be used for profiles that have insights_enabled
property set to true
in the response of the /3/linkedin/profiles
endpoint.
Name | Dimensions | Aggregation | Metric Description |
---|---|---|---|
insights_engagements |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Engagements refers to the number of times that users engaged with your posts during the specified date range. Learn More. |
insights_impressions |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | The total number of times any content associated with your page has been seen. |
insights_impressions_engagement_rate |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | The number of impressions received by the content published on your page, divided by the number of people who have seen any content associated with your page. Learn More. |
insights_post_clicks |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | The number of clicks on all the content published on your page. |
insights_reach |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | The number of people who have seen any content associated with your page. |
insights_reach_engagement_rate |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | The number of people who engaged with your page, divided by the number of people who have seen any content associated with your page. Learn More. |
Example request
POST /3/linkedin/metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"date_start": "2016-01-01",
"date_end": "2016-01-02",
"profiles": [
"urn:li:organization:14846557"
],
"metrics": ["followers_change"],
"dimensions": [
{
"type": "date.day"
}
]
}
Example response
{
"success": true,
"header": [
{
"type": "date.day",
"rows": [
"2016-01-01",
"2016-01-02"
]
},
{
"type": "metric",
"rows": [
"followers_change"
]
}
],
"data": [
[
2
],
[
1
]
]
}
Pinterest Metrics
Returns daily metrics for each requested Pinterest profile.
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
The response uses a timezone assigned to a profile in Suite settings of the account.
The last day will be also included in the response.
|
profiles | The list of string values. Each is ID of the profile available from the
/3/pinterest/profiles endpoint. |
metrics | The list of metrics that will be returned in the response. Available metrics are listed in the table below. |
dimensions | array of {type: dimensionType} objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimension types for each metric in the table below. Dimensions marked with an asterisk* must be last, and only one such dimension can be used. |
Metrics
Name | Dimensions | Aggregation | Metric description |
---|---|---|---|
boards_change |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Absolute change of number of profile boards. Number is aggregated by day. |
boards_lifetime |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Total number of boards of the profile. |
followers_change |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Absolute change of followers of a profile. |
followers_lifetime |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Total number of followers of the profile. Number is aggregated by day. |
following_change |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Absolute change of followed profiles. Number is aggregated by day. |
following_lifetime |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Total number of followed profiles. |
pins_lifetime |
date.day ,date.month ,date.week ,profile ,profile_label
|
avg | Total number of pins of the profile. |
Example request
POST /3/pinterest/metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"date_start": "2020-05-10",
"date_end": "2020-05-18",
"profiles": [ "376684093741466051" ],
"metrics": [ "boards_change" ],
"dimensions": [
{ "type": "profile" },
{ "type": "date.day" }
]
}
Example response
{
"success": true,
"header": [
{
"type": "profile",
"rows": [
"376684093741466051"
]
},
{
"type": "date.day",
"rows": [
"2020-05-10",
"2020-05-11",
"2020-05-12",
"2020-05-13",
"2020-05-14",
"2020-05-15",
"2020-05-16",
"2020-05-17",
"2020-05-18"
]
},
{
"type": "metric",
"rows": [
"boards_change"
]
}
],
"data": [
[
[
0
],
[
0
],
[
0
],
[
0
],
[
0
],
[
0
],
[
0
],
[
0
],
[
0
]
]
]
}
TikTok Metrics
Returns daily metrics for each requested TikTok profile.
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
The response uses a timezone assigned to a profile in Suite settings of the account.
The last day will be also included in the response.
|
profiles | The list of string values. Each is ID of the profile available from the /3/tiktok/profiles endpoint. |
metrics | The list of metrics that will be returned in the response. Available metrics are listed in the table below. |
dimensions | array of {type: dimensionType} objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimension types for each metric in the table below. Dimensions marked with an asterisk* must be last, and only one such dimension can be used. |
Insights Metrics
Metrics prefixed with insights_
can only be used for profiles that have insights_enabled
property set to true
in the response of the /3/tiktok/profiles
endpoint.
Name | Dimensions | Aggregation | Metric Description |
---|---|---|---|
insights_engagements |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Engagements returns the number of times that users engaged with your posts during the specified date range. Learn more |
insights_fans_change |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Net growth of the total number of users who follow a profile. |
insights_fans_lifetime |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | The total number of users who follow a profile. |
insights_profile_views |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Total number of users who have viewed the TikTok business account during the specific date range. |
insights_video_views |
date.day ,date.month ,date.week ,profile ,profile_label
|
sum | Total number of times the TikTok profile videos have been viewed during the selected date range. |
Example request
POST /3/tiktok/metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"date_start": "2022-05-01",
"date_end": "2022-05-02",
"profiles": [
"c3694e88-379a-4f3d-9942-acc7203f72e3"
],
"metrics": ["insights_fans_change"],
"dimensions": [
{
"type": "date.day"
}
]
}
Example response
{
"success": true,
"header": [
{
"type": "date.day",
"rows": [
"2022-05-01",
"2022-05-02"
]
},
{
"type": "metric",
"rows": [
"insights_fans_change"
]
}
],
"data": [
[
2
],
[
1
]
]
}
Posts
The endpoints in this section return a list of posts/videos/tweets, accompanied by the fields you specify.
It can be an attribute of the post (text, created time, author, id, paid status) or metric (Number of comments, Number of Likes).
Pagination
These endpoints also supports pagination. You can only get up to a 100 posts per request. To get additional posts, you would need to make subsequent requests by only including the after parameter.
When the response contains remaining
and
next
keys, more posts are available using pagination.
The key remaining
contains the number of items that are
available after the last item in the response.
To request the next page, send the parameter after
set to
value of the next
key from the previous response.
Example request
POST /3/linkedin/page/posts HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"profiles": ["urn:li:organization:2056516"],
"date_start": "2020-01-15",
"date_end": "2020-01-17",
"fields": ["attachments", "comments"],
"sort": [
{
"field": "comments",
"order": "desc"
}
],
"limit": 1
}
Example response
{
"success": true,
"data": {
"posts": [
{
"attachments": [
{
"title": "2020 Vision: Marketers List Year's Top Priorities",
"description": "What will be the top digital marketing trends in 2020? Emplifi gathered thoughts and priorities from marketers across the globe.",
"url": "http://bit.ly/2TzpGXU",
"image_url": "https://www.socialbakers.com/www/storage/www/articles/og-image/2019-12/1577440777-1552993065-og-blog__11tips.jpg",
"type": "link"
}
],
"comments": 2
}
],
"next": "eyJxdWVyeSI6eyJmZWVkVHlwZSI6InVzZXJGZWVkIiwiZmllbGRzIjpbImF0dGFjaG1lbnRzIiwiY29tbWVudENvdW50Iiwib3JpZ2luIiwiYXV0aG9ySWQiLCJwcm9maWxlSWQiLCJtb25pdG9yZWRQcm9maWxlSWQiLCJzdG9yYWdlVHlwZSJdLCJmaWx0ZXJzIjpbeyJ0eXBlIjoib3IiLCJmaWx0ZXJzIjpbeyJ0eXBlIjoiYW5kIiwiZmlsdGVycyI6W3sidHlwZSI6ImNyZWF0ZWRUaW1lIiwicmFuZ2UiOnsiZnJvbSI6IjIwMjAtMDEtMTVUMDA6MDA6MDBaIiwidG8iOiIyMDIwLTAxLTE3VDIzOjU5OjU5WiJ9fSx7InR5cGUiOiJwcm9maWxlSWQiLCJwcm9maWxlcyI6W3sicHJvZmlsZUlkIjpbInVybjpsaTpvcmdhbml6YXRpb246MjA1NjUxNiJdLCJuZXR3b3JrIjoibGlua2VkaW4ifV19XX1dfSx7InR5cGUiOiJuZXR3b3JrIiwidmFsdWUiOlsiZmFjZWJvb2siLCJ0d2l0dGVyIiwicGludGVyZXN0IiwiaW5zdGFncmFtIiwieW91dHViZSIsInZrb250YWt0ZSIsImxpbmtlZGluIl19XSwic29ydCI6W3sidHlwZSI6ImNvbW1lbnRDb3VudCIsIm9yZGVyIjoiZGVzYyJ9LHsidHlwZSI6ImNyZWF0ZWRUaW1lIiwib3JkZXIiOiJkZXNjIn1dLCJsaW1pdCI6MSwiYWNjb3VudElkIjoiMTcyMTk2IiwidXNlcklkIjoiZDE5NTk5NTEiLCJ0b2dnbGVzIjpbIkNPTU1VTklUWV9TRVRfRE9ORV9BRlRFUl9SRVBMWSIsIkFOQUxZVElDU19NT0RVTEUiLCJBVURJRU5DRVNfVEVBU0lORyIsIlBVQkxJU0hfTU9EVUxFIiwiVE9LRU5fRkxPVyIsIkFEU19CRU5DSE1BUktTIiwiTElOS0VESU5fQ09NTVVOSVRZIiwiQVVUT01BVEVEX1NFTlRJTUVOVF9BQ0NFUFRFRCIsIkFEX0FDQ09VTlRTX1JPTEVTX1BFUk1JU1NJT05TIiwiQVBQUk9WQUxfRkxPVyIsIkFVVE9MQUJFTElORyIsIkRBU0hCT0FSRF9PTU5JX1dJREdFVFMiLCJGSUxFU1RBQ0tfRlVMTCIsIklOU1RBR1JBTV9BRFNfUFVCX0NPTSIsIklOU1RBR1JBTV9WSURFT19QVUJMSVNISU5HIiwiTElOS0VESU5fUFVCTElTSElORyIsIk1PQklMRV9DT01NVU5JVFlfTU9EVUxFIiwiQ09OVEVOVF9IVUJfTU9EVUxFIiwiUlVMRV9CQVNFRF9MQUJFTElORyIsIkNPTlRFTlRfSFVCX0NPTExFQ1RJT05TIiwiUEFJRF9NT0RVTEUiLCJQVUJMSVNIRVJfRVhURVJOQUwiLCJUV19JTlNJR0hUUyIsIkNPTU1VTklUWV9NT0RVTEUiLCJBRFNfQkVOQ0hNQVJLU19GVUxMX0FDQ0VTUyIsIkJFTkNITUFSS1NfTVVMVElDT01QQVJFIiwiQ0FNUEFJR05fVklFVyIsIkNPTlRFTlRfU0VBUkNIX1BSTyIsIkRBU0hCT0FSRF9NT0RVTEUiLCJHT09HTEVfQU5BTFlUSUNTIiwiTElTVEVOSU5HIiwiTElWRV9WSURFT19NRVRSSUNTIiwiUEFJRF9QT1NUX0RFVEVDVElPTiIsIlBBSURfUE9TVF9ERVRFQ1RJT05fSUciLCJQT1NUX0JPT1NUSU5HIiwiUFJJTUVUSU1FIiwiVklERU9fQkVOQ0hNQVJLU19GVUxMX0FDQ0VTUyIsIkJVU0lORVNTX1RPR0dMRV9QVUJMSVNIRVJfSUdfVVNFUlNfVEFHR0lORyIsIklORkxVRU5DRVJTX01PRFVMRSIsIlBFUk1JU1NJT05TX0JZX1NFQ1RJT05TIiwiQlVTSU5FU1NfVE9HR0xFX1NUT1JJRVNfU0NIRURVTElORyIsIkJVU0lORVNTX1RPR0dMRV9BU1RVVEVfSU5URUdSQVRJT04iLCJCVVNJTkVTU19UT0dHTEVfTElOS0VESU5fVEFSR0VUSU5HIiwiQlVTSU5FU1NfVE9HR0xFX1BVQkxJU0hFUl9JR19MT0NBVElPTl9UQUdHSU5HIiwiQ09OVEVOVF9QUkVESUNUSU9OIiwiQ09OVEVOVF9QUkVESUNUSU9OX0lHIiwiUFVCTElTSEVSX0ZCX1NDSEVEVUxJTkciLCJCVVNJTkVTU19UT0dHTEVfUFVCTElDX0RBU0hCT0FSRCIsIkVOR0FHRU1FTlRfUkFURV9FU1RFX0xBVURFUiIsIkNPTlRFTlRfU0VOVElNRU5UIiwiQVVUT01BVEVEX1NFTlRJTUVOVCIsIkJVU0lORVNTX1RPR0dMRV9PUkdBTklDX0FOQUxZVElDUyIsIkJVU0lORVNTX1RPR0dMRV9MSVNURU5JTkdfTU9EVUxFIiwiQlVTSU5FU1NfVE9HR0xFX0lHX09SR0FOSUNfUEFJRF9SRU1PVkFMX0lOVEVSSU0iLCJCVVNJTkVTU19UT0dHTEVfSUdfT1JHQU5JQ19QQUlEX1JFTU9WQUxfRklOQUwiLCJCRVRBX01PQklMRV9DT01NVU5JVFlfTU9EVUxFIiwiQVVESUVOQ0VTX01PRFVMRSIsIkJVU0lORVNTX1RPR0dMRV9DT01NVU5JVFlfUkVQT1JUSU5HIiwiU1VJVEVfQURTIiwiQlVTSU5FU1NfVE9HR0xFX1BBSURfU1RPUkVEX0RBVEEiLCJCVVNJTkVTU19UT0dHTEVfUFJJT1JJVFlfU0NPUkUiLCJJTkZMVUVOQ0VSU19GVUxMX0FDQ0VTUyJdLCJwcm9maWxlcyI6W3sicHJvZmlsZUlkIjpbInVybjpsaTpvcmdhbml6YXRpb246MjA1NjUxNiJdLCJuZXR3b3JrIjoibGlua2VkaW4iLCJ0aW1lem9uZSI6IlVUQyIsImluc2lnaHRzIjpmYWxzZSwibWFuYWdlZCI6ZmFsc2UsImluc3RhZ3JhbVRva2VuIjpmYWxzZSwiaXNBdXRvU2VudGltZW50RW5hYmxlZCI6dHJ1ZSwiaW5mbHVlbmNlckluc2lnaHRzIjpmYWxzZX1dLCJjcmVhdGVkVGltZSI6eyJmcm9tIjoiMjAyMC0wMS0xNVQwMDowMDowMFoiLCJ0byI6IjIwMjAtMDEtMTdUMjM6NTk6NTlaIn19LCJjdXJzb3IiOnsic29ydCI6W3sidHlwZSI6ImNvbW1lbnRDb3VudCIsInZhbHVlIjoyLCJvcmRlciI6ImRlc2MifSx7InR5cGUiOiJjcmVhdGVkVGltZSIsInZhbHVlIjoxNTc5MjY4MjYxMDAwLCJvcmRlciI6ImRlc2MifV0sImxhc3RTb3J0SGFzaCI6Iis5MDA3MTk5MjU0NzQwOTkwXys5MDA1NjE5OTg2NDc5OTkyIiwiaWRzIjpbInVybjpsaTpzaGFyZTo2NjIzOTMxMTg1NDE0MzI4MzIwIl19LCJ0b3RhbCI6OCwic2Nyb2xsQ291bnQiOjEsInNjcm9sbGVkQ291bnQiOjF9",
"remaining": 7
}
}
Next page request
POST /3/linkedin/page/posts HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"after": "eyJxdWVyeSI6eyJmZWVkVHlwZSI6InVzZXJGZWVkIiwiZmllbGRzIjpbImF0dGFjaG1lbnRzIiwiY29tbWVudENvdW50Iiwib3JpZ2luIiwiYXV0aG9ySWQiLCJwcm9maWxlSWQiLCJtb25pdG9yZWRQcm9maWxlSWQiLCJzdG9yYWdlVHlwZSJdLCJmaWx0ZXJzIjpbeyJ0eXBlIjoib3IiLCJmaWx0ZXJzIjpbeyJ0eXBlIjoiYW5kIiwiZmlsdGVycyI6W3sidHlwZSI6ImNyZWF0ZWRUaW1lIiwicmFuZ2UiOnsiZnJvbSI6IjIwMjAtMDEtMTVUMDA6MDA6MDBaIiwidG8iOiIyMDIwLTAxLTE3VDIzOjU5OjU5WiJ9fSx7InR5cGUiOiJwcm9maWxlSWQiLCJwcm9maWxlcyI6W3sicHJvZmlsZUlkIjpbInVybjpsaTpvcmdhbml6YXRpb246MjA1NjUxNiJdLCJuZXR3b3JrIjoibGlua2VkaW4ifV19XX1dfSx7InR5cGUiOiJuZXR3b3JrIiwidmFsdWUiOlsiZmFjZWJvb2siLCJ0d2l0dGVyIiwicGludGVyZXN0IiwiaW5zdGFncmFtIiwieW91dHViZSIsInZrb250YWt0ZSIsImxpbmtlZGluIl19XSwic29ydCI6W3sidHlwZSI6ImNvbW1lbnRDb3VudCIsIm9yZGVyIjoiZGVzYyJ9LHsidHlwZSI6ImNyZWF0ZWRUaW1lIiwib3JkZXIiOiJkZXNjIn1dLCJsaW1pdCI6MSwiYWNjb3VudElkIjoiMTcyMTk2IiwidXNlcklkIjoiZDE5NTk5NTEiLCJ0b2dnbGVzIjpbIkNPTU1VTklUWV9TRVRfRE9ORV9BRlRFUl9SRVBMWSIsIkFOQUxZVElDU19NT0RVTEUiLCJBVURJRU5DRVNfVEVBU0lORyIsIlBVQkxJU0hfTU9EVUxFIiwiVE9LRU5fRkxPVyIsIkFEU19CRU5DSE1BUktTIiwiTElOS0VESU5fQ09NTVVOSVRZIiwiQVVUT01BVEVEX1NFTlRJTUVOVF9BQ0NFUFRFRCIsIkFEX0FDQ09VTlRTX1JPTEVTX1BFUk1JU1NJT05TIiwiQVBQUk9WQUxfRkxPVyIsIkFVVE9MQUJFTElORyIsIkRBU0hCT0FSRF9PTU5JX1dJREdFVFMiLCJGSUxFU1RBQ0tfRlVMTCIsIklOU1RBR1JBTV9BRFNfUFVCX0NPTSIsIklOU1RBR1JBTV9WSURFT19QVUJMSVNISU5HIiwiTElOS0VESU5fUFVCTElTSElORyIsIk1PQklMRV9DT01NVU5JVFlfTU9EVUxFIiwiQ09OVEVOVF9IVUJfTU9EVUxFIiwiUlVMRV9CQVNFRF9MQUJFTElORyIsIkNPTlRFTlRfSFVCX0NPTExFQ1RJT05TIiwiUEFJRF9NT0RVTEUiLCJQVUJMSVNIRVJfRVhURVJOQUwiLCJUV19JTlNJR0hUUyIsIkNPTU1VTklUWV9NT0RVTEUiLCJBRFNfQkVOQ0hNQVJLU19GVUxMX0FDQ0VTUyIsIkJFTkNITUFSS1NfTVVMVElDT01QQVJFIiwiQ0FNUEFJR05fVklFVyIsIkNPTlRFTlRfU0VBUkNIX1BSTyIsIkRBU0hCT0FSRF9NT0RVTEUiLCJHT09HTEVfQU5BTFlUSUNTIiwiTElTVEVOSU5HIiwiTElWRV9WSURFT19NRVRSSUNTIiwiUEFJRF9QT1NUX0RFVEVDVElPTiIsIlBBSURfUE9TVF9ERVRFQ1RJT05fSUciLCJQT1NUX0JPT1NUSU5HIiwiUFJJTUVUSU1FIiwiVklERU9fQkVOQ0hNQVJLU19GVUxMX0FDQ0VTUyIsIkJVU0lORVNTX1RPR0dMRV9QVUJMSVNIRVJfSUdfVVNFUlNfVEFHR0lORyIsIklORkxVRU5DRVJTX01PRFVMRSIsIlBFUk1JU1NJT05TX0JZX1NFQ1RJT05TIiwiQlVTSU5FU1NfVE9HR0xFX1NUT1JJRVNfU0NIRURVTElORyIsIkJVU0lORVNTX1RPR0dMRV9BU1RVVEVfSU5URUdSQVRJT04iLCJCVVNJTkVTU19UT0dHTEVfTElOS0VESU5fVEFSR0VUSU5HIiwiQlVTSU5FU1NfVE9HR0xFX1BVQkxJU0hFUl9JR19MT0NBVElPTl9UQUdHSU5HIiwiQ09OVEVOVF9QUkVESUNUSU9OIiwiQ09OVEVOVF9QUkVESUNUSU9OX0lHIiwiUFVCTElTSEVSX0ZCX1NDSEVEVUxJTkciLCJCVVNJTkVTU19UT0dHTEVfUFVCTElDX0RBU0hCT0FSRCIsIkVOR0FHRU1FTlRfUkFURV9FU1RFX0xBVURFUiIsIkNPTlRFTlRfU0VOVElNRU5UIiwiQVVUT01BVEVEX1NFTlRJTUVOVCIsIkJVU0lORVNTX1RPR0dMRV9PUkdBTklDX0FOQUxZVElDUyIsIkJVU0lORVNTX1RPR0dMRV9MSVNURU5JTkdfTU9EVUxFIiwiQlVTSU5FU1NfVE9HR0xFX0lHX09SR0FOSUNfUEFJRF9SRU1PVkFMX0lOVEVSSU0iLCJCVVNJTkVTU19UT0dHTEVfSUdfT1JHQU5JQ19QQUlEX1JFTU9WQUxfRklOQUwiLCJCRVRBX01PQklMRV9DT01NVU5JVFlfTU9EVUxFIiwiQVVESUVOQ0VTX01PRFVMRSIsIkJVU0lORVNTX1RPR0dMRV9DT01NVU5JVFlfUkVQT1JUSU5HIiwiU1VJVEVfQURTIiwiQlVTSU5FU1NfVE9HR0xFX1BBSURfU1RPUkVEX0RBVEEiLCJCVVNJTkVTU19UT0dHTEVfUFJJT1JJVFlfU0NPUkUiLCJJTkZMVUVOQ0VSU19GVUxMX0FDQ0VTUyJdLCJwcm9maWxlcyI6W3sicHJvZmlsZUlkIjpbInVybjpsaTpvcmdhbml6YXRpb246MjA1NjUxNiJdLCJuZXR3b3JrIjoibGlua2VkaW4iLCJ0aW1lem9uZSI6IlVUQyIsImluc2lnaHRzIjpmYWxzZSwibWFuYWdlZCI6ZmFsc2UsImluc3RhZ3JhbVRva2VuIjpmYWxzZSwiaXNBdXRvU2VudGltZW50RW5hYmxlZCI6dHJ1ZSwiaW5mbHVlbmNlckluc2lnaHRzIjpmYWxzZX1dLCJjcmVhdGVkVGltZSI6eyJmcm9tIjoiMjAyMC0wMS0xNVQwMDowMDowMFoiLCJ0byI6IjIwMjAtMDEtMTdUMjM6NTk6NTlaIn19LCJjdXJzb3IiOnsic29ydCI6W3sidHlwZSI6ImNvbW1lbnRDb3VudCIsInZhbHVlIjoyLCJvcmRlciI6ImRlc2MifSx7InR5cGUiOiJjcmVhdGVkVGltZSIsInZhbHVlIjoxNTc5MjY4MjYxMDAwLCJvcmRlciI6ImRlc2MifV0sImxhc3RTb3J0SGFzaCI6Iis5MDA3MTk5MjU0NzQwOTkwXys5MDA1NjE5OTg2NDc5OTkyIiwiaWRzIjpbInVybjpsaTpzaGFyZTo2NjIzOTMxMTg1NDE0MzI4MzIwIl19LCJ0b3RhbCI6OCwic2Nyb2xsQ291bnQiOjEsInNjcm9sbGVkQ291bnQiOjF9"
}
Facebook Posts
Returns a set of posts created during the specified date range for each requested Facebook profile. Facebook posts endpoint returns lifetime values of the metrics.
Parameters
Name | Description |
---|---|
profiles |
array , list of profile IDs of the profiles available from the /3/facebook/profiles endpoint.
|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
Your request is transformed using the time zone assigned to a profile in the Suite settings of your account.
The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct
timezone using the timezone of each individual profile from the /3/facebook/profiles endpoint.
The last day will be also included in the response.
|
fields |
array , the list of fields that will be returned in the response. Available fields are listed in
the table below.
|
limit |
integer , (optional). The number of results per page. The default value is 10 and the maximal value is 100.
|
sort |
(optional), You can sort the results by specifying a field and sorting order in the sort object: "field": "created_time"
and "order": "desc" . See the list of fields allowed
for sorting.
|
filter |
(optional), You can filter results by providing the filter parameter with field and value . See
the list of fields allowed for filtering.
|
Parameter for Pagination
after |
string , value of the next property from previous response.
|
Basic Fields
Name | Type | Example | Description |
---|---|---|---|
attachments |
array
|
|
Details about post attachments. |
author |
object
|
|
Author details of the post. |
authorId |
string
|
|
The id of the post author. |
comments |
integer
|
|
Total number of comments. |
comments_sentiment |
object
|
|
Total sentiment for the comments of the post. Sum of sentiment breakdown might not equal the total comments. There would be comments which sentiment are either unassigned or undetected. For stories, this value is undefined since users can not comment on them. |
content |
string
|
|
Content of the Facebook post. |
content_type |
string
|
|
Content type of the Facebook post. |
created_time |
datetime
|
|
Date and time the post was created in Facebook. |
deleted |
boolean
|
|
Describes if the post has been deleted on Facebook. |
grade |
string
|
|
Grade score of the post. |
hidden |
boolean
|
|
Describes if the post has been hidden from Facebook. |
id |
string
|
|
Facebook post id. |
interactions |
integer
|
|
Sum of reactions, comments and shares. |
interactions_per_1k_fans |
float
|
|
Interaction count for every 1000 fans. |
media_type |
string
|
|
Type of Facebook post. |
origin |
string
|
|
Source of post. |
page |
object
|
|
Information about the Facebook page. |
post_attribution |
object
|
|
Type of post whether it's organic or paid. For posts from a profile with insights connected, data comes directly from Facebook. For the rest of the posts, the attribution is based on Socialbakers Paid Post Detection algorithm. |
post_labels |
array
|
|
Content labels (formally post labels) assigned to the post. |
profileId |
string
|
|
The id of the Facebook page. |
published |
boolean
|
|
Describes if the post is published. |
reactions |
integer
|
|
Total number of reactions. |
reactions_by_type |
object
|
|
Breakdown of reactions. |
sentiment |
string
|
|
Facebook page post sentiment. |
shares |
integer
|
|
Number of times the post has been shared. |
spam |
boolean
|
|
Describes if the post has been marked as spam. |
universal_video_id |
integer
|
|
The publishers asset management code for this video. Only available in case the post type is a video. |
url |
string
|
|
Link to the Facebook post. |
video |
object
|
|
Details about the post's video. |
Insights Fields
Metrics prefixed with insights_
can only be used for profiles that have insights_enabled
property set to true
in the response of the /3/facebook/profiles
endpoint.
Name | Type | Example | Description |
---|---|---|---|
insights_engaged_users |
integer
|
|
The number of people who clicked anywhere in your posts |
insights_engagements |
integer
|
|
Engagements inform about how many times users engaged with a post during its lifetime. Learn More. |
insights_impressions |
integer
|
|
The number of impressions for your post. |
insights_impressions_by_post_attribution |
object
|
|
The number of impressions broken down by post attribution. |
insights_impressions_engagement_rate |
float
|
|
Impressions Engagement Rate informs about the percentage of users who engaged with a post during its lifetime given its impressions. Learn More. |
insights_interactions |
integer
|
|
Sum of reactions, comments and shares. |
insights_interactions_by_interaction_type |
object
|
|
Count of reactions, comments and shares. |
insights_negative_feedback_unique |
integer
|
|
The number of people who took a negative action in your post (hid it, for example) |
insights_post_clicks |
integer
|
|
The number of times people clicked on anywhere in your posts without generating an activity. |
insights_post_clicks_by_clicks_type |
object
|
|
The number of times people clicked on anywhere in your posts without generating an activity. |
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 post. |
insights_reach_by_post_attribution |
object
|
|
The number of people who saw your post. |
insights_reach_engagement_rate |
float
|
|
Reach Engagement Rate informs about the percentage of users who engaged with a post during its lifetime given its reach. Learn More. |
insights_reactions |
integer
|
|
Total reactions. |
insights_reactions_by_type |
object
|
|
Breakdown of reactions. |
insights_video_view_time |
integer
|
|
The total number of seconds your video was watched, including replays and views less than 3 seconds. |
insights_video_view_time_average |
float
|
|
The average length in seconds people spent watching your video. |
insights_video_view_time_by_country |
object
|
|
The total number of seconds your video was watched, including replays and views less than 3 seconds. |
insights_video_view_time_by_distribution |
object
|
|
The total number of seconds your video was watched, including replays and views less than 3 seconds. |
insights_video_view_time_by_gender_age |
object
|
|
The total number of seconds your video was watched, including replays and views less than 3 seconds. |
insights_video_view_time_by_post_attribution |
object
|
|
The total number of seconds your video was watched, including replays and views less than 3 seconds. |
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_10s |
integer
|
|
The number of times your video has been viewed for more than 10 seconds. |
insights_video_views_10s_by_play_type |
object
|
|
The number of times your video has been viewed for more than 10 seconds. |
insights_video_views_10s_by_post_attribution |
object
|
|
The number of times your video has been viewed for more than 10 seconds. |
insights_video_views_10s_by_sound |
object
|
|
The number of times your video has been viewed for more than 10 seconds. |
insights_video_views_10s_unique |
integer
|
|
The number of people who have watched your video for at least 10 seconds. |
insights_video_views_30s |
integer
|
|
The number of times your video has been viewed for more than 30 seconds. |
insights_video_views_30s_by_play_type |
object
|
|
The number of times your video has been viewed for more than 30 seconds. |
insights_video_views_30s_by_post_attribution |
object
|
|
The number of times your video has been viewed for more than 30 seconds. |
insights_video_views_30s_unique |
integer
|
|
The number of people who have watched your video for at least 30 seconds. |
insights_video_views_average_completion |
float
|
|
The average percentage of a video watched during a video playback collected during the lifetime of the video. |
insights_video_views_by_play_type |
object
|
|
The number of times your video was watched for an aggregate of at least 3 seconds, or for nearly its total length, whichever happened first. |
insights_video_views_by_post_attribution |
object
|
|
The number of times your video was watched for an aggregate of at least 3 seconds, or for nearly its total length, whichever happened first. |
insights_video_views_by_sound |
object
|
|
The number of times your video was watched for an aggregate of at least 3 seconds, or for nearly its total length, whichever happened first. |
insights_video_views_complete |
integer
|
|
The number of times your video has been viewed for about 95% of its length. |
insights_video_views_complete_by_post_attribution |
object
|
|
The number of times your video has been viewed for about 95% of its length. |
insights_video_views_complete_unique |
integer
|
|
The number of people who have watched your video for about 95% of its length. |
insights_video_views_complete_unique_by_post_attribution |
object
|
|
The number of people who have watched your video for about 95% of its length. |
insights_video_views_distribution |
object
|
|
The number of times your video was watched for an aggregate of at least 3 seconds, or for nearly its total length, whichever happened first. |
insights_video_views_unique |
integer
|
|
The number of people who have watched your video for at least 3 seconds. |
insights_video_views_unique_by_post_attribution |
object
|
|
The number of people who have watched your video for at least 3 seconds. |
Fields that might be used to sort Facebook posts:
Basic Fields- comments
- created_time
- interactions
- interactions_per_1k_fans
- reactions
- reactions_by_type.anger
- reactions_by_type.haha
- reactions_by_type.like
- reactions_by_type.love
- reactions_by_type.sorry
- reactions_by_type.wow
- shares
- insights_engaged_users
- insights_post_clicks
- insights_reach_by_post_attribution.organic
- insights_reach_by_post_attribution.paid
- insights_video_view_time_average
- insights_video_views_10s
- insights_video_views_by_post_attribution.organic
- insights_video_views_by_post_attribution.paid
Fields that might be used to filter Facebook posts:
Field | Allowed values | Description | Advanced filter support |
---|---|---|---|
content_type | post shared |
Content type of the Facebook post. | ✅ Supported operators:
|
grade | A+ A B C D |
Grade score of the post. | ✅ Supported operators:
|
media_type | status link video note poll offer photo carousel reel |
Type of Facebook post. | ✅ Supported operators:
|
origin | User-Generated Content Brand's Content |
Source of post. | ✅ Supported operators:
|
post_attribution | organic paid |
Type of post whether it's organic or paid. For posts from a profile with insights connected, data comes directly from Facebook. For the rest of the posts, the attribution is based on Socialbakers Paid Post Detection algorithm. | ✅ Supported operators:
|
post_labels | * Pattern: .+ |
Content labels (formally post labels) assigned to the post. | ✅ Supported operators:
|
video_type | crosspost crosspostable live shared |
Filter results by specific video types, an attribute of Facebook that belongs only to Facebook Video. Filter by Shared, Crosspost (Videos that have been reused from another profile), Crosspostable (Videos that have been made available for crossposting by their owner) and Live videos. | ✅ Supported operators:
|
Response
Name | Description |
---|---|
success | Status of the response. Possible values are true or false. |
data |
object containing the following properties:
|
Example request
POST /3/facebook/page/posts HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"profiles": [
"164929129743",
"543567853435"
],
"date_start": "2017-07-01",
"date_end": "2017-10-25",
"fields": [
"id",
"created_time",
"author",
"content_type",
"hidden",
"media_type",
"post_attribution",
"post_labels"
],
"sort": [
{
"field": "created_time",
"order": "desc"
}
],
"filter": [
{
"field": "post_attribution",
"value": "organic"
}
],
"limit": 5
}
Example response
{
"success": true,
"data": {
"posts": [
{
"id": "164929129743_10155892118379744",
"created_time": "2017-10-25T16:06:00+00:00",
"author": {
"id": "164929129743",
"name": "Socialbakers",
"url": "https://www.facebook.com/socialbakers"
},
"content_type": "post",
"hidden": false,
"media_type": "link",
"post_attribution": {
"status": "organic",
"type": "insights"
},
"post_labels": []
}
],
"next": "eyJuZXh0IjoiZXlKeGRXVnllU0k2ZXlKbVpXVmtWSGx3WlNJNkluVnpaWEpHWldWa0lpd2labWxsYkdSeklqcGJJbWxrSWl3aVkzSmxZWFJsWkZScGJXVWlMQ0poZFhSb2IzSkpibVp2SWl3aVkyOXVQ==",
"remaining": 194
}
}
Instagram Posts
Returns a set of posts created during the specified date range for each requested Instagram profile. Instagram posts endpoint returns lifetime values of the metrics.
Parameters
Name | Description |
---|---|
profiles |
array , list of profile IDs of the profiles available from the /3/instagram/profiles endpoint.
|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
Your request is transformed using the time zone assigned to a profile in the Suite settings of your account.
The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct
timezone using the timezone of each individual profile from the /3/instagram/profiles endpoint.
The last day will be also included in the response.
|
fields |
array , the list of fields that will be returned in the response. Available fields are listed in
the table below.
|
limit |
integer , (optional). The number of results per page. The default value is 10 and the maximal value is 100.
|
sort |
(optional), You can sort the results by specifying a field and sorting order in the sort object: "field": "created_time"
and "order": "desc" . See the list of fields allowed
for sorting.
|
filter |
(optional), You can filter results by providing the filter parameter with field and value . See
the list of fields allowed for filtering.
|
Parameter for Pagination
after |
string , value of the next property from previous response.
|
Basic Fields
Name | Type | Example | Description |
---|---|---|---|
attachments |
array
|
|
Details about post attachments. |
author |
object
|
|
Author details of the post. |
authorId |
string
|
|
The id of the post author. |
comments |
integer
|
|
Total number of comments. |
comments_sentiment |
object
|
|
Total sentiment for the comments of the post. Sum of sentiment breakdown might not equal the total comments. There would be comments which sentiment are either unassigned or undetected. For stories, this value is undefined since users can not comment on them. |
content |
string
|
|
Content of the Instagram post. |
content_type |
string
|
|
Content type of the Instagram post. |
created_time |
datetime
|
|
Date and time the post was created in Instagram. |
grade |
string
|
|
Grade score of the post. |
id |
string
|
|
Instagram post or story id. |
interactions |
integer
|
|
Sum of reactions and comments. |
interactions_per_1k_fans |
float
|
|
Interaction count for every 1000 fans. |
likes |
integer
|
|
Total number of likes. |
media_type |
string
|
|
Type of Instagram post. |
origin |
string
|
|
Source of post. |
page |
object
|
|
Information about the Instagram profile. |
post_attribution |
object
|
|
Type of post whether it's organic or paid. For posts from a profile with insights connected, data comes directly from Instagram. For the rest of the posts, the attribution is based on Socialbakers Paid Post Detection algorithm. |
post_labels |
array
|
|
Content labels (formally post labels) assigned to the post. |
profileId |
string
|
|
The id of the Instagram page. |
sentiment |
string
|
|
Instagram post sentiment. |
url |
string
|
|
Link to the Instagram post. |
Insights Fields
Metrics prefixed with insights_
can only be used for profiles that have insights_enabled
property set to true
in the response of the /3/instagram/profiles
endpoint.
Name | Type | Example | Description |
---|---|---|---|
insights_engagement |
integer
|
|
Engagements inform about how many times users engaged with a post during its lifetime. Learn More. |
insights_engagement_by_engagement_type |
object
|
|
Breakdown of insights_engagement. |
insights_impressions |
integer
|
|
The number of impressions for your post. |
insights_impressions_engagement_rate |
float
|
|
Impressions Engagement Rate informs about the percentage of users who engaged with a post during its lifetime given its impressions. Learn More. |
insights_initial_video_views |
integer
|
|
The number of first-time plays of your Instagram reel, including plays of 1ms or more. This metric excludes replays. |
insights_reach |
integer
|
|
Number of people who saw your post. |
insights_reach_engagement_rate |
float
|
|
Reach Engagement Rate informs about the percentage of users who engaged with a post during its lifetime given its reach. Learn More. |
insights_saves |
integer
|
|
Number of unique accounts that saved your post. |
insights_story_completion_rate |
float
|
|
The percentage of times a story impression was not interrupted by an exit, tap back, or tap forward. |
insights_story_exits |
integer
|
|
The number of times users exited your story. |
insights_story_replies |
integer
|
|
The number of times users replied to your story. |
insights_story_taps_back |
integer
|
|
The number of times users clicked back to return to the previous story. |
insights_story_taps_forward |
integer
|
|
The number of times users clicked forward to skip to the next story. |
insights_video_views |
integer
|
|
Total number of times your video has been seen. For Instagram Reels number of plays are counted as video views. Plays are defined as video sessions with 1 ms + of playback, excluding replays. |
Fields that might be used to sort Instagram posts:
Basic Fields- comments
- created_time
- interactions
- interactions_per_1k_fans
- likes
- insights_impressions
- insights_initial_video_views
- insights_reach
- insights_saves
- insights_story_completion_rate
- insights_story_exits
- insights_story_taps_back
- insights_story_taps_forward
- insights_video_views
Fields that might be used to filter Instagram posts:
Field | Allowed values | Description | Advanced filter support |
---|---|---|---|
content_type | post story |
Content type of the Instagram post. | ✅ Supported operators:
|
grade | A+ A B C D |
Grade score of the post. | ✅ Supported operators:
|
media_type | video photo carousel video_igtv reel |
Type of Instagram post. | ✅ Supported operators:
|
origin | User-Generated Content Brand's Content |
Source of post. | ✅ Supported operators:
|
post_attribution | organic paid |
Type of post whether it's organic or paid. For posts from a profile with insights connected, data comes directly from Instagram. For the rest of the posts, the attribution is based on Socialbakers Paid Post Detection algorithm. | ✅ Supported operators:
|
post_labels | * Pattern: .+ |
Content labels (formally post labels) assigned to the post. | ✅ Supported operators:
|
Response
Name | Description |
---|---|
success | Status of the response. Possible values are true or false. |
data |
object containing the following properties:
|
Example request
POST /3/instagram/profile/posts HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"profiles": ["490402220", "55674325"],
"date_start": "2020-06-01",
"date_end": "2020-08-31",
"fields": [
"id",
"created_time",
"author",
"content_type",
"media_type",
"post_attribution",
"post_labels"
],
"sort": [
{
"field": "created_time",
"order": "desc"
}
],
"filter": [
{
"field": "media_type",
"value": "photo"
}
],
"limit": 1
}
Example response
{
"success": true,
"data": {
"posts": [
{
"id": "17966172199068623_490402220",
"created_time": "2020-06-25T16:06:00+00:00",
"author": {
"id": "490402220",
"name": "Socialbakers",
"url": "https://www.instagram.com/socialbakers"
},
"content_type": "post",
"media_type": "photo",
"post_attribution": {
"status": "organic",
"type": "insights"
},
"post_labels": []
}
]
}
}
YouTube Videos
Returns a set of videos created during the specified date range for each requested YouTube channels. YouTube videos endpoint returns lifetime values of the metrics.
Parameters
Name | Description |
---|---|
profiles |
array , list of profile IDs of the profiles available from the /3/youtube/profiles endpoint.
|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
Your request is transformed using the time zone assigned to a profile in the Suite settings of your account.
The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct
timezone using the timezone of each individual profile from the /3/youtube/profiles endpoint.
The last day will be also included in the response.
|
fields |
array , the list of fields that will be returned in the response. Available fields are listed in
the table below.
|
limit |
integer , (optional). The number of results per page. The default value is 10 and the maximal value is 100.
|
sort |
(optional), You can sort the results by specifying a field and sorting order in the sort object: "field": "created_time"
and "order": "desc" . See the list of fields allowed
for sorting.
|
filter |
(optional), You can filter results by providing the filter parameter with field and value . See
the list of fields allowed for filtering.
|
Parameter for Pagination
after |
string , value of the next property from previous response.
|
Basic Fields
Name | Type | Example | Description |
---|---|---|---|
author |
object
|
|
Author details of the video. |
authorId |
string
|
|
The id of the video author. |
channel |
object
|
|
Information about the Youtube channel. |
comments |
integer
|
|
Total number of comments. |
created_time |
datetime
|
|
Date and time the video was uploaded on Youtube. |
description |
string
|
|
Description of the Youtube video. |
dislikes |
integer
|
|
Number of dislikes for the video. Dislike count is no longer available as of December 13, 2021 Learn more. |
duration |
integer
|
|
Length of the video in seconds. |
id |
string
|
|
Youtube video id. |
insights_engagement |
integer
|
|
Engagements inform about how many times users engaged with a post during its lifetime. Learn More. |
interactions |
integer
|
|
Sum of likes and comments. Dislike count is no longer available for this metric as of December 13, 2021 Learn more. |
interactions_per_1k_fans |
float
|
|
Interaction count for every 1000 subscribers. Dislike count is no longer available for this metric as of December 13, 2021 Learn more. |
likes |
integer
|
|
Number of likes for the video. |
media_type |
string
|
|
Type of Youtube video. |
post_labels |
array
|
|
Content labels (formally post labels) assigned to the video. |
profileId |
string
|
|
The id of the Youtube profile. |
url |
string
|
|
Link to the Youtube video. |
video_view_time |
integer
|
|
Number of times the video has been viewed multiplied by the duration in seconds. |
video_views |
integer
|
|
Number of times the video has been viewed. |
Fields that might be used to sort YouTube profile video:
Basic Fields- comments
- created_time
- dislikes
- duration
- interactions
- interactions_per_1k_fans
- likes
- video_view_time
- video_views
Fields that might be used to filter YouTube profile video:
Field | Allowed values | Description | Advanced filter support |
---|---|---|---|
media_type | video |
Type of Youtube video. | ✅ Supported operators:
|
post_labels | * Pattern: .+ |
Content labels (formally post labels) assigned to the video. | ✅ Supported operators:
|
Response
Name | Description |
---|---|
success | Status of the response. Possible values are true or false. |
data |
object containing the following properties:
|
Example request
POST /3/youtube/profile/videos HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"profiles": ["UCA6AG33Zac0xi6f9VMTxkFQ"],
"date_start": "2018-06-01",
"date_end": "2018-08-31",
"fields": [
"author",
"created_time"
],
"sort": [
{
"field": "created_time",
"order": "desc"
}
],
"limit": 5
}
Example response
{
"success": true,
"data": {
"posts": [
{
"author": {
"id": "UCA6AG33Zac0xi6f9VMTxkFQ",
"name": "Socialbakers",
"url": "https://www.youtube.com/channel/UCA6AG33Zac0xi6f9VMTxkFQ",
},
"created_time": "2019-04-08T14:36:03+00:00"
},
],
}
}
Twitter Tweets
Returns tweets metrics for each requested Twitter profile.
Parameters
Name | Description |
---|---|
profiles |
array , list of profile IDs of the profiles available from the
/3/twitter/profiles endpoint.
|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
Your request is transformed using the time zone assigned to a profile in the Suite settings of your account.
The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct
timezone using the timezone of each individual profile from the /3/twitter/profiles endpoint.
The last day will be also included in the response.
|
fields |
array , the list of fields that will be returned in the response. Available fields are listed in
the table below.
|
limit |
integer , (optional). The number of results per page. The default value is 10 and the maximal value is 100.
|
filter |
(optional), You can filter results by providing the filter parameter with field and value . See
the list of fields allowed for filtering.
|
Parameter for Pagination
after |
string , value of the next property from previous response.
|
Basic Fields
Name | Type | Example | Description |
---|---|---|---|
id |
string
|
|
Twitter tweet id. |
origin |
string
|
|
Source of post. |
post_labels |
array
|
|
Content labels (formally post labels) assigned to the post. |
profile |
object
|
|
Information about the Twitter profile. |
profileId |
string
|
|
The id of the tweet author. |
Fields that might be used to filter Twitter posts:
Field | Allowed values | Description | Advanced filter support |
---|---|---|---|
origin | User-Generated Content Brand's Content |
Source of post. | ✅ Supported operators:
|
post_labels | * Pattern: .+ |
Content labels (formally post labels) assigned to the post. | ✅ Supported operators:
|
Response
Name | Description |
---|---|
success | Status of the response. Possible values are true or false. |
data |
object containing the following properties:
|
Example request
POST /3/twitter/profile/tweets HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"profiles": ["78569316"],
"date_start": "2020-07-20",
"date_end": "2020-07-23",
"fields": ["id"],
"limit": 1
}
Example response
{
"success": true,
"data": {
"posts": [
{
"id": "123"
}
],
"next": "eyJxdWVyeSI6eyJmZWVkVHlwZSI6InVzZXJGZWVkIiwiZmllbGRzIjpbImNyZWF0ZWRUaW1lIiwib3JpZ2luIiwiYXV0aG9ySWQiLCJwcm9maWxlSWQiLCJtb25pdG9yZWRQcm9maWxlSWQiLCJzdG9yYWdlVHlwZSJdLCJmaWx0ZXJzIjpbeyJ0eXBlIjoib3IiLCJmaWx0ZXJzIjpbeyJ0eXBlIjoiYW5kIiwiZmlsdGVycyI6W3sidHlwZSI6ImNyZWF0ZWRUaW1lIiwicmFuZ2UiOnsiZnJvbSI6IjIwMjAtMDctMjBUMDA6MDA6MDBaIiwidG8iOiIyMDIwLTA3LTIzVDIzOjU5OjU5WiJ9fSx7InR5cGUiOiJwcm9maWxlSWQiLCJwcm9maWxlcyI6W3sicHJvZmlsZUlkIjpbIjc4NTY5MzE2Il0sIm5ldHdvcmsiOiJ0d2l0dGVyIn1dfV19XX0seyJ0eXBlIjoibmV0d29yayIsInZhbHVlIjpbImZhY2Vib29rIiwidHdpdHRlciIsInBpbnRlcmVzdCIsImluc3RhZ3JhbSIsInlvdXR1YmUiLCJ2a29udGFrdGUiLCJsaW5rZWRpbiJdfV0sImxpbWl0Ijo1LCJhY2NvdW50SWQiOiIxNzIxOTYiLCJ1c2VySWQiOiJkMTk2MTA4NyIsInRvZ2dsZXMiOlsiQ09NTVVOSVRZX1NFVF9ET05FX0FGVEVSX1JFUExZIiwiQ09OVEVOVF9TRU5USU1FTlQiLCJBTkFMWVRJQ1NfTU9EVUxFIiwiQVVESUVOQ0VTX1RFQVNJTkciLCJQVUJMSVNIX01PRFVMRSIsIlRPS0VOX0ZMT1ciLCJBRFNfQkVOQ0hNQVJLUyIsIkxJTktFRElOX0NPTU1VTklUWSIsIkFVVE9NQVRFRF9TRU5USU1FTlRfQUNDRVBURUQiLCJBVVRPTUFURURfU0VOVElNRU5UIiwiQURfQUNDT1VOVFNfUk9MRVNfUEVSTUlTU0lPTlMiLCJBUFBST1ZBTF9GTE9XIiwiQVVUT0xBQkVMSU5HIiwiREFTSEJPQVJEX09NTklfV0lER0VUUyIsIkZJTEVTVEFDS19GVUxMIiwiSU5TVEFHUkFNX0FEU19QVUJfQ09NIiwiSU5TVEFHUkFNX1ZJREVPX1BVQkxJU0hJTkciLCJMSU5LRURJTl9QVUJMSVNISU5HIiwiTU9CSUxFX0NPTU1VTklUWV9NT0RVTEUiLCJDT05URU5UX0hVQl9NT0RVTEUiLCJSVUxFX0JBU0VEX0xBQkVMSU5HIiwiQ09OVEVOVF9IVUJfQ09MTEVDVElPTlMiLCJQQUlEX01PRFVMRSIsIlBVQkxJU0hFUl9FWFRFUk5BTCIsIlRXX0lOU0lHSFRTIiwiQ09NTVVOSVRZX01PRFVMRSIsIkFEU19CRU5DSE1BUktTX0ZVTExfQUNDRVNTIiwiQkVOQ0hNQVJLU19NVUxUSUNPTVBBUkUiLCJDQU1QQUlHTl9WSUVXIiwiQ09OVEVOVF9TRUFSQ0hfUFJPIiwiREFTSEJPQVJEX01PRFVMRSIsIkdPT0dMRV9BTkFMWVRJQ1MiLCJMSVNURU5JTkciLCJMSVZFX1ZJREVPX01FVFJJQ1MiLCJQQUlEX1BPU1RfREVURUNUSU9OIiwiUEFJRF9QT1NUX0RFVEVDVElPTl9JRyIsIlBPU1RfQk9PU1RJTkciLCJQUklNRVRJTUUiLCJWSURFT19CRU5DSE1BUktTX0ZVTExfQUNDRVNTIiwiQlVTSU5FU1NfVE9HR0xFX1BVQkxJU0hFUl9JR19VU0VSU19UQUdHSU5HIiwiSU5GTFVFTkNFUlNfTU9EVUxFIiwiUEVSTUlTU0lPTlNfQllfU0VDVElPTlMiLCJCVVNJTkVTU19UT0dHTEVfU1RPUklFU19TQ0hFRFVMSU5HIiwiQlVTSU5FU1NfVE9HR0xFX0FTVFVURV9JTlRFR1JBVElPTiIsIkJVU0lORVNTX1RPR0dMRV9MSU5LRURJTl9UQVJHRVRJTkciLCJCVVNJTkVTU19UT0dHTEVfUFVCTElTSEVSX0lHX0xPQ0FUSU9OX1RBR0dJTkciLCJDT05URU5UX1BSRURJQ1RJT04iLCJDT05URU5UX1BSRURJQ1RJT05fSUciLCJQVUJMSVNIRVJfRkJfU0NIRURVTElORyIsIkJVU0lORVNTX1RPR0dMRV9JR19PUkdBTklDX1BBSURfUkVNT1ZBTF9JTlRFUklNIiwiQlVTSU5FU1NfVE9HR0xFX0lHX09SR0FOSUNfUEFJRF9SRU1PVkFMX0ZJTkFMIiwiQkVUQV9NT0JJTEVfQ09NTVVOSVRZX01PRFVMRSIsIkFVRElFTkNFU19NT0RVTEUiLCJCVVNJTkVTU19UT0dHTEVfQ09NTVVOSVRZX1JFUE9SVElORyIsIlNVSVRFX0FEUyIsIkJVU0lORVNTX1RPR0dMRV9QQUlEX1NUT1JFRF9EQVRBIiwiQlVTSU5FU1NfVE9HR0xFX1BSSU9SSVRZX1NDT1JFIiwiSU5GTFVFTkNFUlNfRlVMTF9BQ0NFU1MiXSwicHJvZmlsZXMiOlt7InByb2ZpbGVJZCI6WyI3ODU2OTMxNiJdLCJuZXR3b3JrIjoidHdpdHRlciIsInRpbWV6b25lIjoiVVRDIiwiaW5zaWdodHMiOnRydWUsIm1hbmFnZWQiOmZhbHNlLCJpbnN0YWdyYW1Ub2tlbiI6ZmFsc2UsImlzQXV0b1NlbnRpbWVudEVuYWJsZWQiOnRydWUsImluZmx1ZW5jZXJJbnNpZ2h0cyI6ZmFsc2V9XSwiY3JlYXRlZFRpbWUiOnsiZnJvbSI6IjIwMjAtMDctMjBUMDA6MDA6MDBaIiwidG8iOiIyMDIwLTA3LTIzVDIzOjU5OjU5WiJ9LCJzb3J0IjpbeyJ0eXBlIjoiY3JlYXRlZFRpbWUiLCJvcmRlciI6ImRlc2MifV19LCJjdXJzb3IiOnsic29ydCI6W3sidHlwZSI6ImNyZWF0ZWRUaW1lIiwidmFsdWUiOjE1OTU1MzA5MDMwMDAsIm9yZGVyIjoiZGVzYyJ9XSwibGFzdFNvcnRIYXNoIjoiKzkwMDU2MDM3MjM4Mzc5OTIiLCJpZHMiOlsiMTI4NjM3NTk2MDY4Njg3NDYzMCJdfSwidG90YWwiOjE2MCwic2Nyb2xsQ291bnQiOjEsInNjcm9sbGVkQ291bnQiOjV9",
"remaining": 155
}
}
Linkedin Posts
Returns a set of posts created during the specified date range for each requested Linkedin profile. Linkedin posts endpoint returns lifetime values of the metrics.
Parameters
Name | Description |
---|---|
profiles |
array , list of profile IDs of the profiles available from the /3/linkedin/profiles endpoint.
|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
Your request is transformed using the time zone assigned to a profile in the Suite settings of your account.
The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct
timezone using the timezone of each individual profile from the /3/linkedin/profiles endpoint.
The last day will be also included in the response.
|
fields |
array , the list of fields that will be returned in the response. Available fields are listed in
the table below.
|
limit |
integer , (optional). The number of results per page. The default value is 10 and the maximal value is 100.
|
sort |
(optional), You can sort the results by specifying a field and sorting order in the sort object: "field": "created_time"
and "order": "desc" . See the list of fields allowed
for sorting.
|
filter |
You can filter results by providing the filter parameter with field and value . See
the list of fields allowed for filtering.
|
Parameter for Pagination
after |
string , value of the next property from previous response.
|
Basic Fields
Name | Type | Example | Description |
---|---|---|---|
attachments |
array
|
|
Details about post attachments. |
author |
object
|
|
Author details of the post. |
authorId |
string
|
|
The id of the post author. |
comments |
integer
|
|
Total number of comments. |
content |
string
|
|
Content of the LinkedIn post. |
content_type |
string
|
|
Content type of the LinkedIn post. |
created_time |
datetime
|
|
Date and time the post was created in LinkedIn. |
id |
string
|
|
LinkedIn post id. |
interactions |
integer
|
|
Sum of reactions, comments and shares. |
interactions_per_1k_fans |
float
|
|
Interaction count for every 1000 fans. |
media_type |
string
|
|
Type of LinkedIn post. |
page |
object
|
|
Information about the LinkedIn page. |
post_labels |
array
|
|
Content labels (formally post labels) assigned to the post. |
profileId |
string
|
|
The id of the LinkedIn page. |
reactions |
integer
|
|
Total number of reactions. |
url |
string
|
|
Link to the LinkedIn post. |
Insights Fields
Metrics prefixed with insights_
can only be used for profiles that have insights_enabled
property set to true
in the response of the /3/linkedin/profiles
endpoint.
Name | Type | Example | Description |
---|---|---|---|
insights_clicks |
integer
|
|
Number of clicks received by a post during its lifetime. |
insights_comments |
integer
|
|
Sum of comments received by a post during its lifetime. This is an Insights type of metric. Learn More. |
insights_content_impressions |
integer
|
|
Sum of impressions received by a post during its lifetime. |
insights_engagements |
integer
|
|
Engagements refers to how many times users engaged with a post during its lifetime. Learn More. |
insights_impressions_engagement_rate |
float
|
|
Impressions engagement rate refers to the percentage of users who engaged with a post during its lifetime, given its impressions. Learn More. |
insights_reactions |
integer
|
|
Sum of reactions received by a post during its lifetime. This is an Insights type of metric. Learn More. |
insights_video_views |
integer
|
|
Number of times a LinkedIn video was viewed for at least 3 seconds. Learn More. |
insights_video_views_unique |
integer
|
|
Number of unique people who watched this video for at least 3 seconds during its lifetime. Learn More. |
insights_view_time |
integer
|
|
The total amount of time that users watched a LinkedIn video during its lifetime. Learn More. |
Fields that might be used to sort Linkedin posts:
Basic Fields- comments
- created_time
- interactions
- interactions_per_1k_fans
- reactions
- insights_clicks
- insights_comments
- insights_content_impressions
- insights_engagements
- insights_impressions_engagement_rate
- insights_video_views
- insights_video_views_unique
- insights_view_time
Fields that might be used to filter Linkedin posts:
Field | Allowed values | Description | Advanced filter support |
---|---|---|---|
media_type | status link video photo album carousel |
Type of LinkedIn post. | ✅ Supported operators:
|
post_labels | * Pattern: .+ |
Content labels (formally post labels) assigned to the post. | ✅ Supported operators:
|
Example request
POST /3/linkedin/profile/posts HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"profiles": ["urn:li:organization:2056516"],
"date_start": "2020-01-15",
"date_end": "2020-01-17",
"fields": ["content", "created_time"],
"sort": [
{
"field": "created_time",
"order": "asc"
}
],
"limit": 5
}
Example response
{
"success": true,
"data": {
"posts": [
{
"content": "Today in our 🍕 lunch and learn 🧠session Mathias Durand gave our #Emplifi team some tips on how they can strengthen their habits and willpower to accomplish their 2020 goals 🙌. \n\nThe secret? Creating small milestones and increasing the desired goal over time little by little 😉. #InsideEmplifi",
"created_time": "2020-01-15T15:04:55+00:00"
},
{
"content": "Get everything you need to start the New Year of with a BANG 💥. ",
"created_time": "2020-01-15T18:00:01+00:00"
},
{
"content": "#SocialMedia 💻 and link building are often looked at separately from a business perspective. But the reality is, they actually go hand ✋ in hand ✋.\n\n📲 Learn how to refine your backlink strategy here: http://bit.ly/3a64VZy",
"created_time": "2020-01-16T13:00:09+00:00"
},
{
"content": "We had the pleasure of speaking with remarkable digital #marketers 💻 and CMOs about their ambitions 💪 for 2020. \n\n⬇️ Here's what they had to say... ",
"created_time": "2020-01-16T17:00:01+00:00"
},
{
"content": "Discover how Bath & Body Works 🛁experienced a massive increase in #socialmedia engagement and skyrocketed 🚀their sales revenue for two major annual campaigns!\n\n➡️Unlock the full study here: http://bit.ly/370f1t6 \n\n#socialbakers #socialmediaengagement #marketing ",
"created_time": "2020-01-17T09:37:58+00:00"
}
],
"next": "eyJxdWVyeSI6eyJmZWVkVHlwZSI6InVzZXJGZWVkIiwiZmllbGRzIjpbIm1lc3NhZ2UiLCJjcmVhdGVkVGltZSIsIm9yaWdpbiIsImF1dGhvcklkIiwicHJvZmlsZUlkIiwibW9uaXRvcmVkUHJvZmlsZUlkIiwic3RvcmFnZVR5cGUiXSwiZmlsdGVycyI6W3sidHlwZSI6Im9yIiwiZmlsdGVycyI6W3sidHlwZSI6ImFuZCIsImZpbHRlcnMiOlt7InR5cGUiOiJjcmVhdGVkVGltZSIsInJhbmdlIjp7ImZyb20iOiIyMDIwLTAxLTE1VDAwOjAwOjAwWiIsInRvIjoiMjAyMC0wMS0xN1QyMzo1OTo1OVoifX0seyJ0eXBlIjoicHJvZmlsZUlkIiwicHJvZmlsZXMiOlt7InByb2ZpbGVJZCI6WyJ1cm46bGk6b3JnYW5pemF0aW9uOjIwNTY1MTYiXSwibmV0d29yayI6ImxpbmtlZGluIn1dfV19XX0seyJ0eXBlIjoibmV0d29yayIsInZhbHVlIjpbImZhY2Vib29rIiwidHdpdHRlciIsInBpbnRlcmVzdCIsImluc3RhZ3JhbSIsInlvdXR1YmUiLCJ2a29udGFrdGUiLCJsaW5rZWRpbiJdfV0sInNvcnQiOlt7InR5cGUiOiJjcmVhdGVkVGltZSIsIm9yZGVyIjoiYXNjIn1dLCJsaW1pdCI6NSwiYWNjb3VudElkIjoiMTcyMTk2IiwidXNlcklkIjoiZDE5NjEwODciLCJ0b2dnbGVzIjpbIkNPTU1VTklUWV9TRVRfRE9ORV9BRlRFUl9SRVBMWSIsIkFOQUxZVElDU19NT0RVTEUiLCJBVURJRU5DRVNfVEVBU0lORyIsIlBVQkxJU0hfTU9EVUxFIiwiVE9LRU5fRkxPVyIsIkFEU19CRU5DSE1BUktTIiwiTElOS0VESU5fQ09NTVVOSVRZIiwiQVVUT01BVEVEX1NFTlRJTUVOVF9BQ0NFUFRFRCIsIkFEX0FDQ09VTlRTX1JPTEVTX1BFUk1JU1NJT05TIiwiQVBQUk9WQUxfRkxPVyIsIkFVVE9MQUJFTElORyIsIkRBU0hCT0FSRF9PTU5JX1dJREdFVFMiLCJGSUxFU1RBQ0tfRlVMTCIsIklOU1RBR1JBTV9BRFNfUFVCX0NPTSIsIklOU1RBR1JBTV9WSURFT19QVUJMSVNISU5HIiwiTElOS0VESU5fUFVCTElTSElORyIsIk1PQklMRV9DT01NVU5JVFlfTU9EVUxFIiwiQ09OVEVOVF9IVUJfTU9EVUxFIiwiUlVMRV9CQVNFRF9MQUJFTElORyIsIkNPTlRFTlRfSFVCX0NPTExFQ1RJT05TIiwiUEFJRF9NT0RVTEUiLCJQVUJMSVNIRVJfRVhURVJOQUwiLCJUV19JTlNJR0hUUyIsIkNPTU1VTklUWV9NT0RVTEUiLCJBRFNfQkVOQ0hNQVJLU19GVUxMX0FDQ0VTUyIsIkJFTkNITUFSS1NfTVVMVElDT01QQVJFIiwiQ0FNUEFJR05fVklFVyIsIkNPTlRFTlRfU0VBUkNIX1BSTyIsIkRBU0hCT0FSRF9NT0RVTEUiLCJHT09HTEVfQU5BTFlUSUNTIiwiTElTVEVOSU5HIiwiTElWRV9WSURFT19NRVRSSUNTIiwiUEFJRF9QT1NUX0RFVEVDVElPTiIsIlBBSURfUE9TVF9ERVRFQ1RJT05fSUciLCJQT1NUX0JPT1NUSU5HIiwiUFJJTUVUSU1FIiwiVklERU9fQkVOQ0hNQVJLU19GVUxMX0FDQ0VTUyIsIkJVU0lORVNTX1RPR0dMRV9QVUJMSVNIRVJfSUdfVVNFUlNfVEFHR0lORyIsIklORkxVRU5DRVJTX01PRFVMRSIsIlBFUk1JU1NJT05TX0JZX1NFQ1RJT05TIiwiQlVTSU5FU1NfVE9HR0xFX1NUT1JJRVNfU0NIRURVTElORyIsIkJVU0lORVNTX1RPR0dMRV9BU1RVVEVfSU5URUdSQVRJT04iLCJCVVNJTkVTU19UT0dHTEVfTElOS0VESU5fVEFSR0VUSU5HIiwiQlVTSU5FU1NfVE9HR0xFX1BVQkxJU0hFUl9JR19MT0NBVElPTl9UQUdHSU5HIiwiQ09OVEVOVF9QUkVESUNUSU9OIiwiQ09OVEVOVF9QUkVESUNUSU9OX0lHIiwiUFVCTElTSEVSX0ZCX1NDSEVEVUxJTkciLCJCVVNJTkVTU19UT0dHTEVfUFVCTElDX0RBU0hCT0FSRCIsIkNPTlRFTlRfU0VOVElNRU5UIiwiQVVUT01BVEVEX1NFTlRJTUVOVCIsIkJVU0lORVNTX1RPR0dMRV9PUkdBTklDX0FOQUxZVElDUyIsIkJVU0lORVNTX1RPR0dMRV9MSVNURU5JTkdfTU9EVUxFIiwiQlVTSU5FU1NfVE9HR0xFX0lHX09SR0FOSUNfUEFJRF9SRU1PVkFMX0lOVEVSSU0iLCJCVVNJTkVTU19UT0dHTEVfSUdfT1JHQU5JQ19QQUlEX1JFTU9WQUxfRklOQUwiLCJCRVRBX01PQklMRV9DT01NVU5JVFlfTU9EVUxFIiwiQVVESUVOQ0VTX01PRFVMRSIsIkJVU0lORVNTX1RPR0dMRV9DT01NVU5JVFlfUkVQT1JUSU5HIiwiU1VJVEVfQURTIiwiQlVTSU5FU1NfVE9HR0xFX1BBSURfU1RPUkVEX0RBVEEiLCJCVVNJTkVTU19UT0dHTEVfUFJJT1JJVFlfU0NPUkUiLCJJTkZMVUVOQ0VSU19GVUxMX0FDQ0VTUyJdLCJwcm9maWxlcyI6W3sicHJvZmlsZUlkIjpbInVybjpsaTpvcmdhbml6YXRpb246MjA1NjUxNiJdLCJuZXR3b3JrIjoibGlua2VkaW4iLCJ0aW1lem9uZSI6IlVUQyIsImluc2lnaHRzIjpmYWxzZSwibWFuYWdlZCI6ZmFsc2UsImluc3RhZ3JhbVRva2VuIjpmYWxzZSwiaXNBdXRvU2VudGltZW50RW5hYmxlZCI6dHJ1ZSwiaW5mbHVlbmNlckluc2lnaHRzIjpmYWxzZX1dLCJjcmVhdGVkVGltZSI6eyJmcm9tIjoiMjAyMC0wMS0xNVQwMDowMDowMFoiLCJ0byI6IjIwMjAtMDEtMTdUMjM6NTk6NTlaIn19LCJjdXJzb3IiOnsic29ydCI6W3sidHlwZSI6ImNyZWF0ZWRUaW1lIiwidmFsdWUiOjE1NzkyNTM4NzgwMDAsIm9yZGVyIjoiYXNjIn1dLCJsYXN0U29ydEhhc2giOiItMDAwMTU3OTI1Mzg3ODAwMCIsImlkcyI6WyJ1cm46bGk6dWdjUG9zdDo2NjIzODcwODYwMjQ5ODMzNDcyIl19LCJ0b3RhbCI6OCwic2Nyb2xsQ291bnQiOjEsInNjcm9sbGVkQ291bnQiOjV9",
"remaining": 3
}
}
Pinterest Posts
Returns a set of posts created during the specified date range for each requested Pinterest profile. Pinterest posts endpoint returns lifetime values of the metrics.
Parameters
Name | Description |
---|---|
profiles |
array , list of profile IDs of the profiles available from the
/3/pinterest/profiles endpoint.
|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
Your request is transformed using the time zone assigned to a profile in the Suite settings of your account.
The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct
timezone using the timezone of each individual profile from the /3/pinterest/profiles endpoint.
The last day will be also included in the response.
|
fields |
array , the list of fields that will be returned in the response. Available fields are listed in
the table below.
|
limit |
integer , (optional). The number of results per page. The default value is 10 and the maximal value is 100.
|
sort |
(optional), You can sort the results by specifying a field and sorting order in the sort object:
"field": "created_time"
and "order": "desc" . See the list of fields allowed
for sorting.
|
filter |
You can filter results by providing the filter parameter with field and value . See
the list of fields allowed for filtering.
|
Parameter for Pagination
after |
string , value of the next property from previous response.
|
Basic Fields
Name | Type | Example | Description |
---|---|---|---|
attachments |
array
|
|
Details about post attachments. |
author |
object
|
|
Author details of the post. |
authorId |
string
|
|
The id of the post author. |
content |
string
|
|
Content of the Pinterest post. |
content_type |
string
|
|
Content type of the Pinterest post. |
created_time |
datetime
|
|
Date and time the post was created in Pinterest. |
id |
string
|
|
Pinterest post id. |
media_type |
string
|
|
Type of Pinterest post. |
post_labels |
array
|
|
Content labels (formally post labels) assigned to the post. |
profile |
object
|
|
Information about the Pinterest profile. |
profileId |
string
|
|
The id of the Pinterest profile. |
url |
string
|
|
Link to the Pinterest post. |
Insights Fields
All metrics can only be used for profiles that have insights_enabled
property set to true
in the response of the /3/pinterest/profiles
endpoint.
Name | Type | Example | Description |
---|---|---|---|
comments |
integer
|
|
Total number of comments. |
insights_avg_time_watched |
float
|
|
The average time in seconds someone spent playing the video and static image cards included in your Pin. |
insights_engagements |
integer
|
|
Engagements inform about how many times users engaged with a pin during its lifetime. Learn More. |
insights_impressions |
integer
|
|
The number of times your Pin was on screen. |
insights_impressions_engagement_rate |
float
|
|
Impressions Engagement Rate informs about the percentage of users who engaged with a pin during its lifetime given its impressions. Learn More. |
insights_link_clicks |
integer
|
|
The number of times users clicked on links that redirected them away from Pinterest. |
insights_post_clicks |
integer
|
|
The total number of clicks on your Pin so it opens in closeup. |
insights_post_saves |
integer
|
|
The number of times people saved your Pin to a board. |
insights_reactions |
integer
|
|
Total reactions. |
insights_save_rate |
float
|
|
The total saves of your Pins divided by the total number of times your Pins were on screen. |
insights_video_completed_views |
integer
|
|
The number of times your video was viewed to 95% of its length. |
insights_video_starts |
integer
|
|
Total number of video starts. |
insights_video_views |
integer
|
|
The amount of views for at least 2 seconds with 50% of video in view. |
insights_video_views_10s |
integer
|
|
The number of times your video was viewed for at least 10 seconds. |
insights_view_time |
integer
|
|
The total play time for your video in seconds. |
interactions |
integer
|
|
Sum of reactions and comments. |
interactions_per_1k_fans |
float
|
|
Interaction count for every 1000 fans. |
Fields that might be used to sort Pinterest posts:
Basic Fields- created_time
- comments
- insights_avg_time_watched
- insights_engagements
- insights_impressions
- insights_impressions_engagement_rate
- insights_link_clicks
- insights_post_clicks
- insights_post_saves
- insights_save_rate
- insights_video_completed_views
- insights_video_starts
- insights_video_views
- insights_video_views_10s
- insights_view_time
- interactions
- interactions_per_1k_fans
Fields that might be used to filter Pinterest posts:
Field | Allowed values | Description | Advanced filter support |
---|---|---|---|
content_type | post shared |
Content type of the Pinterest post. | ✅ Supported operators:
|
post_labels | * Pattern: .+ |
Content labels (formally post labels) assigned to the post. | ✅ Supported operators:
|
Example request
POST /3/pinterest/profile/posts HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"profiles": ["376684093741466051"],
"date_start": "2020-06-10",
"date_end": "2020-07-18",
"fields": ["attachments"],
"sort": [
{
"field": "created_time",
"order": "desc"
}
],
"limit": 5
}
Example response
{
"success": true,
"data": {
"posts": [
{
"attachments": [
{
"image_url": "https://i.pinimg.com/600x/ec/fc/14/ecfc14c0e0457290a52fbfe2b7260abd.jpg",
"type": "photo"
}
]
},
{
"attachments": [
{
"image_url": "https://i.pinimg.com/600x/f9/22/92/f92292a71c310e234367f561ce177284.jpg",
"type": "photo"
}
]
},
{
"attachments": [
{
"image_url": "https://i.pinimg.com/600x/96/90/d8/9690d8a4a5495181870ce7fc58d9508e.jpg",
"type": "photo"
}
]
},
{
"attachments": [
{
"image_url": "https://i.pinimg.com/600x/85/18/a1/8518a1670f67c82d87f65ae58a45c1b1.jpg",
"type": "photo"
}
]
},
{
"attachments": [
{
"image_url": "https://i.pinimg.com/600x/43/16/cb/4316cba530e935255d99f41247c1c7b9.jpg",
"type": "photo"
}
]
}
],
"next": "eyJxdWVyeSI6eyJmZWVkVHlwZSI6InVzZXJGZWVkIiwiZmllbGRzIjpbImF0dGFjaG1lbnRzIiwib3JpZ2luIiwiYXV0aG9ySWQiLCJwcm9maWxlSWQiLCJtb25pdG9yZWRQcm9maWxlSWQiLCJzdG9yYWdlVHlwZSJdLCJmaWx0ZXJzIjpbeyJ0eXBlIjoib3IiLCJmaWx0ZXJzIjpbeyJ0eXBlIjoiYW5kIiwiZmlsdGVycyI6W3sidHlwZSI6ImNyZWF0ZWRUaW1lIiwicmFuZ2UiOnsiZnJvbSI6IjIwMjAtMDYtMTBUMDA6MDA6MDBaIiwidG8iOiIyMDIwLTA3LTE4VDIzOjU5OjU5WiJ9fSx7InR5cGUiOiJwcm9maWxlSWQiLCJwcm9maWxlcyI6W3sicHJvZmlsZUlkIjpbIjM3NjY4NDA5Mzc0MTQ2NjA1MSJdLCJuZXR3b3JrIjoicGludGVyZXN0In1dfV19XX0seyJ0eXBlIjoibmV0d29yayIsInZhbHVlIjpbImZhY2Vib29rIiwidHdpdHRlciIsInBpbnRlcmVzdCIsImluc3RhZ3JhbSIsInlvdXR1YmUiLCJ2a29udGFrdGUiLCJsaW5rZWRpbiJdfV0sImxpbWl0Ijo1LCJhY2NvdW50SWQiOiIxNzIxOTYiLCJ1c2VySWQiOiJkMTk2MTA4NyIsInRvZ2dsZXMiOlsiQ09NTVVOSVRZX1NFVF9ET05FX0FGVEVSX1JFUExZIiwiQ09OVEVOVF9TRU5USU1FTlQiLCJBTkFMWVRJQ1NfTU9EVUxFIiwiQVVESUVOQ0VTX1RFQVNJTkciLCJQVUJMSVNIX01PRFVMRSIsIlRPS0VOX0ZMT1ciLCJBRFNfQkVOQ0hNQVJLUyIsIkxJTktFRElOX0NPTU1VTklUWSIsIkFVVE9NQVRFRF9TRU5USU1FTlRfQUNDRVBURUQiLCJBVVRPTUFURURfU0VOVElNRU5UIiwiQURfQUNDT1VOVFNfUk9MRVNfUEVSTUlTU0lPTlMiLCJBUFBST1ZBTF9GTE9XIiwiQVVUT0xBQkVMSU5HIiwiREFTSEJPQVJEX09NTklfV0lER0VUUyIsIkZJTEVTVEFDS19GVUxMIiwiSU5TVEFHUkFNX0FEU19QVUJfQ09NIiwiSU5TVEFHUkFNX1ZJREVPX1BVQkxJU0hJTkciLCJMSU5LRURJTl9QVUJMSVNISU5HIiwiTU9CSUxFX0NPTU1VTklUWV9NT0RVTEUiLCJDT05URU5UX0hVQl9NT0RVTEUiLCJSVUxFX0JBU0VEX0xBQkVMSU5HIiwiQ09OVEVOVF9IVUJfQ09MTEVDVElPTlMiLCJQQUlEX01PRFVMRSIsIlBVQkxJU0hFUl9FWFRFUk5BTCIsIlRXX0lOU0lHSFRTIiwiQ09NTVVOSVRZX01PRFVMRSIsIkFEU19CRU5DSE1BUktTX0ZVTExfQUNDRVNTIiwiQkVOQ0hNQVJLU19NVUxUSUNPTVBBUkUiLCJDQU1QQUlHTl9WSUVXIiwiQ09OVEVOVF9TRUFSQ0hfUFJPIiwiREFTSEJPQVJEX01PRFVMRSIsIkdPT0dMRV9BTkFMWVRJQ1MiLCJMSVNURU5JTkciLCJMSVZFX1ZJREVPX01FVFJJQ1MiLCJQQUlEX1BPU1RfREVURUNUSU9OIiwiUEFJRF9QT1NUX0RFVEVDVElPTl9JRyIsIlBPU1RfQk9PU1RJTkciLCJQUklNRVRJTUUiLCJWSURFT19CRU5DSE1BUktTX0ZVTExfQUNDRVNTIiwiQlVTSU5FU1NfVE9HR0xFX1BVQkxJU0hFUl9JR19VU0VSU19UQUdHSU5HIiwiSU5GTFVFTkNFUlNfTU9EVUxFIiwiUEVSTUlTU0lPTlNfQllfU0VDVElPTlMiLCJCVVNJTkVTU19UT0dHTEVfU1RPUklFU19TQ0hFRFVMSU5HIiwiQlVTSU5FU1NfVE9HR0xFX0FTVFVURV9JTlRFR1JBVElPTiIsIkJVU0lORVNTX1RPR0dMRV9MSU5LRURJTl9UQVJHRVRJTkciLCJCVVNJTkVTU19UT0dHTEVfUFVCTElTSEVSX0lHX0xPQ0FUSU9OX1RBR0dJTkciLCJDT05URU5UX1BSRURJQ1RJT04iLCJDT05URU5UX1BSRURJQ1RJT05fSUciLCJQVUJMSVNIRVJfRkJfU0NIRURVTElORyIsIkJVU0lORVNTX1RPR0dMRV9JR19PUkdBTklDX1BBSURfUkVNT1ZBTF9JTlRFUklNIiwiQlVTSU5FU1NfVE9HR0xFX0lHX09SR0FOSUNfUEFJRF9SRU1PVkFMX0ZJTkFMIiwiQkVUQV9NT0JJTEVfQ09NTVVOSVRZX01PRFVMRSIsIkFVRElFTkNFU19NT0RVTEUiLCJCVVNJTkVTU19UT0dHTEVfQ09NTVVOSVRZX1JFUE9SVElORyIsIlNVSVRFX0FEUyIsIkJVU0lORVNTX1RPR0dMRV9QQUlEX1NUT1JFRF9EQVRBIiwiQlVTSU5FU1NfVE9HR0xFX1BSSU9SSVRZX1NDT1JFIiwiSU5GTFVFTkNFUlNfRlVMTF9BQ0NFU1MiXSwicHJvZmlsZXMiOlt7InByb2ZpbGVJZCI6WyIzNzY2ODQwOTM3NDE0NjYwNTEiXSwibmV0d29yayI6InBpbnRlcmVzdCIsInRpbWV6b25lIjoiVVRDIiwiaW5zaWdodHMiOmZhbHNlLCJtYW5hZ2VkIjpmYWxzZSwiaW5zdGFncmFtVG9rZW4iOmZhbHNlLCJpc0F1dG9TZW50aW1lbnRFbmFibGVkIjp0cnVlLCJpbmZsdWVuY2VySW5zaWdodHMiOmZhbHNlfV0sImNyZWF0ZWRUaW1lIjp7ImZyb20iOiIyMDIwLTA2LTEwVDAwOjAwOjAwWiIsInRvIjoiMjAyMC0wNy0xOFQyMzo1OTo1OVoifSwic29ydCI6W3sidHlwZSI6ImNyZWF0ZWRUaW1lIiwib3JkZXIiOiJkZXNjIn1dfSwiY3Vyc29yIjp7InNvcnQiOlt7InR5cGUiOiJjcmVhdGVkVGltZSIsInZhbHVlIjoxNTkyMTI5NDc3MDAwLCJvcmRlciI6ImRlc2MifV0sImxhc3RTb3J0SGFzaCI6Iis5MDA1NjA3MTI1MjYzOTkyIiwiaWRzIjpbIjM3NjY4NDA5Mzc0MTQ2NjA1MV8zNzY2ODM5NTYzMzg4MTM5MzUiXX0sInRvdGFsIjo4LCJzY3JvbGxDb3VudCI6MSwic2Nyb2xsZWRDb3VudCI6NX0=",
"remaining": 3
}
}
TikTok Posts
Returns a set of posts created during the specified date range for each requested TikTok profile. TikTok posts endpoint returns lifetime values of the metrics.
Parameters
Name | Description |
---|---|
profiles |
array , list of profile IDs of the profiles available from the
/3/tiktok/profiles endpoint.
|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
Your request is transformed using the time zone assigned to a profile in the Suite settings of your account.
The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct
timezone using the timezone of each individual profile from the /3/tiktok/profiles endpoint.
The last day will be also included in the response.
|
fields |
array , the list of fields that will be returned in the response. Available fields are listed in
the table below.
|
limit |
integer , (optional). The number of results per page. The default value is 10 and the maximal value is 100.
|
sort |
(optional), You can sort the results by specifying a field and sorting order in the sort object:
"field": "created_time"
and "order": "desc" . See the list of fields allowed
for sorting.
|
filter |
(optional), You can filter results by providing the filter parameter with field and value . See
the list of fields allowed for filtering.
|
Parameter for Pagination
after |
string , value of the next property from previous response.
|
Basic Fields
Name | Type | Example | Description |
---|---|---|---|
attachments |
array
|
|
Details about post attachments. |
author |
object
|
|
Author details of the post. |
authorId |
string
|
|
The id of the post author. |
content_type |
string
|
|
Content type of the TikTok post. |
created_time |
datetime
|
|
Date and time the post was created in TikTok. |
duration |
integer
|
|
Length of the video in seconds. |
id |
string
|
|
TikTok post id. |
link |
string
|
|
Link to the post in TikTok. |
media |
string
|
|
Media type of TikTok post. |
message |
string
|
|
TikTok post content. |
post_labels |
array
|
|
Content labels (formally post labels) assigned to the post. |
Insights Fields
Metrics prefixed with insights_
can only be used for profiles that have insights_enabled
property set to true
in the response of the /3/tiktok/profiles
endpoint.
Name | Type | Example | Description |
---|---|---|---|
insights_avg_time_watched |
integer
|
|
The average time that users spent watching the video during its lifetime. Note: There can be up to 24h delay in availability for this metric from the TikTok Organic API. |
insights_comments |
integer
|
|
Total number of comments for a TikTok video during its lifetime. |
insights_completion_rate |
float
|
|
The percentage of times a video was watched in full during its lifetime. Note: There can be up to 24h delay in availability for this metric from the TikTok Organic API. |
insights_engagements |
integer
|
|
Total number of times users engaged with a video during its lifetime. TikTok Engagements is calculated from the sum of likes, comments and shares. |
insights_impressions |
integer
|
|
The number of impressions for your post. |
insights_impressions_by_traffic_source |
array
|
|
List of traffic sources from which a TikTok video has received its impressions. Note: There can be up to 24h delay in availability for this metric from the TikTok Organic API. |
insights_likes |
integer
|
|
Total number of likes for a TikTok video during its lifetime. |
insights_reach |
integer
|
|
Total number of unique users who viewed a TikTok video during its lifetime. Note: There can be up to 24h delay in availability for this metric from the TikTok Organic API. |
insights_reach_engagement_rate |
float
|
|
Reach engagement rate informs about the percentage of users who engaged with a video during its lifetime given its reach. TikTok Engagements is calculated from the sum of likes, comments and shares. |
insights_shares |
integer
|
|
Total number of shares for a TikTok video during its lifetime. |
insights_video_views |
integer
|
|
Total number of video views for a TikTok video during its lifetime. |
insights_view_time |
integer
|
|
The total amount of time that users watched the video during its lifetime. Note: There can be up to 24h delay in availability for this metric from the TikTok Organic API. |
insights_viewers_by_country |
array
|
|
Country breakdown of the viewers of a TikTok video. Note: There can be up to 24h delay in availability for this metric from the TikTok Organic API. |
Fields that might be used to sort TikTok posts:
Basic Fields- created_time
- duration
- insights_avg_time_watched
- insights_comments
- insights_completion_rate
- insights_engagements
- insights_impressions
- insights_likes
- insights_reach_engagement_rate
- insights_shares
- insights_video_views
- insights_view_time
Fields that might be used to filter TikTok posts:
Field | Allowed values | Description | Advanced filter support |
---|---|---|---|
post_labels | * Pattern: .+ |
Content labels (formally post labels) assigned to the post. | ✅ Supported operators:
|
Response
Name | Description |
---|---|
success | Status of the response. Possible values are true or false. |
data |
object containing the following properties:
|
Example request
POST /3/tiktok/profile/posts HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"profiles": ["c3694e88-379a-4f3d-9942-acc7203f72e3"],
"date_start": "2022-05-01",
"date_end": "2022-05-20",
"fields": [
"id",
"created_time",
"attachments",
"insights_reach"
],
"sort": [
{
"field": "created_time",
"order": "desc"
}
],
"limit": 1
}
Example response
{
"success": true,
"data": {
"posts": [
{
"id": "7099511034708315434",
"created_time": "2022-05-19T18:08:45+00:00",
"attachments": [
{
"image_url": "https://p16-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/eeb89870920743bbbcf0fecbaf18da8a_1652983726~tplv-noop.image?x-expires=1654798315&x-signature=CGac9MWE1J3XxgUE6N2TEm4pE4s%3D",
"type": "video"
}
],
"insights_reach": 1228407
}
],
"next": "eyJjdXJzb3IiOlt7ImZpZWxkIjoiY3JlYXRlZF90aW1lIiwidmFsdWUiOiIyMDE4LTA2LTI4VDEyOjM4OjM0KzAwOjAwIiwib3JkZXIiOiJkZXNjIn1dLCJpZHMiOlsiMTc4OTM5NTExNjIyMTY0NjRfNDkwNDAyMjIwIl19=",
"remaining": 28
}
}
Snapchat Posts
Returns a set of posts created during the specified date range for each requested Snapchat profile. Snapchat posts endpoint returns lifetime values of the metrics.
Parameters
Name | Description |
---|---|
profiles |
array , list of profile IDs of the profiles available from the
/3/snapchat/profiles endpoint.
|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
Your request is transformed using the time zone assigned to a profile in the Suite settings of your account.
The response of the endpoint displays the date/time in UTC time zone. You can shift the date/time to the correct
timezone using the timezone of each individual profile from the /3/snapchat/profiles endpoint.
The last day will be also included in the response.
|
fields |
array , the list of fields that will be returned in the response. Available fields are listed in
the table below.
|
limit |
integer , (optional). The number of results per page. The default value is 10 and the maximal value is 100.
|
sort |
(optional), You can sort the results by specifying a field and sorting order in the sort object:
"field": "created_time"
and "order": "desc" . See the list of fields allowed
for sorting.
|
filter |
(optional), You can filter results by providing the filter parameter with field and value . See
the list of fields allowed for filtering.
|
Parameter for Pagination
after |
string , value of the next property from previous response.
|
Basic Fields
Name | Type | Example | Description |
---|---|---|---|
attachments |
array
|
|
Details about post attachments. |
author |
object
|
|
Author details of the post. |
authorId |
string
|
|
The id of the post author. |
content_type |
string
|
|
Content type of the Snapchat post. |
created_time |
datetime
|
|
Date and time the post was created in Snapchat. |
id |
string
|
|
Snapchat post id. |
media |
string
|
|
Media type of Snapchat post. |
message |
string
|
|
Snapchat post content. |
post_labels |
array
|
|
Content labels (formally post labels) assigned to the post. |
Insights Fields
Metrics prefixed with insights_
can only be used for profiles that have insights_enabled
property set to true
in the response of the /3/snapchat/profiles
endpoint.
Name | Type | Example | Description |
---|---|---|---|
insights_avg_time_watched |
integer
|
|
The average time that users spent watching the video during its lifetime. Note: There can be up to 24h delay in availability for this metric from the Snapchat Organic API. |
insights_comments |
integer
|
|
Total number of comments for a Snapchat post during its lifetime. |
insights_engagements |
integer
|
|
Total number of times users engaged with a post during its lifetime. Learn More. |
insights_impressions |
integer
|
|
The number of impressions for your post. |
insights_impressions_engagement_rate |
float
|
|
Impressions Engagement Rate informs about the percentage of users who engaged with a post during its lifetime given its impressions. Learn More. |
insights_media_view_time |
integer
|
|
The total amount of time (in seconds) that users watched a video and images during its lifetime |
insights_media_views |
integer
|
|
The total number of times a tile was viewed at least 1.2 seconds and viewed at least 25% of the tile on Snapchat within selected time range. |
insights_reach |
integer
|
|
The number of people who saw your post. |
insights_reach_engagement_rate |
float
|
|
Reach engagement rate informs about the percentage of users who engaged with a video during its lifetime given its reach. Learn More. |
insights_screenshots |
integer
|
|
The number of screenshots of a snap. |
insights_shares |
integer
|
|
Total number of shares for a Snapchat post during its lifetime. |
insights_swipe_down |
integer
|
|
The number of swipe downs on an asset. |
insights_swipe_up |
integer
|
|
The number of swipe ups on an asset. |
insights_taps_back |
integer
|
|
The number of times a user taps backward on an Snapchat post |
insights_taps_forward |
integer
|
|
The number of times a user taps forward on an Snapchat post |
insights_video_views |
integer
|
|
Total number of video views for a Snapchat video during its lifetime. |
insights_view_time |
integer
|
|
The total amount of time that users watched the video during its lifetime. |
Fields that might be used to sort Snapchat posts:
Basic Fields- created_time
- insights_avg_time_watched
- insights_comments
- insights_engagements
- insights_impressions
- insights_impressions_engagement_rate
- insights_media_view_time
- insights_media_views
- insights_reach
- insights_reach_engagement_rate
- insights_screenshots
- insights_shares
- insights_swipe_down
- insights_swipe_up
- insights_taps_back
- insights_taps_forward
- insights_video_views
- insights_view_time
Fields that might be used to filter Snapchat posts:
Field | Allowed values | Description | Advanced filter support |
---|---|---|---|
post_labels | * Pattern: .+ |
Content labels (formally post labels) assigned to the post. | ✅ Supported operators:
|
Response
Name | Description |
---|---|
success | Status of the response. Possible values are true or false. |
data |
object containing the following properties:
|
Example request
POST /3/snapchat/profile/posts HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"profiles": ["97e483bf-281e-4f2e-b890-da13edbc8d39"],
"date_start": "2022-05-01",
"date_end": "2022-05-20",
"fields": [
"id",
"created_time",
"attachments",
"insights_reach"
],
"sort": [
{
"field": "created_time",
"order": "desc"
}
],
"limit": 1
}
Example response
{
"success": true,
"data": {
"posts": [
{
"id": "-w1hYHxrReeT-wZJyCTOHwAAgbWdlZ3NlZnZqAYlKyMdWAYlKyMadAAAAAA",
"created_time": "2022-05-19T18:08:45+00:00",
"attachments": [
{
"image_url": "https://cf-st.sc-cdn.net/d/iKCnfr7QDOK3YVvENsqw.410.IRZXSOY?mo=Gj8aGBoAGgAyAQQ6AX1CBgjM8cakBkgCUF5gAVoQRGZMYXJnRodW1ibmFpbKIBEAiaAyIgAqB0lSWlhTT1k%3D&uc=94",
"type": "photo"
}
],
"insights_reach": 1228407
}
],
"next": "eyJjdXJzb3IiOlt7ImZpZWxkIjoiY3JlYXRlZF90aW1lIiwidmFsdWUiOiIyMDE4LTA2LTI4VDEyOjM4OjM0KzAwOjAwIiwib3JkZXIiOiJkZXNjIn1dLCJpZHMiOlsiMTc4OTM5NTExNjIyMTY0NjRfNDkwNDAyMjIwIl19=",
"remaining": 28
}
}
Aggregated Post Metrics
Aggregated Post metrics display lifetime data from individual posts published during the selected time period of your analysis. All post data is aggregated and displayed for the day the post was published, regardless of when the engagement happened. Spam and deleted posts are removed from results.
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
The response uses a timezone assigned to a profile in Suite settings of the account.
The last day will be also included in the response.
|
profiles | array of objects, consists of profile IDs and platforms. You can get the profiles from the List of Connected Profiles section. |
metric | string , the list of available metrics is displayed below. |
dimensions | array of objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimensions in the table of metrics below. Dimensions marked with an asterisk* must be last, and only one such dimension can be used. A maximum of 2 dimensions can be used. |
filter | array of objects. You can filter the results using simple or advanced post filters. See the list of fields allowed for filtering. |
Metrics
Metrics prefixed with insights_
can only be used for profiles from platforms that have insights enabled. Not all metrics are available for all platforms.
All LinkedIn, Pinterest, TikTok and Snapchat metrics can only be used for profiles that have insights_enabled
property set to true
in the response of their respective endpoint /${apiVersion}/{network}/profiles
endpoint.
Aggregation is the type of calculation used for grouping values of a specific metric.
Name | Dimensions | Aggregation | Metrics Description |
---|---|---|---|
engagement_rate
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type published_status sentiment_type |
avg | Engagement Rate for a particular post displays the average number of Interactions per Fan. Engagement Rate is therefore calculated by dividing the number of Interactions of a post by the number of Fans on that day. |
insights_avg_time_watched
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label |
avg | The average time that users spent watching the videos during its lifetime. |
insights_completion_rate
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label media_type |
avg | For TikTok video this is a percentage of times a video was watched in full during its lifetime. For Instagram this is a percentage of times a story impression was not interrupted by an exit, tap back, or tap forward. |
insights_engagements
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label media_type content_type |
sum | Engagements refers to how many times users engaged with a post during its lifetime. Learn More. |
insights_impressions
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type published_status sentiment_type |
sum | The number of impressions on your posts. |
insights_impressions_engagement_rate
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label media_type content_type |
avg | Impressions engagement rate refers to the percentage of users who engaged with a post during its lifetime, given its impressions. Learn More. |
insights_initial_video_views
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type published_status sentiment_type |
sum | The number of first-time plays of your Instagram reel, including plays of 1ms or more. This metric excludes replays. |
insights_link_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 users clicked on links that redirected them to a given destination. |
insights_media_view_time
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type |
sum | The total amount of time (in seconds) that users watched a video and images during its lifetime |
insights_media_views
|
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 clicks received by a post during its lifetime. |
insights_post_saves
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type |
sum | The number of times people saved the content during its lifetime. |
insights_reach_engagement
|
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 sentiment_type |
avg | Number of people who have seen any content associated with your Page. (Unique Users) |
insights_save_rate
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type published_status |
avg | The total saves of your content divided by the total number of times your content were on screen. |
insights_screenshots
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type |
sum | The number of screenshots of a snap. |
insights_story_exits
|
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_swipe_down
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type |
sum | The number of swipe downs on an asset. |
insights_swipe_up
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type |
sum | The number of swipe ups on an asset. |
insights_video_completed_views
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type published_status sentiment_type |
sum | The number of times your video was viewed to 95% of its length. |
insights_video_starts
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type published_status sentiment_type |
sum | Total number of video starts. |
insights_video_views
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type published_status sentiment_type |
sum | An aggregation of video views across multiple platforms. The definition of a video view differs per platform. FB, IG, LI count views of 3+ seconds; PI count views of 2+ seconds; YT counts views of 30+ seconds. For IG Reels video views count number of plays (video sessions with 1 ms+ of playback, excluding replays). For SC, the number of times a video snap was viewed during its lifetime. A view is counted immediately upon opening the video snap and for each time it is rewatched. Note: FB, IG, LI, TT, SC, PI and TW data represents Insights metrics. YT data comes from public sources. |
insights_video_views_10s
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type published_status sentiment_type |
sum | The number of times your video was viewed for at least 10 seconds. |
insights_video_views_unique
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type published_status sentiment_type |
sum | The number of people who have watched your video for at least 3 seconds. |
insights_view_time
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label |
sum | The total amount of time that users watched the video during its lifetime. |
interactions
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type published_status interaction_type sentiment_type |
sum | Number of interactions on page posts. YouTube dislike count is no longer available for this metric as of December 13, 2021 Learn more. |
interactions_per_1k_fans
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type published_status sentiment_type |
sum | Number of interactions on page posts per 1k fans. |
likes
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label media_type sentiment_type |
sum | Number of likes of profile posts. For Linkedin a public version of reactions is used. Learn More. |
number_of_comments
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type published_status sentiment_type |
sum | Number of comments on page posts. |
page_posts
|
date.day date.month date.quarter date.week date.year platform profile post_labels profile_label content_type media_type published_status sentiment_type |
sum | Number of page posts. |
page_replies
|
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:
Field | Allowed values | Description | Advanced filter support |
---|---|---|---|
content_type | post reply shared story snap |
Type of content. | ✅ Supported operators:
|
media_type | album animated_gif carousel link note offer photo poll reel status video audio activity doc map combined unknown |
Type of media used in content. | ✅ Supported operators:
|
platform | twitter instagram facebook youtube linkedin pinterest tiktok snapchat |
Publishing platform of content. | ✅ Supported operators:
|
post_labels | * Pattern: .+ |
Content labels assigned to your posts | ✅ Supported operators:
|
profile_labels | * Pattern: .+ |
Profile labels assigned to your profiles. | ✅ Supported operators:
|
Example request
POST /3/aggregated-metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"profiles": [
{
"id": "564919357",
"platform": "twitter"
},
{
"id": "164929129743",
"platform": "facebook"
}
],
"date_start": "2018-11-01",
"date_end": "2018-11-12",
"metric": "page_posts",
"dimensions": [
{
"type": "profile"
}
],
"filter": [
{
"field": "post_labels",
"value": [
"e3af7de2d2274393b86b"
]
}
]
}
Example response
{
"success": true,
"header": [
{
"type": "profile",
"rows": [
{
"id": "564919357",
"platform": "twitter"
},
{
"id": "164929129743",
"platform": "facebook"
}
]
},
{
"type": "metric",
"rows": [
"page_posts"
]
}
],
"data": [
[
3
],
[
6
]
]
}
Advanced Post Filters
Introduction
Some fields support advanced possibilities of filtering. It is possible to create filter rules as a combination of match_all
and match_any
clauses. A combination with simple filter definition is also possible.
The filter consists of two types of clauses:
Simple filter clauses
Specifies particular field(s) and its values. Posts having these values will be part of the results.
{
"field": "type",
"value": [
"photo",
"status"
]
}
Advanced filter clauses
The advanced filter is used to combine multiple filters in a logical meaning as AND
, and OR
.
match_all
- Represents 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"
]
}
]
}
Assets
Use these set of endpoints to integrate your current assets management solutions to our Collections.
Collections
Manage your collections with these endpoints. Besides getting a list of all the collections you have, you will also be able to create, update and archive them.
List Collections
Get a list of all collections within the account.
Example request
GET /3/collections HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Example response
{
"success": true,
"data": [
{
"id": "g11N6XQBZejoR1EGGGq8",
"name": "My first collection",
"createdBy": {
"userId": "1336595",
"email": "my.email@emplifi.io"
},
"createdTime": "2020-10-02T12:32:57.849Z",
"updatedTime": "2020-10-02T12:32:58.603Z",
"status": "active",
"permission": "private"
}
]
}
Create Collection
Create a new private or global collection inside your account. You can have a total of maximum 100 collections created.
Parameters
Name | Description |
---|---|
name | string . The name of the collection that will be created. |
description | string , (optional). Describes more in detail the colletion that will be created. |
permission | string , it can be only private or global . Defines the permission rule for the newly created Collection. |
Example request
POST /3/collections HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"name": "New Collection",
"description": "New example collection",
"permission": "private"
}
Example response
{
"success": true,
"data": {
"collectionId": "O1yxunQBZejoR1EGQshy"
}
}
Edit Collection
Edit a collection name and/or description.
Parameters
Name | Description |
---|---|
collectionId | string . The collection id. |
name | string , (optional). The name of the collection that will be created. |
description | string , (optional). Describes more in detail the colletion that will be created. |
permission | string , (optional). New permission. Changes the collection permission to global. Please note that you can only change from private to global. |
Please note that name, description and permission are optional, but it's required to send at least one of them.
Example request
PATCH /3/collections HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"collectionId": "collection-id",
"name": "a-new-name",
"description": "a-new-description",
"permission": "global"
}
Example response
{
"success": true,
"data": {
"status": "ok"
}
}
Archive Collection
Archive a collection. Collection can be restored at any point.
Parameters
Name | Description |
---|---|
collectionId | string . The collection id. |
Example request
POST /3/collections/archive HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"collectionId": "collection-id"
}
Example response
{
"success": true,
"data": {
"status": "ok"
}
}
Delete Collection
Delete a collection from suite. If there are any assets within the collection, those will get deleted as well. You can only delete a collection that has been archived. Please be extremely cautious when using this endpoint as this action is not reversible.
Parameters
Name | Description |
---|---|
collectionId | string . The collection id. |
Example request
DELETE /3/collections HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"collectionId": "collection-id"
}
Example response
{
"success": true,
"data": {
"status": "ok"
}
}
Restore Collection
Restore a previously archived collection. Collection can be archived again anytime.
Parameters
Name | Description |
---|---|
collectionId | string . The collection id. |
Example request
POST /3/collections/restore HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"collectionId": "collection-id"
}
Example response
{
"success": true,
"data": {
"status": "ok"
}
}
Assets
Manage assets with these endpoints. You can upload your own assets to existing collections or download them.
Upload Asset
Upload an asset to a collection. You can only upload asset to a collection that already exists and you have permissions to. The maximum size of an asset you can upload is 5GB. However, for best results, upload an asset not more than 100MB. There can only be up to 500 assets per collection.
Uploading an asset is a 2 part process. This first is calling this endpoint and passing all relevant information to register the asset.
Upon registering, this endpoint will return a pre-signed URL that you should then use to upload the actual asset itself. The URL will expire in 10 minutes. More information regarding the pre-signed URL can be found here.
In your PUT request to the pre-signed URL, you should remove the authorization header. Please don't forget to include the necessary headers i.e Content-Type, Content-Length and Content-MD5 as specified in the second table below.
Parameters for 1st step - generating pre-signed URL
Name | Description |
---|---|
collectionId | string . The collection id. |
assetName | string . The name of the file to be uploaded. It does not necessarily need to be the existing name of that file and can be a new name. Needs to include the file extension. For example, the asset name can be thisisanimage.jpeg or thisisavideo.mkv. |
assetContentType | string . The MIME type of the file to be uploaded. It is only possible to upload either an image or a video. It is usually in the format of type/extension. For example, image/jpeg or video/mov. Check here to learn more about MIME types. |
assetMd5 | string . The MD5 checksum value of the file to be uploaded that is encoded to base64. More information on how to obtain this value can be found here, specifically the Resolution section. |
description | string , (optional). Asset's description. |
note | string , (optional). Asset's note. |
labelIds | array of string , (optional). An array of Emplifi label ids with which to tag the asset. |
Headers for 2nd step - uploading file to pre-signed URL
Name | Description |
---|---|
Content-Length | The size of the file to be uploaded. This should be in bytes. |
Content-MD5 | The MD5 checksum value of the file to be uploaded that is encoded to base64. This should be the exact same value as the assetMd5 parameter specified in the first step when registering the asset. |
Content-Type | The MIME type of the file to be uploaded. This should be the exact same value as the assetContentType parameter specified in the first step when registering the asset. |
The body should be the file to be uploaded only.
Example request
POST /3/collections/assets HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"collectionId": "collection-id",
"assetName": "asset-name",
"assetContentType": "image/jpeg",
"assetMd5": "asset-md5",
"description": "some description",
"note": "some note",
"labelIds": ["labelId-1"]
}
Example response
{
"success": true,
"data": {
"assetUploadUrl": "https://sbks-builder.s3-accelerate.amazonaws.com/production/content-hub/collection/account/123456/asset-name?AWSAccessKeyId=SOMEACCESSKEYID&Content-MD5=asset-md5&Content-Type=image%2Fjpeg&Expires=1603406210&Signature=SOMESIGNATURE"
}
}
Example request to pre-signed URL
PUT https://sbks-builder.s3-accelerate.amazonaws.com/production/content-hub/collection/account/123456/asset-name?AWSAccessKeyId=SOMEACCESSKEYID&Content-MD5=asset-md5&Content-Type=image%2Fjpeg&Expires=1603406210&Signature=SOMESIGNATURE HTTPS
Content-Type: image/jpeg
Content-MD5: asset-md5
Content-Length: 12345
Body: file.jpeg
Example response from pre-signed URL
Status: 200
Get Assets
Get the metadata and download url for all assets within a collection, or for the specified asset. All that is required is the collection id, and the asset id in case of retrieving data only for a specific asset. URLs for downloading the assets will expire in an hour.
Query String Parameters
Name | Description |
---|---|
collectionId | string . The collection id. |
assetId | string , (optional). The asset id. |
Example request (all collection assets)
GET /3/collections/assets?collectionId=<collection_id> HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Example response
{
"success": true,
"data": [
{
"id": "NOo5u3QBrFWnaVYeCNdn",
"userId": "d1961087",
"accountId": "172196",
"description": "aaaa something or other something",
"createdTime": "2020-09-23T13:48:31.206Z",
"updatedTime": "2020-09-23T13:48:31.206Z",
"collectionId": "_MzdunQBrFWnaVYeXuI8",
"type": "video",
"url": "https://cdn-assets-sign.socialbakers.com/dev/content-hub/collection/account/172196/team-testing/aosdijaosid.mov?Expires=1604056447&Key-Pair-Id=APKAIEJK4DOLCYRB43WQ&Signature=O0d-BDJDatF~OAkRnl1~u8Fnu4L8S~q0~PVdkaRlBLTKdw9xFr8svwqJjw0tRN9wAh5eDDbDldLN2UYMCXs~3wxOXF7RvC0uhX~73f7Dgtbs7eQkWov-4drco-IpUSrykbKAARULxCZBNWEnXXNa6CghWpP3rgWnrGI8FKAwoZ4BTsaIX-z~cae3~sXSrG6r-3xH7XbxDQpzLxLjSJN9YDuPnpuqiXbiiLt4X8hm5G6qa93WoUDtj2s3zc0ik6r5xARGRN0dJM7sh2~ewDE3NOhAP5GC0lXc6mwC52TYMP7-cmSlPPw6LsH7~jPvF8zrw5vMaze2hE3~5APe1GXgWQ__",
"labels": []
},
{
"id": "-e1Bu3QBrFWnaVYeX7Uh",
"userId": "d1961087",
"accountId": "172196",
"description": "aaaa something or other",
"createdTime": "2020-09-23T13:57:37.696Z",
"updatedTime": "2020-09-23T13:57:37.696Z",
"collectionId": "_MzdunQBrFWnaVYeXuI8",
"type": "video",
"url": "https://cdn-assets-sign.socialbakers.com/dev/content-hub/collection/account/172196/team-testing/aosdijaosid.mov?Expires=1604056447&Key-Pair-Id=APKAIEJK4DOLCYRB43WQ&Signature=O0d-BDJDatF~OAkRnl1~u8Fnu4L8S~q0~PVdkaRlBLTKdw9xFr8svwqJjw0tRN9wAh5eDDbDldLN2UYMCXs~3wxOXF7RvC0uhX~73f7Dgtbs7eQkWov-4drco-IpUSrykbKAARULxCZBNWEnXXNa6CghWpP3rgWnrGI8FKAwoZ4BTsaIX-z~cae3~sXSrG6r-3xH7XbxDQpzLxLjSJN9YDuPnpuqiXbiiLt4X8hm5G6qa93WoUDtj2s3zc0ik6r5xARGRN0dJM7sh2~ewDE3NOhAP5GC0lXc6mwC52TYMP7-cmSlPPw6LsH7~jPvF8zrw5vMaze2hE3~5APe1GXgWQ__",
"labels": []
}
]
}
Example request (single asset)
GET /3/collections/assets?collectionId=<collection_id>&assetId=<asset_id> HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Example response
{
"success": true,
"data": {
"id": "NOo5u3QBrFWnaVYeCNdn",
"userId": "d1961087",
"accountId": "172196",
"description": "aaaa something or other something",
"createdTime": "2020-09-23T13:48:31.206Z",
"updatedTime": "2020-09-23T13:48:31.206Z",
"collectionId": "_MzdunQBrFWnaVYeXuI8",
"type": "video",
"url": "https://cdn-assets-sign.socialbakers.com/dev/content-hub/collection/account/172196/team-testing/aosdijaosid.mov?Expires=1604056447&Key-Pair-Id=APKAIEJK4DOLCYRB43WQ&Signature=O0d-BDJDatF~OAkRnl1~u8Fnu4L8S~q0~PVdkaRlBLTKdw9xFr8svwqJjw0tRN9wAh5eDDbDldLN2UYMCXs~3wxOXF7RvC0uhX~73f7Dgtbs7eQkWov-4drco-IpUSrykbKAARULxCZBNWEnXXNa6CghWpP3rgWnrGI8FKAwoZ4BTsaIX-z~cae3~sXSrG6r-3xH7XbxDQpzLxLjSJN9YDuPnpuqiXbiiLt4X8hm5G6qa93WoUDtj2s3zc0ik6r5xARGRN0dJM7sh2~ewDE3NOhAP5GC0lXc6mwC52TYMP7-cmSlPPw6LsH7~jPvF8zrw5vMaze2hE3~5APe1GXgWQ__",
"labels": []
}
}
Delete Asset
Delete an asset in a collection from suite. Please be extremely cautious when using this endpoint as this action is not reversible.
Parameters
Name | Description |
---|---|
collectionId | string . The collection id. |
assetId | string . The asset id. |
Example request
DELETE /3/collections/assets HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"collectionId": "_MzdunQBrFWnaVYeXuI8",
"assetId": "13QGlHUBN8G-fcdJO6ZX"
}
Example response
{
"success": true,
"data":
{
"status": "ok"
}
}
Community
Content Labeling
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 /3/community/{network}/labels HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"content_ids": [
// Facebook conversation ID
"754387418054186-t_100022491363476",
// Facebook page post ID
"849715935050458_1520511894637588"
],
"labels": ["my label"]
}
Example response
{
"success": true,
"data": {
"contents": {
"754387418054186-t_100022491363476": {
"status": "ok"
},
"849715935050458_1520511894637588": {
"status": "ok"
}
}
}
}
Labelling content across networks
To label contents from multiple networks at once, use a version of the endpoint that does not include the network in the path. Instead, all content IDs should be prefixed by network-
which is true also for the response.
This endpoint support all networks available in Community.
Example request
PUT /3/community/content/labels HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"content_ids": [
// Facebook conversation ID
"faceboook-754387418054186-t_100022491363476",
// Facebook page post ID
"facebook-849715935050458_1520511894637588"
],
"labels": ["my label"]
}
Example response
{
"success": true,
"data": {
"contents": {
"facebook-754387418054186-t_100022491363476": {
"status": "ok"
},
"facebook-849715935050458_1520511894637588": {
"status": "ok"
}
}
}
}
Content
Returns a set of messages in Community created during the specified date range for specified profiles.
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the ISO date-time format without timezone.
|
listening_queries |
array of strings. You can get the listening queries from the List of Listening Queries section.
Request can contain either listening_queries or profiles , not both.
|
profiles |
array of objects, consists of profile IDs and platforms.
You can get the profiles from the List of Connected Profiles section.
Request can contain either listening_queries or profiles , not both.
|
fields |
array , the list of fields that will be returned in the response. Available fields are listed in the table below.
|
limit |
integer , (optional). The number of results per page. The default value is 10 and the maximal value is 100.
|
sort |
(optional), You can sort the results by specifying a field and sorting order in the sort object: "field": "created_time"
and "order": "desc" . See the list of fields allowed for sorting.
|
filter |
(optional), You can filter results by providing the filter parameter with field and value . See
the list of fields allowed for filtering.
|
Parameter for Pagination
after |
string , value of the next property from previous response.
|
Fields
Name | Type | Example | Description |
---|---|---|---|
author |
object
|
|
Information about author of the post. |
community_type |
string
|
|
Type of the post in community. |
content_type |
string
|
|
Content type of the post. |
created_time |
datetime
|
|
Date and time the post was created. |
id |
string
|
|
Post id. |
message |
string
|
|
Message of the post. |
messages |
array
|
|
Messages in a conversation post (only for content of type conversation). |
origin |
string
|
|
Source of the post. |
parent_post |
object
|
|
Parent post (e.g. for a comment). |
platform |
string
|
|
Platform, where the post was created. |
post_labels |
array
|
|
Labels assigned to the post. |
profileId |
string
|
|
Id of the profile associated with the post. |
response_first |
object
|
|
First response to the post (e.g. first reply in a comment thread). |
sentiment |
string
|
|
Users sentiment towards the post. |
url |
string
|
|
Link to the post. |
Sort
Basic Fields- created_time
Filter
Field | Allowed values | Description | Advanced filter support |
---|---|---|---|
content_type | comment conversation post shared story |
Content type of the post. | ✅ Supported operators:
|
origin | User-Generated Content Brand's Content |
Source of the post. | ✅ Supported operators:
|
post_labels | * Pattern: .+ |
Labels assigned to the post. | ✅ Supported operators:
|
Limits
There is a 90 day data retention limit for community data. So the date of date_start
and date_end
can not be more than 90 days in the past.
Response
Name | Description |
---|---|
success | Status of the response. Possible values are true or false . |
data |
object containing the following properties:
|
Example request
POST /3/community/posts HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"profiles": [
{
"id": "1784142059xxxxxxx",
"platform": "facebook"
}
],
"date_start": "2021-09-23T12:00:00",
"date_end": "2021-09-23T18:00:00",
"fields": [
"author",
"community_type",
"content_type",
"created_time",
"id",
"message",
"messages",
"origin",
"parent_post",
"platform",
"post_labels",
"profileId",
"response_first",
"sentiment",
"url"
],
"limit": 10,
"sort": [
{
"field": "created_time",
"order": "desc"
}
],
"filter": [
{
"field": "content_type",
"value": "comment"
},
{
"field": "origin",
"value": "Brand's Content"
},
{
"match_all": [
{
"field": "post_labels",
"value": [
"fc3fa9ff8df14xxxxxxx",
"785c242afee7418e9877bb885xxxxxxx"
]
}
]
}
]
}
Example response
{
"success": true,
"data": {
"posts": [
{
"author": {
"id": "1784142059xxxxxxx",
"name": "Emplifi",
"url": "https://www.facebook.com/Emplifi/"
},
"community_type": "comment",
"content_type": "comment",
"created_time": "2021-09-23T16:01:57+02:00",
"id": "1787362461xxxxxxx",
"message": "hello",
"messages": [],
"origin": "Brand's Content",
"parent_post": {
"id": "183693293517xxxxxxx",
"message": "greetings",
"post_labels": [
{"id": "fc3f23a18df14xxxxxxx", "name": "Label A"}
]
},
"platform": "facebook",
"post_labels": [
{"id": "785c242afee7418e9877bb885xxxxxxx", "name": "Label B"},
{"id": "fc3fa9ff8df14xxxxxxx", "name": "Label C"}
],
"profileId": "1784142059xxxxxxx",
"response_first": {
"id": "163293297011xxxxxxx",
"message": "ahoy",
"response_time": "216798",
"response_time_real": "1056753",
"account_id": "387xxx",
"user_id": "1207xxx",
"first_name": "John",
"last_name": "Doe"
},
"sentiment": "no_sentiment",
"url": "https://www.facebook.com/135454333xxxxxxx"
}
],
"next": "eyJuZXh0IjoiZXlKeGRXVnllU0k2ZXlKbVpXVmtWSGx3WlNJNkluVnpaWEpHWldWa0lpd2labWxsYkdSeklqcGJJbWxrSWl3aVkzSmxZWFJsWkZScGJXVWlMQ0poZFhSb2IzSkpibVp2SWl3aVkyOXVQ==",
"remaining": 72
}
}
Metrics
Returns Community related metrics for requested profiles.
Request
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the ISO date-time format without timezone.
|
listening_queries |
array of strings. You can get the listening queries from the List of Listening Queries section.
Request can contain either listening_queries or profiles , not both.
|
profiles |
array of objects, consists of profile IDs and platforms.
You can get the profiles from the List of Connected Profiles section.
Request can contain either listening_queries or profiles , not both.
|
metrics |
array of objects.
See parameters of the object in table below.
Only one metric can be specified in a single request.
|
dimensions (optional) |
array of objects.
The data of the metric can be split by a specific dimension.
See the table of available dimensions.
|
filter (optional) |
array of objects.
You can filter the results using simple or advanced post filters.
See the table of fields allowed for filtering.
|
Metrics
Parameters
Name | Description |
---|---|
metric | string , table of available metrics is displayed below. |
Available metrics
Name | Dimensions | Aggregation | Metric Description |
---|---|---|---|
content_count | community_type date post_label profile profile_label resolve_status sentiment |
sum | The total number of available content. |
message_count | community_type date post_label profile profile_label resolve_status sentiment |
sum | The total number of messages in content of type conversation. |
response_time | community_type post_label profile profile_label resolve_status response_date sentiment |
median | The message response time for content of type conversation. |
response_time_business_hours | community_type post_label profile profile_label resolve_status response_date sentiment |
median | The message response time, in business hours only, for content of type conversation. |
salesforce_lead_count | community_type post_label profile profile_label resolve_status sentiment response_date user_actions_created_time |
sum | The total number of escalated Salesforce lead in available content. |
salesforce_case_count | community_type post_label profile profile_label resolve_status sentiment response_date user_actions_created_time |
sum | The total number of escalated Salesforce cases in available content. |
Dimensions
Parameters
Name | Description |
---|---|
type |
string , table of available dimension types is displayed below.
|
aggregation (optional) |
string , can be used only with date /response_date /user_actions_created_time dimensions,
which use aggregation parameter instead of group .
|
group (optional) |
object , can be used to limit and sort the result buckets.
See parameters of the object in table below.
|
Group parameters
Name | Description |
---|---|
sort |
object , can be used to define sorting logic.
Consists of parameters key and order .
|
sort.key |
string , possible values are value or name .
|
sort.order (optional) |
string , possible values are desc (default) or asc .
|
limit |
integer , limits number of result buckets in response.
Default is 10 .
|
Available dimension aggregations
Name | Aggregation |
---|---|
date | hour day month quarter week year |
response_date | hour day month quarter week year |
user_actions_created_time | hour day month quarter week year |
Filter
Field | Allowed values | Description | Advanced filter support |
---|---|---|---|
community_type | ad_comment comment direct_message mention_comment mention_post mention_story_mention wall_post review |
✅ Supported operators:
|
|
origin | Brand's Content User-Generated Content |
Source of the content. | ✅ Supported operators:
|
post_labels | * Pattern: .+ |
Labels assigned to the post. | ✅ Supported operators:
|
profile_labels | * Pattern: .+ |
Labels assigned to the profile. | ✅ Supported operators:
|
Response
Parameters
Name | Description |
---|---|
success |
boolean , status of the response.
Possible values are true or false .
|
header |
array of objects. Result format depends on request parameters.
|
data |
array of arrays. Result format depends on request parameters.
|
Example request
POST /3/community/metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"profiles": [
{
"id": "164929xxxxxx",
"platform": "facebook"
},
{
"id": "1784140102xxxxxx",
"platform": "instagram"
}
],
"date_start": "2021-11-14T14:30:00",
"date_end": "2021-11-15T11:59:59",
"dimensions": [
{
"type": "profile"
},
{
"type": "community_type",
"group": {
"sort": {
"key": "value",
"order": "asc"
},
"limit": 2
}
},
{
"type": "date",
"aggregation": "day"
}
],
"metrics": [
{
"metric": "content_count"
}
],
"filter": [
{
"field": "origin",
"value": "Brand's Content"
},
{
"match_all": [
{
"field": "post_labels",
"value": [
"fc3fa9ff8df14xxxxxxx",
"785c242afee7418e9877bb885xxxxxxx"
]
}
]
}
]
}
Example response
{
"success": true,
"header": [
{
"type": "profile",
"rows": [
{
"id": "164929xxxxxx",
"platform": "facebook"
},
{
"id": "1784140102xxxxxx",
"platform": "instagram"
}
]
},
{
"type": "community_type",
"rows": [
"direct_message",
{
"other": [
"ad_comment",
"comment",
"mention_comment",
"mention_post",
"mention_story_mention",
"wall_post"
]
}
]
},
{
"type": "date",
"rows": [
"2021-11-14",
"2021-11-15"
]
},
{
"type": "metric",
"rows": [
"content_count"
]
}
],
"data": [
[
[
[
3
],
[
45
]
],
[
[
5
],
[
98
]
]
],
[
[
[
2
],
[
230
]
],
[
[
1
],
[
73
]
]
]
]
}
Listening
Content
Returns a set of posts created during the specified date range and matched by the requested Listening queries.
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
Your request is transformed using the time zone assigned to a profile in the Suite settings of your account.
The response of the endpoint displays the date/time in UTC time zone.
The last day will be also included in the response.
|
listening_queries |
array of strings, consists of listening query IDs.
You can get the listening query IDs from the List of Listening Queries section.
|
fields |
array , the list of fields that will be returned in the response. Available fields are listed in
the table below.
|
limit |
integer , (optional). The number of results per page. The default and maximum value is 100.
|
sort |
(optional), You can sort the results by specifying a field and sorting order in the sort object: "field": "interactions"
and "order": "desc" . See the list of fields allowed
for sorting.
|
filter |
(optional), You can filter results by providing the filter parameter with field and value . See
the list of fields allowed for filtering.
|
Parameter for Pagination
after |
string , value of the next property from previous response.
|
Basic Fields
Name | Type | Example | Description |
---|---|---|---|
attachments |
array
|
|
Post attachments. Objects contain fields depending on platform and attachment type: "title", "description", "url", "type", "image_url", "video_url". |
author |
object
|
|
Information about author of the post. |
authorId |
string
|
|
Id of the author of the post. |
comments |
integer
|
|
Comment count of the post. |
content_type |
string
|
|
Content type of the post. |
country |
string
|
|
Country of origin of the post. |
created_time |
datetime
|
|
Date and time the post was created. |
id |
string
|
|
Post id. |
interactions |
integer
|
|
Number of post interactions. |
language |
string
|
|
Language of the post. |
listening_queries |
array
|
|
Listening queries associated with this post. |
media_type |
string
|
|
Media type of the post. |
mentions |
array
|
|
Ids of mentioned profiles in the post (Twitter only). |
message |
string
|
|
Message of the post. |
platform |
string
|
|
Platform, where the post was created. |
post_labels |
array
|
|
Content labels assigned to the post. |
potential_impressions |
integer
|
|
Potential impressions of the post. |
profileId |
string
|
|
Id of the profile associated with the post. |
sentiment |
string
|
|
Users sentiment towards the post. |
shares |
integer
|
|
Number of times the post was shared on the platform. |
site |
string
|
|
Website from which the post was obtained. |
url |
string
|
|
Link to the post. |
Fields that might be used to sort Listening posts:
Basic Fields- comments
- interactions
- potential_impressions
- shares
Fields that might be used to filter Listening posts:
Field | Allowed values | Description | Advanced filter support |
---|---|---|---|
content_type | post comment |
Content type of the post. | ✅ Supported operators:
|
country | * Pattern: .+ |
Country of origin of the post. | ✅ Supported operators:
|
language | * Pattern: .+ |
Language of the post. | ✅ Supported operators:
|
media_type | album animated_gif carousel link note offer photo poll reel status video |
Media type of the post. | ✅ Supported operators:
|
platform | blogs facebook forums instagram news twitter youtube |
Platform, where the post was created. | ✅ Supported operators:
|
post_labels | * Pattern: .+ |
Content labels assigned to the post. | ✅ Supported operators:
|
sentiment | positive negative neutral |
Users sentiment towards the post. | ✅ Supported operators:
|
Response
Name | Description |
---|---|
success | Status of the response. Possible values are true or false. |
data |
object containing the following properties:
|
Example request
POST /3/listening/posts HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"listening_queries": [
"LNQ_394957_62a11038bcd2c60422edb994",
"LNQ_394957_6241c597857f917a0529975d"
],
"date_start": "2022-06-01",
"date_end": "2022-06-30",
"fields": [
"id",
"created_time",
"author",
"content_type",
"comments",
"interactions"
],
"sort": [
{
"field": "comments",
"order": "desc"
}
],
"filter": [
{
"field": "platform",
"value": "facebook"
}
],
"limit": 5
}
Example response
{
"success": true,
"data": {
"posts": [
{
"id": "164929129743_10155892118379744",
"created_time": "2022-06-04T16:06:00+00:00",
"author": {
"id": "164929129743",
"name": "Emplifi",
"url": "https://www.facebook.com/Emplifi"
},
"content_type": "post",
"comments": 153,
"interactions": 5628
}
],
"next": "eyJuZXh0IjoiZXlKeGRXVnllU0k2ZXlKbVpXVmtWSGx3WlNJNkluVnpaWEpHWldWa0lpd2labWxsYkdSeklqcGJJbWxrSWl3aVkzSmxZWFJsWkZScGJXVWlMQ0poZFhSb2IzSkpibVp2SWl3aVkyOXVQ==",
"remaining": 194
}
}
Metrics
Returns metrics for requested listening queries.
Request
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the ISO date-time format without timezone.
|
listening_queries |
array of strings, consists of listening query IDs.
You can get the listening query IDs from the List of Listening Queries section.
|
metrics |
array of objects.
See parameters of the object in table below.
|
dimensions (optional) |
array of objects.
The data of the metric can be split by a specific dimension.
See the metrics table below for list of available dimensions.
|
filter (optional) |
array of objects.
You can filter the results using simple or advanced post filters.
See the table of fields allowed for filtering.
|
Metrics
Parameters
Name | Description |
---|---|
metric |
string , table of available metrics is displayed below.
|
Available metrics
Name | Dimensions | Aggregation | Metric Description |
---|---|---|---|
authors |
content_type ,country ,hashtag ,keyword ,language ,location ,media_type ,organization ,person ,platform ,post_label ,profession ,sentiment ,topic ,url
|
sum | The number of users who produced content. |
comments |
content_type ,country ,hashtag ,keyword ,language ,location ,media_type ,organization ,person ,platform ,post_label ,profession ,sentiment ,topic ,url
|
sum | The number of comments. |
content_count |
content_type ,country ,hashtag ,keyword ,language ,location ,media_type ,organization ,person ,platform ,post_label ,profession ,sentiment ,topic ,url
|
sum | The number of total available content. |
interactions |
content_type ,country ,hashtag ,keyword ,language ,location ,media_type ,organization ,person ,platform ,post_label ,profession ,sentiment ,topic ,url
|
sum | The number of interactions. |
potential_impressions |
content_type ,country ,hashtag ,keyword ,language ,location ,media_type ,organization ,person ,platform ,post_label ,profession ,sentiment ,topic ,url
|
sum | The number of potential impressions. |
shares |
content_type ,country ,hashtag ,keyword ,language ,location ,media_type ,organization ,person ,platform ,post_label ,profession ,sentiment ,topic ,url
|
sum | The number of shares. |
Dimensions
Parameters
Name | Description |
---|---|
type |
string , table of available dimension types is displayed below.
|
group (optional) |
object , can be used to limit and sort the result buckets.
See parameters of the object in table below.
|
Group parameters
Name | Description |
---|---|
sort |
object , can be used to define sorting logic.
Consists of parameters key and order .
|
sort.key |
string , possible values are value or name .
|
sort.order (optional) |
string , possible values are desc (default) or asc .
|
limit |
integer , limits number of result buckets in response.
Default is 10 .
|
Filter
Field | Allowed values | Description | Advanced filter support |
---|---|---|---|
author | [platform]-[profile_id] Example: facebook-1649291xxxxx |
✅ Supported operators:
|
|
content_type | post comment share |
✅ Supported operators:
|
|
country | GB FR CA NE ... |
List of codes from ISO 3166-1 alpha-2 | ✅ Supported operators:
|
language | en fr de es ... |
List of codes from ISO 639-1 (or ISO 639-2 if missing in ISO 639-1) | ✅ Supported operators:
|
media_type | album animated_gif carousel link note offer photo poll reel status video |
✅ Supported operators:
|
|
platform | facebook instagram linkedin pinterest tiktok twitter youtube blogs forums news |
✅ Supported operators:
|
|
post_labels | * Pattern: .+ |
See List of Content Labels | ✅ Supported operators:
|
sentiment | positive negative neutral no_sentiment |
✅ Supported operators:
|
Response
Parameters
Name | Description |
---|---|
success |
boolean , status of the response.
Possible values are true or false .
|
header |
array of objects. Result format depends on request parameters.
|
data |
array of arrays. Result format depends on request parameters.
|
Example request
POST /3/listening/metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"date_start": "2022-01-01T00:30:00",
"date_end": "2022-12-31",
"listening_queries": [
"LNQ_394xxx_6241c636857f917a0xxxxxxx",
"LNQ_394xxx_62a11038bcd2c6042xxxxxxx"
],
"metrics": [
{
"metric": "comments"
}
],
"dimensions": [
{
"type": "platform",
"group": {
"sort": {
"key": "value",
"order": "asc"
},
"limit": 3
}
},
{
"type": "content_type"
}
],
"filter": [
{
"field": "sentiment",
"value": "positive"
}
]
}
Example response
{
"success": true,
"header": [
{
"type": "platform",
"rows": [
"blogs",
"forums",
{
"other": {
"length": 3
}
}
]
},
{
"type": "content_type",
"rows": [
"comment",
"post"
]
},
{
"type": "metric",
"rows": [
"comments"
]
}
],
"data": [
[
[
21
],
[
3
]
],
[
[
0
],
[
null
]
],
[
[
4
],
[
51
]
]
]
}
Facebook Ads
Content
Returns a set of Facebook ads active during the specified date range for specified ad accounts.
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the ISO date-time format without timezone.
|
ad_accounts |
array of strings. Max. limit is 500 account strings.
|
ad_campaigns |
array of compound strings (optional). Use pattern AdAccountId#CampaignId (e.g. 123#456 ). Max. limit is 500 campaign strings.
|
fields |
array , the list of fields that will be returned in the response. Available fields are listed in the table below.
|
limit |
integer (optional). The number of results. The default value is 10 and the maximal value is 500.
|
sort |
object (optional). You can sort the results by specifying a field and sorting order in the sort object: "field": "impressions"
and "order": "desc" . See the list of fields allowed for sorting.
|
filter |
array of objects (optional). You can filter results by providing the filter parameter with field and value . See
the list of fields allowed for filtering.
|
Fields
Name | Type | Example | Description |
---|---|---|---|
ad_account_id |
string
|
|
Ad account unique identifier. |
ad_account_name |
string
|
|
Ad account name. |
ad_campaign_id |
string
|
|
Ad campaign unique identifier. |
ad_campaign_name |
string
|
|
Ad campaign name. |
ad_set_id |
string
|
|
Ad set unique identifier. |
ad_set_name |
string
|
|
Ad set name. |
ad_type |
string
|
|
Ad type. |
attachments |
array
|
|
Ad attachments types are "photo", "video", "link". A special type is "carousel" which contains nested "attachments" |
clicks |
integer
|
|
The number of clicks on your ad. |
cost_per_post_engagement |
float
|
|
The cost per post engagement. |
cpc |
float
|
|
The cost per click. |
cpm |
float
|
|
The cost per 1,000 impressions. |
created_time |
datetime
|
|
Date and time the ad was created in Facebook. |
ctr |
float
|
|
The percentage of times that people saw your ad and performed a click. |
engagement_rate |
float
|
|
The rate at which your ad receives interactions. |
id |
string
|
|
Ad unique identifier. |
impressions |
integer
|
|
The number of times your ad was on-screen. |
inline_link_clicks |
integer
|
|
The number of clicks on links within the ad that led to advertiser-specified destinations, on or off Facebook. |
interaction_count |
integer
|
|
The total number of reactions, comments and shares on your ad. |
landing_page_view |
integer
|
|
The number of times users clicked on your ad link and successfully loaded the intended destination webpage. |
lead |
integer
|
|
A submission of information by a customer with the understanding that they may be contacted at a later date by your business. For example, submitting a form or signing up for a trial. |
message |
string
|
|
The text message of your ad. |
name |
string
|
|
The name of your ad. |
objective |
string
|
|
Ad objective. |
placements |
object
|
|
Relations between platforms and placements. |
post_engagement |
integer
|
|
The total number of actions that people take involving your ad. |
post_labels |
array
|
|
An array of post label ids and names. |
spend |
float
|
|
The estimated total amount of money you've spent on your campaign, ad set or ad during its schedule. |
status |
string
|
|
Ad status. |
video_play_view |
integer
|
|
The number of times that your video started to play. This is counted for each impression of a video, and excludes replays. This metric is in development. |
Clarification of objective
field
Name | Description |
---|---|
APP_INSTALLS | Send people to the shop where they can download your business's app. |
BRAND_AWARENESS | Increase people's awareness of your business, brand or service. |
CONVERSIONS | Encourage people to take a specific action on your business's site, such as having them to add items to a cart, download your app, register for your site, or make a purchase. |
EVENT_RESPONSES | Drive awareness and attendance of a FB event. |
LEAD_GENERATION | Collect leads for your business. Create ads that collect info from people interested in your product, such as sign-ups for newsletters. |
LINK_CLICKS | Drive people from Facebook to any URL you choose, such as your website's landing page, a blog post, app etc. |
LOCAL_AWARENESS | Increase local awareness of your business, brand or service. |
MESSAGES | Connect with people on Facebook, communicate with potential or existing customers to encourage interest in your business. |
MOBILE_APP_ENGAGEMENT | Drive people to app events. |
MOBILE_APP_INSTALLS | Drive people to install your app. |
OFFER_CLAIMS | Such sorts of ads enable advertisers to share coupon codes and discounts with their target audiences. |
OUTCOME_APP_PROMOTION | Find new people to install your app and continue using it. New ODAX objective beneficial for App Installs and App Events. |
OUTCOME_AWARENESS | Show your ads to people who are mostlikely to remember them. New ODAX objective beneficial for Reach, Video views and Brand awareness objective. |
OUTCOME_ENGAGEMENT | Get more video views, post engagement, page likes or event responses. New ODAX objective beneficial for messsages, video views, likes, comments an shares. |
OUTCOME_LEADS | Collect leads for your bussines or brand. New ODAX objective beneficial for instant forms, messages, calls, sign ups. |
OUTCOME_SALES | Find people likely to purchase your product or service. New ODAX objective beneficial for conversions, catalogue sales, messages. |
OUTCOME_TRAFFIC | Send people to a destination, like your website, app or Facebook event. New ODAX objective beneficial for link clicks and landing page views. |
PAGE_LIKES | Drive people from Facebook to like your FB page. |
POST_ENGAGEMENT | Reach people more likely to engage with your post. Engagement includes likes, comments and shares but can also include offers claimed from your Page. |
PRODUCT_CATALOG_SALES | Show products from your e-commerce store's catalogue to generate sales. |
REACH | Show your ad to as many people as possible in your target audience. |
STORE_VISITS | Promote your brick-and-mortar business locations to people that are nearby. |
VIDEO_VIEWS | Share videos of your business with people on Facebook most likely to watch it. |
Clarification of placements
field
Placement | Description | facebook |
instagram |
messenger |
audience_network |
unknown |
---|---|---|---|---|---|---|
all_placements | Messenger: All placements | X | ||||
an_classic | Native, Banner and Interstitial | X | ||||
facebook_groups_feed | Groups feed | X | ||||
facebook_stories | Stories | X | ||||
feed | Feed | X | X | |||
instagram_explore | Explore feed | X | ||||
instagram_igtv | IGTV | X | ||||
instagram_reels | Reels | X | ||||
instagram_stories | Stories | X | ||||
instant_article | Instant articles | X | ||||
instream_video | Instream videos | X | X | |||
marketplace | Marketplace | X | ||||
messenger_inbox | Inbox | X | ||||
messenger_stories | Stories | X | ||||
rewarded_video | Rewarded videos | X | ||||
right_hand_column | Right column | X | ||||
search | Search | X | ||||
unknown | Unknown placement | X | ||||
video_feeds | Video feed | X |
Sort
Basic Fields- clicks
- cost_per_post_engagement
- cpc
- cpm
- ctr
- engagement_rate
- impressions
- inline_link_clicks
- interaction_count
- landing_page_view
- lead
- post_engagement
- spend
- video_play_view
Filter
Field | Allowed values | Description | Advanced filter support |
---|---|---|---|
ad_type | boosted catalog dynamic standard variations |
Ad type. | ✅ Supported operators:
|
country | US GB MX ... More than 240 country codes ... |
Country value is based on results, not targeting. | ✅ Supported operators:
|
objective | APP_INSTALLS BRAND_AWARENESS CONVERSIONS EVENT_RESPONSES LEAD_GENERATION LINK_CLICKS LOCAL_AWARENESS MESSAGES MOBILE_APP_ENGAGEMENT MOBILE_APP_INSTALLS OFFER_CLAIMS OUTCOME_APP_PROMOTION OUTCOME_AWARENESS OUTCOME_ENGAGEMENT OUTCOME_LEADS OUTCOME_SALES OUTCOME_TRAFFIC PAGE_LIKES POST_ENGAGEMENT PRODUCT_CATALOG_SALES REACH STORE_VISITS VIDEO_VIEWS |
Ad objective. | ✅ Supported operators:
|
placements | all_placements an_classic facebook_groups_feed facebook_stories feed instagram_explore instagram_igtv instagram_reels instagram_stories instant_article instream_video marketplace messenger_inbox messenger_stories rewarded_video right_hand_column search video_feeds unknown |
Relations between platforms and placements. | ✅ Supported operators:
|
platform | audience_network facebook instagram messenger |
Publishing Platform of the ad. Audience Network extends Facebook's people-based advertising beyond the Facebook platform. With Audience Network, publishers can make money by showing ads from Facebook advertisers in their apps. | ✅ Supported operators:
|
post_labels | * Pattern: .+ |
An array of post label ids and names. | ✅ Supported operators:
|
Clarification of platform
filter field
Audience Network extends Facebook's people-based advertising beyond the Facebook platform. With Audience Network, publishers can make money by showing ads from Facebook advertisers in their apps.
Response
Name | Description |
---|---|
success | Status of the response. Possible values are true or false . |
data |
object containing the following properties:
|
Example request
POST /3/facebook/ads/posts HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"date_start": "2022-05-01",
"date_end": "2022-06-01",
"ad_accounts": ["827395000927082"],
"ad_campaigns": ["827395000927082#231299220370118"],
"fields": [
"ad_account_name",
"ad_type",
"attachments",
"clicks",
"created_time",
"id",
"impressions",
"message",
"name",
"objective",
"placements",
"post_labels",
"status"
],
"filter": [
{
"field": "placements",
"value": "feed"
},
{
"field": "platform",
"value": ["facebook", "instagram"]
},
{
"match_any": [
{
"field": "ad_type",
"value": ["standard", "boosted"]
}
]
}
],
"sort": {
"field": "impressions",
"order": "desc"
},
"limit": 1
}
Example response
{
"success": true,
"data": {
"posts": [
{
"ad_account_name": "testing API",
"ad_type": "standard",
"attachments": [
{
"type": "photo",
"image_url": "https://www.facebook.com/ads/image/?d=AQJ_jLw7AgR_T22WoqvLBgqASGmfU5crSXqGiPhRULCgln8OCvGulZgOR4iY670vaQIfT6eupw5hg0VUxBZXYz5Lh9wgIwO4R9ZeJ1mDOn6IquIJLpSetQoa0wLV2lOCoG3JJvU_o4PcIGx6Lx00bn_3"
}
],
"clicks": 71,
"created_time": "2022-06-01T08:28:18.000Z",
"id": "23851631725210369",
"impressions": 20735,
"message": "Brace yourself the winter is coming!",
"name": "COM-698 ad",
"objective": "OUTCOME_AWARENESS",
"placements": {
"facebook": [
"feed"
],
"instagram": [
"feed"
]
},
"post_labels": [
{
"id": "1e7948c0abc74d20b2725e9a3303a7a1",
"name": "api test"
}
],
"status": "ACTIVE"
}
]
}
}
Metrics
Parameters
Name | Description |
---|---|
date_start, date_end |
string ,
the beginning / end of the period you want to get the data for in the format YYYY-MM-DD.
The response uses a timezone assigned to a profile in Suite settings of the account.
The last day will be also included in the response.
|
ad_accounts | array of strings. Max. limit is 500 account strings. |
ad_campaigns | array of strings. Max. limit is 500 campaign strings. |
metrics | array of objects. See parameters of the object in table below. |
dimensions | array of objects. The data of the metric can be split by a specific dimension. The most common dimension is time. See the list of available dimensions in the table of metrics below. A maximum of 2 dimensions can be used. See the table of allowed dimension combinations. |
filter | array of objects. You can filter the results using simple or advanced post filters. See the table of fields allowed for filtering. |
Metrics
Parameters
Name | Description |
---|---|
metric | string , table of available metrics is displayed below. |
aggregation | string , specifies aggregation used for calculation of metric results. In table below are default values used for each metric. Not all metrics support multiple aggregation types. |
alias | string , alias for metric name in response header. Also allows querying for same metric with different aggregation. |
Available metrics
The provided results are in USD, for all types of currency metrics.
Name | Dimensions | Aggregation | Metric Description |
---|---|---|---|
impressions | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of times that your ads were on-screen. |
spend | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The estimated total amount of money you've spent on your campaign, ad set or ad during its schedule. This metric is estimated. |
clicks | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of clicks on your ads. |
cpc | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
avg | The average cost for each click (all). |
ctr | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
avg | The percentage of times that people saw your ads and performed a click (all). |
cpm | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
avg | The average cost per 1,000 impressions. |
page_engagement | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The total number of actions that people took on your Facebook Page and its posts, attributed to your ads. |
page_likes | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of likes of your Facebook Page attributed to your ads. |
comment_count | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of comments on your ads. |
post_engagement | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The total number of actions that people take involving your ads. |
like_count | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of reactions on your ads. The reactions button on an ad allows people to share different reactions to its content: like, love, haha, wow, sad or angry. |
interaction_count | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The total number of reactions, comments and shares on your ads. |
reaction_anger | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of anger reactions on your ads. |
reaction_like | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of like reactions on your ads. |
reaction_love | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of love reactions on your ads. |
reaction_haha | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of haha reactions on your ads. |
reaction_wow | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of wow reactions on your ads. |
reaction_sorry | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of sorry reactions on your ads. |
reaction_pride | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of pride reactions on your ads. |
reaction_thankful | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of thankful reactions on your ads. |
reaction_care | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of care reactions on your ads. |
onsite_conversion_post_save | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The total number of times your ads have been saved. This metric is in development. |
share_count | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of shares of your ads. People can share your ads or posts on their own or friends' Timelines, in groups and on their own Pages. |
photo_view | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of views of photos on your Page or posts that are attributed to your ads. Photo views are counted when people click on photos to view them. |
video_view | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of views of videos on your Page or posts that are attributed to your ads. Video views are counted when people click on video to view them. |
rsvp | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of people who responded with Interested or Going to your Facebook event, attributed to your ads. |
checkin | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of check-ins to your Facebook Page that are attributed to your ads. If your Page has a physical address associated with it, people can check in to your Page when they update their status in their Facebook News Feed or Timeline. |
full_view_impressions | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of times that your entire ad was viewed. |
cost_per_page_engagement | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
avg | The average cost for each Page engagement. |
cost_per_page_like | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
avg | The average cost for each Facebook Page like. |
cost_per_post_engagement | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
avg | The average cost for each post engagement. |
cost_per_rsvp | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
avg | The average cost for each event response. |
video_thruplay_watched | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of times that your video was played to completion, or for at least 15 seconds. |
video_p25_watched | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of times your video was played at 25% of its length, including plays that skipped to this point. |
video_p50_watched | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of times your video was played at 50% of its length, including plays that skipped to this point. |
video_p75_watched | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of times your video was played at 75% of its length, including plays that skipped to this point. |
video_p95_watched | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of times your video was played at 95% of its length, including plays that skipped to this point. |
video_p100_watched | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of times your video was played at 100% of its length, including plays that skipped to this point. |
video_avg_time_watched | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
avg | The average time that a video was played for, including any time spent replaying the video for a single impression. |
video_play_view | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of times that your video started to play. This is counted for each impression of a video, and excludes replays. This metric is in development. |
canvas_avg_view_time | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
avg | The average total time, in seconds, that people spent viewing an Instant Experience. An Instant Experience is a screen that opens after someone interacts with your ad on a mobile device. It may include a series of interactive or multimedia components, including a videos, images product catalogue and more. |
canvas_avg_view_percent | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
avg | The average percentage of the Instant Experience that people saw. An Instant Experience is a screen that opens after someone has interacted with your ad on a mobile device. It may include a series of interactive or multimedia components, including a video, images product catalogue and more. |
cost_per_thruplay | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
avg | The average cost of each ThruPlay. |
inline_link_clicks | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of clicks on links within the ad that led to destinations or experiences, on or off Facebook. For ads promoting Instagram profile views, link clicks include clicks on the ad header or comments that led to the advertiser's profile. |
outbound_clicks | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of clicks on links that take people off Facebook-owned properties. |
inline_link_click_ctr | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
avg | The percentage of times people saw your ads and performed a link click. |
outbound_clicks_ctr | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
avg | The percentage of times that people saw your ads and performed an outbound click. |
instant_experience_clicks_to_open | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of clicks on your ads that open an Instant Experience. This metric is in development. |
instant_experience_clicks_to_start | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of times that an interactive component in an Instant Experience starts. This metric is in development. |
instant_experience_outbound_clicks | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of clicks on links in an Instant Experience that take people off Facebook-owned properties. This metric is in development. |
cost_per_inline_link_click | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
avg | The average cost for each link click. |
cost_per_outbound_click | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
avg | The average cost for each outbound click. |
omni_achievement_unlocked | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of unlock achievement events attributed to your ads, based on information received from one or more of your connected Facebook Business Tools. |
add_payment_info | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The addition of customer payment information during a checkout process. For example, a person clicks on a button to save their billing information. |
omni_add_to_cart | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The addition of an item to a shopping cart or basket. For example, clicking an Add to Cart button on a website. |
add_to_wishlist | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The addition of items to a wishlist. For example, clicking an Add to Wishlist button on a website. |
omni_activate_app | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of times your app was activated from mediums attributed to your ads. |
omni_app_install | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of times your app was installed from mediums attributed to your ads. |
omni_initiated_checkout | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of initiate checkout events on mediums attributed to your ads. |
omni_view_content | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of view content events on mediums attributed to your ads. |
omni_spend_credits | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of credit spent on a particular ad. |
app_custom_event | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of Facebook Pixel Custom events. Custom events are actions that fall outside those covered by Facebook standard events (Add to cart, Complete Registration, Contatct, Purchase,..). |
app_engagement | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of desktop app events recorded on mediums attributed to your ads. |
app_story | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of actions related to the desktop app story that were recorded as app events and attributed to your ads. |
app_use | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of uses of your desktop app that were recorded as app events and attributed to your ads. |
games_plays | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of times a game was played that resulted from mediums attributed to your ads. |
landing_page_view | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of times users clicked on your ad link and successfully loaded the intended destination webpage. |
lead | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | A submission of information by a customer with the understanding that they may be contacted at a later date by your business. For example, submitting a form or signing up for a trial. |
omni_level_achieved | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of achieve level events that are tracked by one of your Facebook Business Tools (such as a Facebook pixel, app SDK or offline event set) and attributed to your ads. |
onsite_conversion_flow_complete | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of times a workflow was completed within a Facebook-owned property (such as Pages or Messenger) and attributed to your ads. |
purchase_roas_omni_purchase | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
avg | The total return on ad spend (ROAS) from website purchases. This is based on the value of all conversions recorded by the Facebook pixel on your website and attributed to your ads. |
omni_purchase | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The completion of a purchase, usually signified by receiving order or purchase confirmation, or a transaction receipt. For example, landing on a Thank You or confirmation page. |
omni_rate | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of ratings submitted events on mediums attributed to your ads. |
omni_complete_registration | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of completed registration events on mediums attributed to your ads. |
omni_search | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | A search performed on your website, app or other property. For example, product or travel searches. |
store_visit_with_dwell | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of times users visited your stores from mediums attributed to your ads. This metric is estimated. |
subscribe | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The start of a paid subscription for a product or service you offer. |
omni_tutorial_completion | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
sum | The number of completed tutorial events that are tracked by one of your Facebook Business Tools (such as a Facebook pixel, app SDK or offline event set) and attributed to your ads. |
engagement_rate | ad_account age campaign country date.day date.month date.quarter date.week gender objective placement publisher_platform |
avg | The rate at which your ads receive interactions. |
Dimensions
Parameters
Name | Description |
---|---|
type | string , table of available dimension types and their combinations is displayed below. |
fields (optional) | array of strings. Allow extending response with additional data. See available fields in table below. |
group (optional) | object , can be used to limit and sort the result buckets. See parameters of the object in table below. |
other (optional) | boolean , allows aggregation of result buckets over defined limit into last cumulative result bucket. |
Group parameters
Name | Description |
---|---|
sort | object , can be used to define sorting logic. Consists of parameters key , order and valueIndex . |
sort.key | string , possible values are value , sortIndex , name and field |
sort.order (optional) | string , possible values are desc (default) and asc |
sort.valueIndex (optional) | integer , defines which metric's results will be used for sorting. Starts with 0 for first metric. |
limit | integer , limits number of result buckets in response. Default is 10 . |
Dimension combinations
ad_account | campaign | age | gender | country | objective | placement | publisher_platform | date | |
---|---|---|---|---|---|---|---|---|---|
ad_account | |||||||||
campaign | |||||||||
age | |||||||||
gender | |||||||||
country | |||||||||
objective | |||||||||
placement | |||||||||
publisher_platform | |||||||||
date |
Dimension fields
ad_account_name | campaign_name | |
---|---|---|
ad_account | ||
campaign |
Limits
Dimension Type | Limit |
---|---|
campaign | Max. group.limit is 2000. |
country | Max. group.limit is 250. |
date.day | Max. allowed day interval between request's date_start and date_end is 31 days. |
date.week | Max. allowed day interval between request's date_start and date_end is 365 days. |
campaign + country |
Max. 50 000 possible result buckets is allowed. Multiplication of group.limit for combination of these two dimensions can't be greater than 50 000.
Valid dimensions: [{ type: 'campaign', group: { limit: 1000 }}, { type: 'country', group: { limit: 10 }}]
Invalid dimensions: [{ type: 'campaign', group: { limit: 501 }}, { type: 'country', group: { limit: 100 }}]
|
Clarification of objective
field
Name | Description |
---|---|
APP_INSTALLS | Send people to the shop where they can download your business's app. |
BRAND_AWARENESS | Increase people's awareness of your business, brand or service. |
CONVERSIONS | Encourage people to take a specific action on your business's site, such as having them to add items to a cart, download your app, register for your site, or make a purchase. |
EVENT_RESPONSES | Drive awareness and attendance of a FB event. |
LEAD_GENERATION | Collect leads for your business. Create ads that collect info from people interested in your product, such as sign-ups for newsletters. |
LINK_CLICKS | Drive people from Facebook to any URL you choose, such as your website's landing page, a blog post, app etc. |
LOCAL_AWARENESS | Increase local awareness of your business, brand or service. |
MESSAGES | Connect with people on Facebook, communicate with potential or existing customers to encourage interest in your business. |
MOBILE_APP_ENGAGEMENT | Drive people to app events. |
MOBILE_APP_INSTALLS | Drive people to install your app. |
OFFER_CLAIMS | Such sorts of ads enable advertisers to share coupon codes and discounts with their target audiences. |
OUTCOME_APP_PROMOTION | Find new people to install your app and continue using it. New ODAX objective beneficial for App Installs and App Events. |
OUTCOME_AWARENESS | Show your ads to people who are mostlikely to remember them. New ODAX objective beneficial for Reach, Video views and Brand awareness objective. |
OUTCOME_ENGAGEMENT | Get more video views, post engagement, page likes or event responses. New ODAX objective beneficial for messsages, video views, likes, comments an shares. |
OUTCOME_LEADS | Collect leads for your bussines or brand. New ODAX objective beneficial for instant forms, messages, calls, sign ups. |
OUTCOME_SALES | Find people likely to purchase your product or service. New ODAX objective beneficial for conversions, catalogue sales, messages. |
OUTCOME_TRAFFIC | Send people to a destination, like your website, app or Facebook event. New ODAX objective beneficial for link clicks and landing page views. |
PAGE_LIKES | Drive people from Facebook to like your FB page. |
POST_ENGAGEMENT | Reach people more likely to engage with your post. Engagement includes likes, comments and shares but can also include offers claimed from your Page. |
PRODUCT_CATALOG_SALES | Show products from your e-commerce store's catalogue to generate sales. |
REACH | Show your ad to as many people as possible in your target audience. |
STORE_VISITS | Promote your brick-and-mortar business locations to people that are nearby. |
VIDEO_VIEWS | Share videos of your business with people on Facebook most likely to watch it. |
Filter
Field | Allowed values | Description | Advanced filter support |
---|---|---|---|
age | 13-17 18-24 25-34 35-44 45-54 55-64 65+ |
Age is based on results, not targeting. | ✅ Supported operators:
|
country | US GB MX ... More than 240 country codes ... |
List of codes from ISO 3166-1 alpha-2. | ✅ Supported operators:
|
gender | female male |
Gender is based on results, not targeting. | ✅ Supported operators:
|
objectives | CONVERSIONS LINK_CLICKS APP_INSTALLS REACH POST_ENGAGEMENT PRODUCT_CATALOG_SALES LEAD_GENERATION VIDEO_VIEWS BRAND_AWARENESS PAGE_LIKES STORE_VISITS MESSAGES EVENT_RESPONSES MOBILE_APP_INSTALLS MOBILE_APP_ENGAGEMENT OFFER_CLAIMS OUTCOME_AWARENESS OUTCOME_ENGAGEMENT OUTCOME_LEADS OUTCOME_SALES OUTCOME_TRAFFIC OUTCOME_APP_PROMOTION |
Objectives used within publishing platform. For more details see Clarification of objective fields under FB ads content section. | ✅ Supported operators:
|
placement | feed instagram_stories instagram_explore video_feeds marketplace facebook_stories search instream_video instant_article an_classic right_hand_column messenger_inbox messenger_stories rewarded_video facebook_groups_feed instagram_igtv instagram_reels all_placements |
Ad placement used within publishing platform. For more details see Clarification of placement fields under FB ads content section. | ✅ Supported operators:
|
publisher_platform | facebook instagram audience_network messenger |
Publishing Platform of the ad. Audience Network extends Facebook's people-based advertising beyond the Facebook platform. With Audience Network, publishers can make money by showing ads from Facebook advertisers in their apps. | ✅ Supported operators:
|
Response
Parameters
Name | Description |
---|---|
success | boolean , status of the response. Possible values are true or false . |
header | array of objects. Result format depends on request parameters. |
data | array of arrays. Result format depends on request parameters. |
Dimensions
Dimension | Possible values |
---|---|
ad_account |
* Example: 227555088172XXX
|
campaign |
* Example: 227555088172XXX#23847159232150XXX
|
date |
* Format: YYYY-MM-DD Example: 2021-01-01
|
gender |
female male unknown
|
age |
13-17 18-24 25-34 35-44 45-54 55-64 65+ unknown
|
objective |
CONVERSIONS ‐ Encourage people to take a specific action on your business's site, such as having them to add items to a cart, download your app, register for your site, or make a purchase.LINK_CLICKS ‐ Drive people from Facebook to any URL you choose, such as your website's landing page, a blog post, app etc.APP_INSTALLS ‐ Send people to the shop where they can download your business's app.REACH ‐ Show your ad to as many people as possible in your target audience.POST_ENGAGEMENT ‐ Reach people more likely to engage with your post. Engagement includes likes, comments and shares but can also include offers claimed from your Page.PRODUCT_CATALOG_SALES ‐ Show products from your e-commerce store's catalogue to generate sales.LEAD_GENERATION ‐ Collect leads for your business. Create ads that collect info from people interested in your product, such as sign-ups for newsletters.VIDEO_VIEWS ‐ Share videos of your business with people on Facebook most likely to watch it.BRAND_AWARENESS ‐ Increase people's awareness of your business, brand or service.PAGE_LIKES ‐ Drive people from Facebook to like your FB page. STORE_VISITS ‐ Promote your brick-and-mortar business locations to people that are nearby.MESSAGES ‐ Connect with people on Facebook, communicate with potential or existing customers to encourage interest in your business.EVENT_RESPONSES ‐ Drive awareness and attendance of a FB event.MOBILE_APP_INSTALLS ‐ Drive people to install your app.MOBILE_APP_ENGAGEMENT ‐ Drive people to app events.OFFER_CLAIMS ‐ Such sorts of ads enable advertisers to share coupon codes and discounts with their target audiences.OUTCOME_AWARENESS ‐ Awareness (ODAX)OUTCOME_ENGAGEMENT ‐ Engagement (ODAX)OUTCOME_LEADS ‐ Leads (ODAX)OUTCOME_SALES ‐ Sales (ODAX)OUTCOME_TRAFFIC ‐ Traffic (ODAX)OUTCOME_APP_PROMOTION ‐ App Promotion (ODAX)unknown
|
publisher_platform |
facebook instagram audience_network ‐ Audience Network extends Facebook's people-based advertising beyond the Facebook platform. With Audience Network, publishers can make money by showing ads from Facebook advertisers in their apps.messenger unknown
|
placement |
feed instagram_stories instagram_explore video_feeds marketplace facebook_stories search instream_video instant_article an_classic right_hand_column messenger_inbox messenger_stories rewarded_video facebook_groups_feed instagram_igtv instagram_reels all_placements unknown
|
country |
US GB MX unknown ... More than 240 country codes ... |
Example request
POST /3/facebook/ads/metrics HTTPS
Host: api.emplifi.io
Authorization: Basic base64_encoded_auth
Content-Type: application/json; charset=utf-8
{
"date_start": "2020-01-01",
"date_end": "2021-01-01",
"ad_accounts": ["2233445566778899"],
"filter": [
{
"field": "objectives",
"value": [
"VIDEO_VIEWS",
"REACH"
]
},
{
"match_all": [
{
"field": "age",
"value": [
"13-17",
"18-24",
"25-34",
"35-44"
]
}
]
}
],
"dimensions": [
{
"type": "campaign",
"fields": [
"ad_account_name",
"campaign_name"
],
"group": {
"sort": {
"key": "value",
"order": "asc",
"valueIndex": 0
},
"limit": 3
},
"other": true
},
{
"type": "gender"
}
],
"metrics": [
{
"metric": "clicks"
},
{
"metric": "cpc"
}
]
}
Example response
{
"success": true,
"header": [
{
"type": "campaign",
"rows": [
"2233445566778899#231123222333234423",
"2233445566778899#255525662577258825",
{
"other": {
"length": 11
}
}
],
"fields": [
{
"ad_account_name": "SocialBakers",
"campaign_name": "SocialBakers API"
},
{
"ad_account_name": "SocialBakers",
"campaign_name": "Facebook Ads endpoint"
},
{
"ad_account_name": null,
"campaign_name": null
}
]
},
{
"type": "gender",
"rows": [
"female",
"male",
"unknown"
]
},
{
"type": "metric",
"rows": [
"clicks",
"cpc"
]
}
],
"data": [
[
[
460,
0.49
],
[
317,
0.53
],
[
4,
0.222
]
],
[
[
481,
0.571
],
[
350,
0.736
],
[
4,
0.137
]
],
[
[
30335,
0.228
],
[
19741,
0.275
],
[
65,
0.238
]
]
]
}
Tableau Web Data Connector (Tableau WD Connector)
Tableau is a data visualization tool used to simplify raw data into an easily understandable format, in the form of dashboards and worksheets that feature interactive graphs, tables, and more.
Emplifi Tableau WD Connector allows you to access the Emplifi API and use it as a data source for your Tableau dashboards and worksheets.
Need help connecting Emplifi Tableau WD Connector?
Please visit the Tableau Help center and read this article.
Emplifi Tableau Connector is available at this address: https://api.emplifi.io/tableau-wdc-v3.
In order to log in please use your API credentials (Token/Secret). If you don’t have your own, please check the Security and Authentication section.
The majority of metrics available in the API v3 are also available in Tableau Connector. For more details, please visit our help center.
Looker Studio Connector (previously known as Google Data Studio)
Looker Studio is a tool that converts your analytics data into informative reports and dashboards which are easy to read, share, and customize.
Emplifi Looker Studio Connector allows you to access the Emplifi API and use it as a data source for your reports and dashboards.
Need help connecting Emplifi Looker Studio Connector?
You can find the Emplifi API 3.0 Connector in the Gallery or using this direct link.
In order to authorize access, please use your API credentials (Token = Username / Secret = Token). If you don’t have your own, please check the Security and Authentication section.
The majority of metrics available in the API v3 are also available in Looker Studio. For more details, please visit our help center.
If you are using the previous version of the Connector, please check the API v1 documentation.
Power BI Connector (PBI Connector)
Power BI Desktop allows you to connect, transform, and visualize your data. You can integrate multiple data sources and combine them to build visual representations, gather them in collections, and share them as reports and dashboards.
Emplifi PBI Connector allows you to access the Emplifi API and use it as a data source for your reports and dashboards.
Need help connecting Emplifi to Power BI?
To connect to data in Power BI Desktop, select Get data from the Home ribbon, and search for “Emplifi connector”.
If you need assistance to connect your data, please visit the Power BI Documentation.
To log in, use your API credentials (Token/Secret). If you don’t have your own, check the Security and Authentication section.
The majority of metrics available in the API v3 are also available in Power BI Connector. For more details, please visit our help center.
Changelog
v3.49 (2024/10/16)
/3/community/content/labels
- Added a new endpoint for Community content labelling that can label contents for all networks at once. The endpoint accepts prefixed content IDs and supports all networks available in Community.
v3.48 (2024/10/02)
/3/facebook/metrics
- Breaking change: Removed the following deprecated Facebook page metrics.
- Combination of metric and dimension:
- Metric
insights_fan_adds
+like_source
dimension. - Metric
insights_fan_adds_unique
+like_source
dimension. - Metric
insights_fan_removes_unique
+unlike_source
dimension. - Metric
insights_fans_lifetime
+gender_age
dimension. - Metric
insights_post_reach
+frequency_distribution
dimension. - Metrics:
insights_positive_feedback
insights_post_clicks
insights_reach_engagement
insights_engaged_users
insights_activity
insights_activity_unique
/3/whatsapp/profiles
- Added Whatsapp Profiles (
whatsapp
) as a platform to the list of Connected Profiles /3/community/posts
and/3/community/metrics
- Added Whatsapp Profiles (
whatsapp
) as a platform to Community API
v3.46 (2024/09/04)
/3/facebook/metrics
- Facebook has deprecated several page metrics. (more info here)
- The historical data will be available until January, 2024. After that, the API will return an invalid metric or dimension error.
-
Combination of metric and dimension:
- Metric
insights_reach
+gender_age
dimension. - Metric
insights_reach_28_days
+gender_age
dimension. - Metric
insights_reach_7_days
+gender_age
dimension. - Metric
insights_post_reach
will lose the organic data option in thepost_attribution
dimension. This dimension will be replaced by a standalone metric for paid data in future releases. - Metric
insights_reach
will lose the organic data option in thepost_attribution
dimension. This dimension will be replaced by a standalone metric for paid data in future releases. - Metric
insights_impressions
will lose the organic data option in thepost_attribution
dimension. This dimension will be replaced by a standalone metric for paid data in future releases.
- Metric
-
Metrics:
insights_post_clicks_unique
insights_negative_feedback
insights_fans_online
v3.45 (2024/07/24)
/3/facebook/metrics
- Fixed
insights_fans_lifetime
metric to return more accurate value /3/googlebp/profiles
- Added Google Business Profiles (
googlebp
) as a platform to the list of Connected Profiles /3/community/posts
and/3/community/metrics
- Added Google Business Profiles (
googlebp
) as a platform to Community API /3/instagram/profile/posts
- Fixed missing
post_attribution
field.
v3.44 (2024/06/26)
/3/instagram/profile/posts
- New metric added for Instagram Reels:
insights_initial_video_views
/3/aggregated-metrics
- New metric added for Instagram Reels:
insights_initial_video_views
- Profiles from irrelevant networks no longer returned in response
v3.43 (2024/03/27)
/3/facebook/metrics
- Fixed support to historical data for deprecated Facebook metric + dimension combinations:
- Dimension
like_source
+insights_fan_adds
metric. - Dimension
like_source
+insights_fan_adds_unique
metric. - Dimension
unlike_source
+insights_fans_lifetime
metric. - Dimension
gender_age
+insights_fan_adds
metric. - Dimension
frequency_distribution
+insights_post_reach
metric.
v3.42 (2024/03/12)
/3/community/posts
- Fixes an error when requesting posts for platforms not available in Community. The list of supported platforms stays:
facebook
instagram
linkedin
tiktok
twitter
youtube
/2/facebook/page/posts
- Facebook has updated deprecation list for post metrics. (more info here).
- The historical data will be available until June 11, 2024. After that, the API will return an invalid metric or dimension error.
- No longer deprecated metrics:
insights_interactions
insights_interactions_by_interaction_type
v3.41 (2024/03/07)
/3/facebook/metrics
/3/facebook/page/posts
- Facebook has updated deprecation list for several page and post metrics. (more info here).
- The historical data will be available until June 11, 2024. After that, the API will return an invalid metric or dimension error.
- No longer deprecated metrics:
insights_reactions
- Additional deprecated metrics:
insights_activity
insights_activity_unique
insights_interactions
insights_interactions_by_interaction_type
v3.40 (2024/02/28)
/3/facebook/metrics
- Facebook has deprecated several page metrics. (more info here).
- The historical data will be available until June 11, 2024. After that, the API will return an invalid metric or dimension error.
- Combination of dimension and metric:
- Dimension
like_source
+insights_fan_adds
metric. - Dimension
like_source
+insights_fan_adds_unique
metric. - Dimension
unlike_source
+insights_fans_lifetime
metric. - Dimension
gender_age
+insights_fan_adds
metric. - Dimension
frequency_distribution
+insights_post_reach
metric. - Metrics:
insights_positive_feedback
insights_post_clicks
insights_reach_engagement
insights_engaged_users
insights_reactions
v3.39 (2024/02/14)
-
New metrics
salesforce_case_count
,salesforce_lead_count
added to/3/community/metrics
.
v3.38 (2023/11/28)
-
Breaking change: Facebook has deprecated
audience_locale
metric (more info here). Alternative metric is N/A. Make sure to update your reports accordingly. -
Affected metrics
locale
can no longer be used as a dimension for the following metric:-
insights_followers
-
-
Affected endpoints
v3.37 (2023/09/20)
-
/3/pinterest/profile/posts
-
Additional metrics have been added to Pinterest pins -
insights_avg_time_watched
,insights_engagements
,insights_impressions
,insights_impressions_engagement_rate
,insights_link_clicks
,insights_post_clicks
,insights_post_saves
,insights_reactions
,insights_save_rate
,insights_video_completed_views
,insights_video_starts
,insights_video_views
,insights_video_views_10s
,insights_view_time
.
-
Additional metrics have been added to Pinterest pins -
-
/3/aggregated-metrics
-
Metrics now support new Pinterest data -
insights_avg_time_watched
,insights_engagements
,insights_impressions
,insights_impressions_engagement_rate
,insights_post_clicks
,insights_post_saves
,insights_video_views
,insights_view_time
,likes
. -
New metrics added:
insights_link_clicks
insights_save_rate
insights_video_completed_views
insights_video_views_10s
insights_video_starts
-
Metrics now support new Pinterest data -
-
Breaking change: Removed
shares
metric from Pinterest pins. Pinterest no longer provides a Shares metric. A similar alternative would be theinsights_post_saves
metric which tracks the number of times people saved your Pin to a board. Affected Endpoints:
v3.36 (2023/08/07)
-
/3/aggregated-metrics
and/3/tiktok/profile/posts
now support for TikTok:insights_impressions
v3.35 (2023/08/24)
-
Pinterest data is now available exclusively for insights connected profiles. Affected endpoints:
v3.34 (2023/07/27)
-
/3/{network}/profiles
- Now supports Snapchat profiles under
/3/snapchat/profiles
- Now supports Snapchat profiles under
-
/3/snapchat/profile/posts
- New endpoint Snapchat post metrics
-
/3/aggregated-metrics
- Added
snap
ascontent_type
filter option. - Metrics
page_posts
,number_of_comments
,insights_video_views
,insights_engagements
,insights_media_views
,insights_reach_per_content
,insights_reach_engagement
,insights_avg_time_watched
,insights_impressions
,insights_impressions_engagement_rate
andinsights_view_time
now support Snapchat Insights data. -
New metrics available for Snapchat:
insights_swipe_up
insights_swipe_down
insights_screenshots
insights_media_view_time
- Added
v3.33 (2023/06/29)
-
/3/aggregated-metrics
supports filtering byprofile_labels
,platform
,content_type
andmedia_type
fields. See list of fields available for filtering.
v3.32 (2023/06/01)
-
Facebook Reels data is available and supported under dimension media_type='reel'. Affected endpoints:
v3.31 (2023/05/04)
-
/3/facebook/page/posts
-
Fixed response values format for the
insights_video_views_complete_unique_by_post_attribution
field.
-
Fixed response values format for the
-
/3/tiktok/profile/posts
-
Fixed response value format for the
media
field.
-
Fixed response value format for the
v3.30 (2023/04/06)
-
/3/linkedin/profile/posts
- Fixed behavior of LinkedIn posts when requesting the data with an expired insights - it returns empty data now as other platforms.
v3.29 (2023/03/22)
-
/3/tiktok/profile/posts
-
Added
authorId
andauthor
fields.
-
Added
v3.28 (2023/03/08)
-
/3/instagram/profile/posts
-
Added
origin
field and filter. - Fixed issue when both user generated content and brand generated content were returned.
-
Added
v3.27 (2023/02/09)
-
Added new dimension and filter
media_type
to Listening metrics endpoint.
v3.26 (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 /3/aggregated-metrics
will no longer returnvideo_igtv
as a separate bucket ofmedia_type
breakdown. Instead, it will include the results in thevideo
bucket. -
POST /3/instagram/profile/posts
will return content withmedia_type=video
instead ofmedia_type=video_igtv
which now also includes thevideo_igtv
content. All previous requests with filtermedia_type=video_igtv
will be automatically converted tomedia_type=video
so no changes on your end are necessary.
-
-
Endpoint
GET /3/tiktok/profiles
now returns alsocommunity_enabled
flag.
v3.25 (2022/11/23)
-
Fixed the incorrect Facebook Ads metrics metric
page_like
to bepage_likes
for The number of likes of your Facebook Page attributed to your ads. - Rename Google Data Studio Connector to Looker Studio Connector.
v3.24 (2022/10/26)
-
Socialbakers API is now Emplifi API.
Read below for the list of changes that may affect you:- The Emplifi API documentation is now located on https://api.emplifi.io/. https://api.socialbakers.com/ automatically redirects here
- All API calls should be sent to new hostname
api.emplifi.io
- For security reasons API calls to
api.socialbakers.com
are not going to be automatically redirected 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
-
/3/community/metrics
- Added new metric
response_time_business_hours
. This metric is a replacement for metric parameteroptions
in future major versions of API.
- Added new metric
v3.23 (2022/09/14)
-
/3/ads/accounts
- New endpoint List of Ad Accounts
-
/3/community/metrics
- Added support for TikTok profiles
v3.22 (2022/08/04)
- Instagram Reels data is available and supported under dimension media_type='reel'. Affected endpoints:
v3.21 (2022/07/21)
-
/3/facebook/ads/posts
- New endpoint Facebook Ads content
v3.20 (2022/07/12)
-
LinkedIn Insights are now supported
-
/3/linkedin/metrics
- Added profile metrics for LinkedIn -
insights_post_clicks
,insights_engagements
,insights_impressions
,insights_reach
,insights_reach_engagement_rate
,insights_impressions_engagement_rate
. - Requesting insights data with a profile without insights access will result in an error with code 7.
- Added profile metrics for LinkedIn -
-
/3/linkedin/profile/posts
- Additional metrics have been added to LinkedIn posts -
insights_comments
,insights_reactions
,insights_clicks
,insights_engagements
,insights_content_impressions
,insights_video_views
,insights_view_time
,insights_video_views_unique
,insights_impressions_engagement_rate
.
- Additional metrics have been added to LinkedIn posts -
-
/3/aggregated-metrics
- Metrics now supporting new LinkedIn data -
insights_engagements
,insights_impressions
,insights_video_views
,insights_view_time
,insights_impressions_engagement_rate
,likes
. -
New metrics added:
insights_post_clicks
insights_video_views_unique
- Metrics now supporting new LinkedIn data -
-
v3.19 (2022/06/27)
-
/3/tiktok/metrics
- New endpoint TikTok metrics
- Requesting insights data with a profile without insights access will result in an error with code 7.
-
/3/{network}/profiles
- Now supports TikTok profiles under
/3/tiktok/profiles
- Now supports TikTok profiles under
-
/3/tiktok/profile/posts
- New endpoint TikTok post metrics
-
/3/aggregated-metrics
- Metrics
page_posts
,insights_video_views
,number_of_comments
,insights_reach_per_content
,insights_reach_engagement
,insights_engagements
,insights_avg_time_watched
,insights_view_time
andinsights_completion_rate
now support TikTok Insights data.
- Metrics
v3.18 (2022/06/27)
-
/3/listening/posts
- New endpoint Listening Content
-
/3/listening/metrics
- New endpoint Listening Metrics
-
/3/community/posts
- Added
listening_queries
parameter to Community Content endpoint
- Added
-
/3/community/metrics
- Added
listening_queries
parameter to Community Metrics endpoint
- Added
v3.17 (2022/06/09)
-
New metric
engagement_rate
added to Facebook Ads endpoint. -
Added a new field
status
to the List of Listening Queries endpoint.
v3.16 (2022/05/11)
-
Added Facebook ODAX objectives to Facebook Ads endpoint.
ODAX stands for Outcome-driven ad experience. Objectives marked with ODAX reflect Facebook's new, simplified campaign objectives mapped to broader marketing goals.
v3.15 (2022/04/27)
- LinkedIn organic metrics now require connected LinkedIn Insights data connection instead of Publishing in order to return data
v3.14 (2022/04/20)
-
Vkontakte data is no longer supported under
-
/3/aggregated-metrics
-
/3/vkontakte/profile/posts
-
- List of connected profiles no longer returns VK profiles
v3.13 (2022/04/20)
-
/3/listening/queries
- New endpoint List of Listening Queries
v3.12 (2022/02/16)
-
YouTube metrics have been updated to reflect the change of Dislikes count availability introduced by YouTube in December 13, 2021 Learn more. Affected are:
-
/3/youtube/metrics
interaction_change, interactions_per_1k_fans
-
/3/youtube/profile/videos
dislikes, interactions, interactions_per_1k_fans
-
/3/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.
v3.11 (2022/01/20)
- Aggregated post metrics endpoint /3/aggregated-metrics now returns data sorted by value descending
- Added a new Community Metrics endpoint
- Added a new Community Content endpoint
v3.10 (2021/10/05)
/3/facebook/page/posts
insights_engagements
- new field for Engagements added. Learn more.insights_reach_engagement_rate
- calculation for this metrics has been upgraded. Learn More. The previous metric was resulting from Engaged Users divided by Reach.insights_impressions_engagement_rate
- new field for Impressions ER added. Learn more./3/instagram/profile/posts
insights_engagement
- calculation for Engagements was upgraded. It now includes also Story Replies. Learn more.insights_reach_engagement_rate
- new field for Reach ER. Learn more.insights_impressions_engagement_rate
- new field for Impressions ER added. Learn more./3/youtube/profile/videos
insights_engagement
- new field for Engagements added. Learn more./3/aggregated-metrics
insights_engagements
- YT Engagements is now supported under this field. Calculation for Facebook and Instagram engagements has been upgraded. Learn Moreinsights_reach_engagement
- IG Reach ER is now supported under this field. Calculation for Facebook has been upgraded. Learn Moreinsights_impressions_engagement_rate
- new field for Impressions ER added. Learn more.
v3.9 (2021/09/17)
- IGTV data is available and supported under dimension
media_type='video_igtv'
Affected endpoints:
v3.8 (2021/08/23)
insights_video_views
metric is now returning data also for Instagram Carousels with videosv3.7 (2021/07/13)
v3.6 (2021/07/13)
v3.5 (2021/02/04)
v3.4.1 (2021/01/25)
v3.4 (2021/01/07)
v3.3 (2020/12/14)
v3.2 (2020/11/26)
- Added 2 new Facebook Post Metrics:
insights_video_view_time_by_country
andinsights_video_view_time_by_gender_age
- Introduced new Assets API to manage collections and assets
- Redesigned the API documentation
v3.1 (2020/10/29)
- Removed name and url from the profile field in Twitter Post Metrics
- Removed created time from Twitter Post Metrics as it is against the Twitter Developer Policy
v3.0 (2020/09/16)
- Content labels and Profile labels endpoints are now GET method instead of POST
- Added new metrics and properties for Post Metrics
- Added LinkedIn, Pinterest and VKontakte support for Post Metrics
- Aggregated Post Metrics now filters out spam and deleted posts
v2.22 (2024/10/02)
/2/facebook/metrics
- Breaking change: Removed the following deprecated Facebook page metrics.
- Combination of metric and dimension:
- Metric
insights_fan_adds
+like_source
dimension. - Metric
insights_fan_adds_unique
+like_source
dimension. - Metric
insights_fan_removes_unique
+unlike_source
dimension. - Metric
insights_fans_lifetime
+gender_age
dimension. - Metric
insights_post_reach
+frequency_distribution
dimension. - Metrics:
insights_positive_feedback
insights_post_clicks
insights_reach_engagement
insights_engaged_users
insights_activity
insights_activity_unique
/2/facebook/page/posts
- Breaking change: Removed the following deprecated Facebook post metric:
insights_impressions_fan_paid
v2.21 (2024/09/04)
/2/facebook/metrics
- Facebook has deprecated several page metrics. (more info here)
- The historical data will be available until January, 2024. After that, the API will return an invalid metric or dimension error.
-
Combination of metric and dimension:
- Metric
insights_reach
+gender_age
dimension. - Metric
insights_reach_28_days
+gender_age
dimension. - Metric
insights_reach_7_days
+gender_age
dimension. - Metric
insights_post_reach
will lose the organic data option in thepost_attribution
dimension. This dimension will be replaced by a standalone metric for paid data in future releases. - Metric
insights_reach
will lose the organic data option in thepost_attribution
dimension. This dimension will be replaced by a standalone metric for paid data in future releases. - Metric
insights_impressions
will lose the organic data option in thepost_attribution
dimension. This dimension will be replaced by a standalone metric for paid data in future releases.
- Metric
-
Metrics:
insights_post_clicks_unique
insights_negative_feedback
insights_fans_online
v2.20 (2024/07/24)
/2/facebook/metrics
- Fixed
insights_fans_lifetime
metric to return more accurate value
v2.19 (2024/06/26)
/3/aggregated-metrics
- Profiles from irrelevant networks no longer returned in response
v2.18 (2024/05/01)
/2/facebook/page/posts
- Facebook has updated deprecation list for several page and post metrics. (more info here).
- The historical data will be available until June 11, 2024. After that, the API will return an invalid metric or dimension error.
- Deprecated metrics:
insights_impressions_fan_paid
v2.17 (2024/03/27)
/2/facebook/metrics
- Fixed support to historical data for deprecated Facebook metric + dimension combinations:
- Dimension
like_source
+insights_fan_adds
metric. - Dimension
like_source
+insights_fan_adds_unique
metric. - Dimension
unlike_source
+insights_fans_lifetime
metric. - Dimension
gender_age
+insights_fan_adds
metric. - Dimension
frequency_distribution
+insights_post_reach
metric.
v2.16 (2024/03/07)
/2/facebook/metrics
/2/facebook/page/posts
- Facebook has updated deprecation list for several page and post metrics. (more info here).
- The historical data will be available until June 11, 2024. After that, the API will return an invalid metric or dimension error.
- No longer deprecated metrics:
insights_reactions
- Additional deprecated metrics:
insights_activity
insights_activity_unique
v2.15 (2024/02/28)
/2/facebook/metrics
- Facebook has deprecated several page metrics. (more info here).
- The historical data will be available until June 11, 2024. After that, the API will return an invalid metric or dimension error.
- Combination of dimension and metric:
- Dimension
like_source
+insights_fan_adds
metric. - Dimension
like_source
+insights_fan_adds_unique
metric. - Dimension
unlike_source
+insights_fans_lifetime
metric. - Dimension
gender_age
+insights_fan_adds
metric. - Dimension
frequency_distribution
+insights_post_reach
metric. - Metrics:
insights_positive_feedback
insights_post_clicks
insights_reach_engagement
insights_engaged_users
insights_reactions
v2.13 (2023/08/24)
-
Pinterest data is now available exclusively for insights connected profiles. Affected endpoints:
v2.12 (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 /2/aggregated-metrics
will no longer returnvideo_igtv
as a separate bucket ofmedia_type
breakdown. Instead, it will include the results in thevideo
bucket.
-
v2.11 (2022/10/26)
-
Socialbakers API is now Emplifi API.
Read below for the list of changes that may affect you:- The Emplifi API documentation is now located on https://api.emplifi.io/. https://api.socialbakers.com/ automatically redirects here
- All API calls should be sent to new hostname
api.emplifi.io
- For security reasons API calls to
api.socialbakers.com
are not going to be automatically redirected 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
v2.10
- Instagram Reels data is available and supported under dimension media_type='reel'. Affected endpoints:
v2.9
- LinkedIn organic metrics now require connected LinkedIn Insights data connection instead of Publishing in order to return data
v2.8
- Vkontakte data is no longer supported under
- List of connected profiles no longer returns VK profiles
v2.7
-
YouTube metrics have been updated to reflect the change of Dislikes count availability introduced by YouTube in December 13, 2021 Learn more. Affected are:
-
/2/youtube/metrics
interaction_change, interactions_per_1k_fans
-
/2/youtube/profile/videos
dislikes, engagement_rate, interactions
-
/2/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.
v2.6
- Aggregated post metrics endpoint /2/aggregated-metrics now returns data sorted by value descending
v2.5
- Tableau WDC connector v1 is no longer supported, please use latest version.
v2.4
/2/facebook/page/posts
insights_engagement_rate
- no longer supported. We have introduced a new version of the Reach ER in the latest version of the API. This field will still be return for the time being./2/instagram/profile/posts
insights_engagement
- no longer supported. We have introduced a new version of the Engagements in the latest version of the API. This field will still be return for the time being./2/aggregated-metrics
insights_engagement
- YT Engagements is now supported under this field. Calculation for Facebook and Instagram engagements has been upgraded. Learn Moreinsights_reach_engagement
- IG Reach ER is now supported under this field. Calculation for Facebook has been upgraded. Learn More
v2.3
- IGTV data is available and supported under dimension
media_type='video_igtv'
Affected endpoints:
v2.2
insights_video_views
metric is now returning data also for Instagram Carousels with videosv2.1
- 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:
v2.0
- Added get connected profiles support for LinkedIn and Vkontakte.
- Introduced new Profile level metrics with dimension support.
- Added Profile level metrics for LinkedIn.
- Facebook Post Metrics endpoint within the Aggregated Post Metric is removed.
v1.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 |