Sprout API

Sprout API Overview

The Sprout API provides an externally accessible API for you to access your owned social profile data so you can use that data to power dashboards and automate your reporting.

Available Data Overview

✅  The Sprout API includes:

• ✅  Owned Profile Data - This matches the data available in Sprout’s Profile Performance, Twitter Profiles, Facebook Pages, Instagram Business Profiles, LinkedIn Pages, Pinterest Profiles, TikTok Profiles and YouTube Videos Report.
• ✅  Post Data - This matches the data available in Sprout’s Post Performance Report.
• ✅  Owned demographic data - View the data available in Sprout’s Facebook Pages, Instagram Business Profiles, LinkedIn Pages, and TikTok Profiles Report
• ✅  Message Data - Get detailed information, including metadata, about your messages. This includes messages received by and replied to from your profiles.
• ✅  Direct Tableau Connector - Easily analyze Sprout API data directly in Tableau. For more details reference the Tableau Connector section of this doc.
• ✅  Listening Topics - Retrieve earned media related metrics and messages found within your Listening Topics. For more details reference sections regarding Topics within this doc.

For specific data and metrics, reference the Metrics & Fields sections of this doc.

🚫  The Sprout API does not currently include:

• 🚫  Paid (Ad Account) data
• 🚫  Publishing data or capabilities
• 🚫  Listening data from X/Twitter

Access Requirements & Authentication

Before accessing the API, your account must be provisioned for API use by your Sprout account representative. Once the account is provisioned, you must obtain an access token. To do so, follow the steps in the Creating an access token as an Account Owner section. The Account Owner can create new access tokens via the dialog, view existing access tokens or invalidate existing tokens (i.e. prevent the tokens from being used for client requests).

Terminology

• Post: A post refers to a message that was published by an owned profile.
• Message: A message refers to any message that was published by or received by an owned profile or Topic. All posts are messages, but not all messages are posts.
• Profile: A profile refers to an account, page, handle, etc. on a native social network, like Twitter or Instagram.

Creating an access token as an Account Owner

1. Log in to Sprout and navigate to Settings.
2. Scroll down to the reporting section and click API Tokens.

3. Accept Sprout’s Analytics API Terms of Service if you haven’t already.
4. Click Create API Token in the upper left corner.

5. Enter a name for your token.

6. Copy the token for use. Be sure to store this securely.

Twitter Data: Twitter Content End User License Agreement

Note: Twitter has additional review and compliance requirements around exposing data through the API. You’re required to undergo a brief review and approval process before you can access Twitter's data through the Sprout API.

Contact your Sprout Social account representative to initiate the review process with Twitter. After Twitter approves your use case, the Account Owner needs to accept the Analytics API Twitter Content End User License Agreement. This appears at the top of the API Tokens settings page.

Sprout API Details

API URL

https://api.sproutsocial.com

Endpoints Overview

Sprout API endpoints are grouped into three collections:

1. Customer Metadata Endpoints - Use these endpoints to obtain high-level information about your Sprout customer account and profiles you have access to; many of these endpoints provide data needed to make requests to other Sprout API endpoints.
2. Analytics Endpoints - These endpoints provide information about your Sprout profiles, and posts.
3. Listening Endpoints - These endpoints provide metrics and messages related to your Listening Topics.
4. Messages Endpoint - This endpoint provides detailed data and metadata about your Sprout messages.

Customer Metadata Endpoints	Description
GET /v1/metadata/client	Customer ID
GET /v1/<customer ID>/metadata/customer	Customer Profiles
GET /v1/<customer ID>/metadata/customer/tags	Customer Tags
GET /v1/<customer ID>/metadata/customer/groups	Customer Groups
GET /v1/<customer ID>/metadata/customer/users	Customer Users
GET /v1/<customer ID>/metadata/customer/topics	Customer Topics

Analytics Endpoints	Description
POST /v1/<customer ID>/analytics/profiles	Owned Profile Analytics
POST /v1/<customer ID>/analytics/posts	Post Analytics

Listening Endpoints	Description
POST /v1/<customer ID>/listening/topics/<topic id>/messages	Topic Messages
POST /v1/<customer ID>/listening/topics/<topic id>/metrics	Topic Metrics

Messages Endpoint	Description
POST /v1/<customer ID>/messages	Inbox Messages

General API Structure

All endpoints use the following naming structure:

/<version>/<customer ID>/<endpoint path>

Where:

• version is the API major version number
• customer ID is your Sprout customer ID

Versioning

The Sprout API is versioned using a MAJOR.MINOR version format.

You can specify only the major number in requests, but the full version is included in responses.

A major version represents a breaking change to the API, including updates to the syntax and semantics for making requests of the APIs and the syntax and semantics of the response of the API.

A minor version represents a backwards compatible change to the API, such as adding new metrics, new endpoints, metric updates, etc. Minor versions are reflected in documentation, but not the API URL itself. Due to the backwards compatibility of minor versions, you only need to specify the major version in the URL path.

Rate Limits

You’re limited to the following number of requests:

• 60 requests per minute
• 250,000 requests per month

Endpoints

Requests

All requests have the following format:

Request Headers

Type	Value
Authorization	Bearer <API access token>
Accept	application/json
Content-Type	application/json

Request Body

The content body for all requests are JSON objects. Details of the structure of that JSON object depend on the endpoint.

Responses

HTTP Status Codes

The following HTTP status codes returned with the response have the following meanings:

Code	Meaning	Corrective Action
200 OK	Request was processed successfully.	None. You should be able to access the result of the request in the response body.
400 Bad Request	The request is malformed and does not conform with the request bodies specified in this document.	Update the request body.
401 Unauthorized	The request does not contain a valid access token or that access token has expired.	Reauthenticate and obtain a fresh token.
403 Forbidden	The request is accessing customer or profile data that the client is not allowed access to.	Update the request body.
404 Not Found	The client is requesting an endpoint that does not exist.	Check your endpoint, and use an existing endpoint.
405 Method Not Allowed	The client is using an HTTP verb that is not appropriate.	Use the HTTP verb listed for the API endpoint you’re using, typically POST or GET. See the specific endpoint documentation for details.
415 Unsupported Media Type	The client has submitted a request body that is not JSON or is requesting a response that is not JSON	Correct the Accept and Content-Type headers to use JSON.
429 Too Many Requests	The client is making requests too quickly or has exhausted the allowed requests in a month.	Slow down your requests.
500 Internal Server Error	The server had an issue processing the request.	Retry the request. If this code persists, contact support.
503 Service Unavailable	The server is overloaded and cannot process the request.	Retry the request. If this code persists, contact support.
504 Gateway Timeout	The server was unable to produce a result in time.	Retry the request. If this code persists, contact support or decrease the scope of the request (smaller date ranges, less profiles, etc.).

Response Headers

The following headers are returned with each response:

Header	Description	Sample Value
X-Sprout-Request-ID	Randomly generated UUID to trace a client request and response. Returned to you for debugging.	bedc387d-9b99-42ae-9887-cc15f9885d47
X-Sprout-API-Version	Major and minor version of the response	1.1
X-Sprout-Server-Version	Server version, including the major, minor, and build number. The major and minor version reflect the latest available version of the API.	1.1.3018

Response Body

Responses from the data API are JSON objects with the following format:

Key	Value
data	JSON array containing the results of the API request (JSON objects for each message, dimensioned data, etc.)
paging	Optional JSON object describing the status of paging the data returned in the response.
error	Optional JSON string containing an error message in the event there is an issue with the request.

Customer Metadata Endpoints

Customer Metadata endpoints are all HTTP GET endpoints. Use these to obtain information about the customer and profiles you have access to.

Client (Customer ID) Endpoint

GET /v1/metadata/client

This endpoint is used to obtain the customer ID you have access to.

Request Body - Client (Customer ID) Endpoint

No request body is necessary for this request.

Response Data - Client (Customer ID) Endpoint

The data array contains JSON objects of customer IDs you have access to. For example:

{
  "data": [
    {"customer_id": 687751}
  ]
}

Customer Profiles Endpoint

GET /v1/<customer ID>/metadata/customer

This endpoint is used to obtain the list of customer profile IDs you have access to.

Request Body - Customer Profiles Endpoint

No request body is necessary for this request.

Response Data - Customer Profiles Endpoint

The data array contains an array of JSON objects describing the social network profiles that are available to that client. The JSON object contains:

Key	Description	Example Value
customer_profile_id	The customer profile ID used by Sprout to identify this social network profile.	492
network_type	The type of social network (Twitter, Facebook, Instagram, etc.)	twitter
name	The human-facing name of the social network profile	Sprout Social
native_name	The user name, screen name, page URL, etc. the social network uses to identify a unique profile.	sproutsocial
native_id	The ID used by the social network to identify a unique profile.	42793960
groups	An array of group IDs this profile belongs to.	[23598, 65245]

An example response:

{
  "data": [
      {
        "customer_profile_id": 492,
        "network_type": "twitter",
        "name": "Sprout Social",
        "native_name": "sproutsocial",
        "native_id": "42793960"
      },
      ...
  ]
}

Customer Tags Endpoint

GET /v1/<customer ID>/metadata/customer/tags

This endpoint is used to obtain the list of message tags you created in Sprout. The response includes all active and archived tags, regardless of when the tag was created. Previously deleted tags are permanently removed from Sprout and are not included.

Request Body - Customer Tags Endpoint

No request body is necessary for this request.

Response Data - Customer Tags Endpoint

The data array contains an array of JSON objects describing the tags that are available. This includes all tags in a single response. There is no limit or pagination in the response. The JSON object contains:

Key	Description	Example Value
tag_id	The ID used by Sprout to identify this message tag	321
any_group	Whether or not this tag is available in any customer group	false
active	Whether this tag is active (or archived) in Sprout Social	true
text	The text of the tag	"Social Support"
type	The type of the tag (LABEL or CAMPAIGN)	"LABEL"
groups	An array of the IDs of the groups this tag is available in	[206063]

An example response:

{
  "data": [
      {
        "tag_id": 321,
        "any_group": false,
        "active": true,
        "text": "Social Support",
        "type": "LABEL",
        "groups": [206063]
      },
      ...
  ]
}

Customer Groups Endpoint

GET /v1/<customer ID>/metadata/customer/groups

This endpoint is used to obtain the list of groups you created in Sprout.

Request Body - Customer Groups Endpoint

No request body is necessary for this request.

Response Data - Customer Groups Endpoint

The data array contains an array of JSON objects describing the groups that are available to you. The JSON object contains:

Key	Description	Example Value
group_id	The ID used by Sprout to identify this group	1234
name	The name of the group	"Sprout Social Team"

An example response:

{
  "data": [
      {
        "group_id": 1234,
        "name": "Sprout Social Team"
      },
      ...
  ]
}

Customer Users Endpoint

GET /v1/<customer ID>/metadata/customer/users

This endpoint is used to obtain the list of users that are active for your customer.

Request Body - Customer Groups Endpoint

No request body is necessary for this request.

Response Data - Customer Groups Endpoint

The data array contains an array of JSON objects describing the active users for your customer. The JSON object contains:

Key	Description	Example Value
id	The ID used by Sprout to identify this user	1234
name	The name of the user	"John Doe"

An example response:

{
  "data": [
      {
        "id": 1234,
        "name": "John Doe"
      },
      ...
  ]
}

Customer Topics Endpoint

GET /v1/<customer ID>/metadata/customer/topics

Utilize this endpoint to find all Topics associated with your customer id. Each Topic includes associated metadata such as themes and available date ranges.

Request Body - Customer Topics Endpoint

No request body is necessary for this request.

Response Data - Customer Topics Endpoint

The data array contains an array of JSON objects describing the Topics that are available to the client. The JSON object contains:

Key	Description	Example Value
id	An identifier for the Topic used to make calls for Topic data	81391723128379
name	The name of the Topic	Sprout Social Brand
topic_type	The Topic category	BRAND_HEALTH
description	A description given by the user when creating the Topic	A Topic for the brand.
group_id	The group the Topic belongs to	123456789
theme_groups	The list of themes belonging to the Topic. Themes are always grouped even when they may not appear that way in app.	[{"name":"Complaints","themes":[{"id":"018085b6-1dc3-43eb-ab28-3c430c0d2412","name":"SlowLogin"}]}]
theme_groups.name	The name of the theme group	Complaints
theme_groups.themes	The themes that belong to the group	[{"id":"018085b6-1dc3-43eb-ab28-3c430c0d2412","name":"SlowLogin"}]
theme_groups.themes.id	The unique ID of the theme	018085b6-1dc3-43eb-ab28-3c430c0d2412
theme_groups.themes.name	The name for the theme	SlowLogin
availability_time	A date representing how far back data is available for the Topic	2020-11-17T09:32:00Z

An example response:

[
 {
   "id": "81391723128379",
   "description": "",
   "group_id": 1330748,
   "theme_groups": [
     {
       "name": "Complaints",
       "themes": [ 
        {
         "id": "018085b6-1dc3-43eb-ab28-3c430c0d2412",
         "name": "Login Errors"
        }
       ],
     }
   ],
   "availability_time": 1600895454244,
   "topic_type": "INDUSTRY_INSIGHTS",
   "name": "Sprout Social Brand"
 }
]

Analytics Endpoints

Analytics endpoints are all HTTP POST endpoints. They provide access to your owned profile and post analytics data, including:

• Profile Analytics - profile activity broken down by day
• Post Analytics - message content, metadata and lifetime activity metrics

Overview

All requests to and responses from Analytics API endpoints have a similar structure.

Requests - Analytics Endpoints

The request body for an analytics API request is a JSON object with the following name/values pairs:

Key	Description	Example Value
filters	Detailed filters used to filter the results by customer_profile_id, reporting_period (for Profile metrics) and message created_time (for Posts endpoint).	Profile Endpoint: ["customer_profile_id.eq(1234, 5678)", "reporting_period.in(2018-01-01...2018-02-01)"] Posts Endpoint: ["customer_profile_id.eq(1234, 5678)", "created_time.in(2018-01-01...2018-02-01)"]
metrics	List of metrics to return in results; refer to the metrics section for post and profile metrics available for each social network type	["impressions", "likes"]
page (optional)	In paginated results, which 1-indexed page to return in the response. Pagination is based on default limits of 1000 results for the Profiles endpoint and 50 results for the Posts endpoint	3
limit (optional)	Specifies the max number of results per page in the response. Defaults to 1000 results for the Profiles endpoint and 50 results for the Posts endpoint.	100
sort (optional)	(Posts endpoint only) Sets the sort order for results, specified as a list of fields and directions (asc or desc) in the format <field>:<direction>.	["created_time:asc"]
timezone (optional)	(Posts endpoint only) Time zone—from the ICANN time zone database. Timezone arguments only impact date/time-related filters, responses are not impacted and are always in UTC for posts.	"America/Chicago"
fields (optional)	(Posts endpoint only) List of fields to return in results; if omitted, only the guid field is returned. Refer to the Message Fields section for full list of valid fields	["content_category", "created_time", "from.name"]

Responses - Analytics Endpoints

Responses follow the standard data API response format:

data

This array contains the analytics data requested. See specific endpoints for additional details.

paging

This object specifies the state of paging for this response:

Key	Description	Example Value
current_page	1-indexed page number of the response	3
total_pages	Total number of pages for the request	20

A paging object is always returned, including when the response contains all data in one page. You can rely on checking for current_page = total_pages in order to know when you are at the end of the paging sequence.

Requesting a page greater than total_pages will return a HTTP 400 Bad Request response with a message describing the error.

Limitations

Note the maximum response size is capped at 10,000 results. For example, if a request with 50 responses per page is made, you will get at most 200 total_pages back. Anything beyond this 10,000 limit will be truncated as a performance guardrail.

To request data for responses with more than 10,000 results, use a cursor-based pagination approach following these steps:

1.) Prepare the API URL for the specific endpoint you want to retrieve data from.

2.) Define the request body by specifying the necessary parameters like limit, timezone, filters, fields, and metrics criteria.

3.) Set the appropriate headers, including any required authentication or session information.

4.) Set the "sort" field to organize the response data by "guid" in ascending order

5.) Send an initial request to the API endpoint to retrieve a batch of data, specifying a limit on the number of items to be returned per request (e.g. 100 items per request).

6.) Process the sorted response data and extract the last "guid" value from the response. This "guid" will be used as the cursor for the next request.

7.) Send a subsequent request to the API endpoint. We’ll filter for posts with a guid greater than the guid we saw in the previous step to fetch the next batch of data. This request should also specify the limit and any other necessary parameters. See below for an example request to see how this is done.

8.) Repeat steps 2-7 until there are no more GUID's left in the response. Each time you receive a response, extract the last "guid" value, and use it to filter posts with greater guids for the following requests.

9.) As you receive the paginated responses, you can store or process the data as needed.

Initial Request:

{                                                                            
    "filters": [
        "customer_profile_id.eq(123, 4567, 890)"
    ],
    "fields": [
        "guid"
    ],
    "sort": [
        "guid:asc"
    ],
    "limit": 2 
}

Initial Response:

{
    "data": [
        {
            "guid": "101"
        }, 
        {
            "guid": "102"
        }
    ]
}

Subsequent Request:

{                                                                           
    "filters": [
        "guid.gt(102)",                                       
        "customer_profile_id.eq(123, 4567, 890)"
    ],
    "fields": [
        "guid"
    ],
    "sort": [
        "guid:asc"
    ],
    "limit": 2 
}

Note that the last guid from the initial response (102) was used as a filter for the subsequent response ( "guid.gt(102)"). Each request thereafter should continue to filter on the last guid from the previous response until no more guids are returned.

Owned Profile Analytics Endpoint

POST /v1/<customer ID>/analytics/profiles

The profiles endpoint is used to query profile-level metrics for a given set of profiles.

Request Body - Owned Profile Analytics Endpoint

An example request:

{
  "filters": [
    "customer_profile_id.eq(1234, 5678, 9012)",
    "reporting_period.in(2018-08-01...2018-10-01)"
  ],
  "metrics": [
    "impressions",
    "reactions"
  ],
  "page": 1
}

Response Data - Owned Profile Analytics Endpoint

An example response:

{
  "data" : [
      {
        "dimensions": {
          "reporting_period.by(day)": "2018-08-01",
          "customer_profile_id": 1234
        },
        "metrics": {
          "impressions": 3400,
          "reactions": 12
        }
      },
      {
        "dimensions": {
          "reporting_period.by(day)": "2018-08-01",
          "customer_profile_id": 5678
        },
        "metrics": {
          "impressions": 23423,
          "reactions": 29
        }
      },
      ...
  ],
  "paging": {
    "current_page": 2,
    "total_pages": 3
  }
}

Profile Request Limits & Pagination

• customer_profile_id (filters): maximum of 100 profiles per request
• reporting_period (filters): maximum of 1 year per request
• Pagination of response: pagination is based on 1000 results per response

Profile Time Zone

Profile daily activity uses the time zone of the native network. These time zones are the same that are used by native networks when grouping profile level activity.

Network	Timezone
Twitter	UTC
Facebook	PST/PDT
Instagram	PST/PDT
LinkedIn	UTC
YouTube	PST/PDT
Pinterest	UTC
Tiktok	UTC

Post Analytics Endpoint

POST /v1/<customer ID>/analytics/posts

The posts content endpoint queries for individual sent posts based on a filter criteria.

Request Body - Post Analytics Endpoint

An example request:

{
  "fields": [
    "created_time",
    "perma_link",
    "text",
    "internal.tags.id",
    "internal.sent_by.id",
    "internal.sent_by.email",
    "internal.sent_by.first_name",
    "internal.sent_by.last_name"
  ],
  "filters": [
    "customer_profile_id.eq(1234, 5678, 9012)",
    "created_time.in(2020-04-06T00:00:00..2020-04-19T23:59:59)"
  ],
  "metrics": [
    "lifetime.impressions",
    "lifetime.reactions"
  ],
  "timezone": "America/Chicago",
  "page": 1
}

Response Data - Post Analytics Endpoint

An example response:

{
  "data": [
      {
        "text": "Come by for a cold brew!",
        "perma_link": "https://www.instagram.com/p/B-pIo1GFqyl/",
        "metrics": {
          "lifetime.impressions": 15,
          "lifetime.reactions": 0
        },
        "created_time": "2020-04-06T14:27:03Z",
        "internal": {
          "tags": [
            {"id": 111111},
            {"id": 111112},
            {"id": 111113}
        ],
        "sent_by": {
          "id": 1155555,
          "email": "sprout.user@sproutsocial.com",
          "first_name": "Sprout",
          "last_name": "User"
        }
      },
      ...
  ],
  "paging": {
    "current_page": 1,
    "total_pages": 3
  }
}

Post Request Limits & Pagination

• customer_profile_id (filters): maximum of 100 profiles per request
• Pagination of response: pagination is based on 50 messages per response

Messages Endpoint

POST /v1/<customer ID>/messages

The messages endpoint provides detailed data and metadata about your Sprout messages.

Requests - Messages Endpoint

The request body for a Messages request is a JSON object with the following name/values pairs:

Key	Description	Example
filters	Refer to the Request Filters section below for details	["group_id.eq(78910)", "customer_profile_id.eq(1234, 5678)", "created_time.in(2022-01-01..2022-02-01)"]
fields (optional)	List of fields to return in results. If omitted, only the guid field is returned. Refer to the Message Fields section for full list of valid fields	["post_type", "created_time", "from.name", "text"]
limit (optional)	Specifies the max number of results per page in the response Default: 50, Max: 100	10
timezone (optional)	Time zone — from the ICANN time zone database — used for period values	"America/Chicago"
page_cursor (optional)	In paginated results, specifies the next page of data to return. Pagination for the messages endpoint only supports fetching the 'next' page of data. See Messages Request Limits & Pagination section for details	"page_cursor": "abc123=="
sort (optional)	Return results sorted by message created_time Default: descending	["created_time:asc"]

Request Filters - Messages Endpoint

All requests to the Messages Endpoint require a filter parameter; the following table details the available filter options, which includes both required and optional filters:

Filter Name	Description	Example Values
group_id	Exactly one Group Id to retrieve messages for	"group_id.eq(78910)"
customer_profile_id	One or more Profile ids to retrieve messages for; these profiles must all belong to the requested group_id	"customer_profile_id.eq(1234, 5678)"
created_time	Only return messages having a created_time within the provided date range; accepts either dates or datetimes	"created_time.in(2022-01-01...2022-02-01)"
action_last_update_time (optional)	Only return messages which have a Sprout action (Reply, Tag, Like or Complete) having an action_time within the provided date range; accepts either dates or datetimes. This range cannot be chronologically before the created_time range	"action_last_update_time.in(2022-01-01...2022-02-01)"
post_type (optional)	If provided, only messages of this type will be returned; defaults to all message types if omitted. Refer to the Post Types table for full list of valid post_types available for filtering	"post_type.eq(TWITTER_DIRECT_MESSAGE, INSTAGRAM_MEDIA)"
tag_id (optional)	If provided, only return messages with the specified tag_ids	"tag_id.eq(123, 456, 789)"
language_code (optional)	If provided, only return messages with the specified language_codes	"language_code.eq(en, es, fr)"

Request Body - Messages Endpoint

Example request:

{
  "filters": [
    "group_id.eq(12345)",
    "customer_profile_id.eq(1234, 5678, 9012)",
    "created_time.in(2020-04-06T00:00:00..2020-04-19T23:59:59)",
    "action_last_update_time.in(2020-08-06T00:00:00..2021-02-28T23:59:59)",
    "post_type.eq(TWEET,FACEBOOK_POST,INSTAGRAM_DIRECT_MESSAGE)"
  ],
  "fields": [
    "network",
    "activity_metadata.first_like.time_elapsed",
    "created_time",
    "post_category",
    "post_type",
    "perma_link",
    "text",
    "from",
    "profile_guid",
    "internal.tags.id",
    "internal.sent_by.id",
    "internal.sent_by.email"
  ],
  "sort": ["created_time:desc"],
  "limit": 50,
  "timezone": "America/Chicago",
  "page_cursor": "123abc=="
}

Responses - Messages Endpoint

Responses follow the standard Sprout API response format:

data

This array contains the message's data requested in JSON format.

paging (optional)

This object, if present, indicates there are still more pages of data to be fetched, and provides a cursor pointing to the next page of data:

Key	Description	Example Value
next_cursor	String of alphanumeric characters representing the next page of data, sorted by message created_time	"abcd1234=="

Messages Request Limits & Pagination

• Pagination of response is based on the following request params:

  • limit - number of messages returned per response (max: 100, default: 50)
  • sort - sort order of messages in response; sorted by message created_time (default: desc)

• To paginate results: continuously fetch the "next" page of data, by updating the page_cursor parameter, until a response without a paging object is returned

• Note: Unlike some other Sprout API Endpoints, index-based paging (e.g. page: 4) is not supported by the Messages Endpoint. While you can specify the sort direction, you can only ever get the "next" page of data — you can't fetch the "previous" page

• A Request containing an invalid page_cursor will return a HTTP 400 Bad Request response with a message describing the error

Response Data - Messages Endpoint

Example response:

{
  "data": [
    {
      "post_category": "POST",
      "post_type": "INSTAGRAM_MEDIA",
      "profile_guid": "placeholder",
      "text": "placeholder",
      "perma_link": "link here",
      "network": "INSTAGRAM",
      "internal": {
        "tags": [
          {
            "id": 1234
          },
          {
            "id": 5678
          }
        ],
        "sent_by": {
          "id": 2066696,
          "email": "___@sproutsocial.com",
          "first_name": "placeholder",
          "last_name": "placeholder"
        }
      },
      "created_time": "2022-06-09T22:10:54Z"
    },
    ...
  ],
  "paging": {
    "next_cursor": "456def=="
  }
}  

Listening Endpoints

Listening endpoints are all HTTP POST endpoints. They provide access to your Listening Topic data, including:

• Messages - Enables you to query for messages within a given Topic.
• Metrics - Aggregates data across the Topic.

Overview

All requests to and responses from Listening API endpoints have a similar structure.

Requests - Listening Endpoints

The request body for a Listening API request is a JSON object with the following name/values pairs:

Key	Description	Example Value
filters	Detailed filters used to filter the results by message created_time and network. To learn more about advanced filters for Topics see the Filters section.	["created_time.in(2018-01-01...2018-02-01)"]
metrics	List of metrics to return in results; refer to the metrics	["impressions", "likes"]
fields	List of fields to return in results; at least one field is required for Listening messages endpoint. Refer to the Listening Message Fields section for full list of valid fields	["content_category", "created_time", "from.name"]
page (optional)	In paginated results, which 1-indexed page to return in the response. Pagination is based on default limits of 50 results	3
limit (optional)	Specifies the max number of results per page in the response. Defaults to 50 results for the Listening endpoints.	100
sort (optional)	Sets the sort order for results, specified as a list of fields and directions (asc or desc) in the format <field>:<direction>.	["created_time:asc"]
timezone (optional)	Time zone—from the ICANN time zone database. Timezone arguments only impact date/time-related filters, responses are not impacted and are always in UTC for posts.	"America/Chicago"
dimensions (optional)	(Topic Metrics endpoints only) Breaks down metrics into discrete buckets. See Dimensions section to learn what fields work with dimensions.	["created_time.by(day)", "sentiment"]

Filters - Listening Endpoints

Filtering is a powerful query mechanism that allows you to isolate data within your Topics. You can combine most fields or metrics with the operators below to produce filter to specific data sets using the Topic Messages or Topic Metric endpoints.

Operator	Description	Example Value
gt	Greater than	likes.gt(10)
gte	Greater than or equal to	engagement_total.gte(5)
lt	Less than	replies.lt(5)
lte	Less than or equal to	impressions.lte(1000)
in	Specifies a range. A helper that circumvents needed to use a filter with both gt and lt. Using … is inclusive of the end value while .. is not. Dates and timestamps are accepted.	created_time.in(2023-05-01…2023-06-01T23:59:59)
eq	Equals a particular value. Can contain multiple comma separated values. If multiple values are provided, the filter returns data containing at least one value.	network.eq(TWITTER,INSTAGRAM)
neq	The opposite of eq.	network.neq(FACEBOOK)
exists	Either true or false. Filter finds (or not) messages that meet the criteria of having a value (or not).	visual_media.exists(true)
match	Performs a text search query on a specified field. Multiple comma terms can be provided using spaces, wrap phrases or multiple words in quotes. Messages must match all provided terms. If you want a message that matches any single term, place an OR between terms (e.g. blue OR red).	text.match(blue OR red) text.match(“the blue car”) text.match(blue red green)

You can apply multiple filters where data must meet all requirements by adding filters to the filters array. An example request using multiple filters:

{
  "filters": [
   "created_time.in(2022-11-28..2022-12-29T23:59:59)",
   "text.match(blue car)",
   "network.eq(INSTAGRAM,YOUTUBE,LINKEDIN,REDDIT,TUMBLR,WWW)"
 ]
}

Responses - Listening Endpoints

Responses follow the standard data API response format:

data

This array contains the Listening data requested. See specific endpoints for additional details.

paging

This object specifies the state of paging for this response:

Key	Description	Example Value
current_page	1-indexed page number of the response	3
total_pages	Total number of pages for the request	20

A paging object is always returned, including when the response contains all data in one page. You can rely on checking for current_page = total_pages in order to know when you are at the end of the paging sequence.

Requesting a page greater than total_pages will return a HTTP 400 Bad Request response with a message describing the error.

Dimensions - Listening Endpoints

Dimensions are a powerful tool that allow you to slice and bucket Topic metrics. The most common uses for dimensions would be generating metrics over time (e.g. a trend chart) or breaking down metrics by metadata such as sentiment score. The following Topic fields can be used as a dimension.

• created_time.by(day)
• created_time.by(month)
• visual_media.media_type
• distribution_type
• network
• sentiment
• language
• explicit_label
• location.city
• location.province
• location.country

Here is an example of multiple dimensions being used to create a trend chart of sentiment data over time:

{
  "filters": [
  "created_time.in(2022-11-28..2022-11-30)",
  "network.eq(INSTAGRAM,YOUTUBE,LINKEDIN,REDDIT,TUMBLR,WWW)"
  ],
  "metrics": [
    "replies",
    "shares_count",
    "likes"
  ],
  "dimensions": [
    "created_time.by(day)",
    "sentiment"
  ],
  "timezone": "America/Chicago"
}

Here is a sample output of this query:

{
    "data": [
        {
            "dimensions": {
                "created_time": "2022-11-30T00:00:00-06:00",
                "sentiment": "positive"
            },
            "metrics": {
                "replies": 29.0,
                "shares_count": 5.0,
                "likes": 557.0
            }
        },
        {
            "dimensions": {
                "created_time": "2022-11-30T00:00:00-06:00",
                "sentiment": "neutral"
            },
            "metrics": {
                "replies": 17.0,
                "shares_count": 5.0,
                "likes": 354.0
            }
        },
        {
            "dimensions": {
                "created_time": "2022-11-30T00:00:00-06:00",
                "sentiment": "negative"
            },
            "metrics": {
                "replies": 49.0,
                "shares_count": 20.0,
                "likes": 4725.0
            }
        }
    ],
    "paging": {}
}

Topic Messages Endpoint

POST /v1/<customer ID>/listening/topics/<topic id>/messages

The Topic messages endpoint enables you to query for messages within a given Topic. The returning data set is an array of matching messages and the requested metrics or fields for each. This endpoint is best used to extract raw messages for further processing or providing sample messages within dashboards.

Request Body - Topic Messages Endpoint

An example request:

{
  "filters": [
    "created_time.in(2022-11-28..2022-12-29T23:59:59)",
    "explicit_label.exists(false), explicit_label.eq(false)",
    "network.eq(INSTAGRAM,YOUTUBE,LINKEDIN,REDDIT,TUMBLR,WWW)"
  ],
  "fields": [
    "content_category",
    "created_time",
    "hashtags",
    "language",
    "location.city"
  ],
  "metrics": [
    "engagements",
    "from.followers_count",
    "likes",
    "replies",
    "shares_count",
    "authors_count",
    "positive_sentiments_count",
    "neutral_sentiments_count",
    "negative_sentiments_count"
  ],
  "sort": [
    "created_time:desc"
  ],
  "timezone": "America/Chicago",
  "limit": 50,
  "page": 1
}

Response Data - Topic Messages Endpoint

An example response:

{
    "data": [
        {
            "content_category": "PHOTO",
            "guid": "17920699361640551",
            "text": "Late post from Seattle trip \nColder than a blizzard in Alaska\n#seattle #seattlewashington #stevenspass #mtbakersnoqualmienationalforest #mtbaker #snoqualmiepass #snoqualmienationalforest #pikeplacemarket #pikeplace #seattlespaceneedle",
            "perma_link": "https://www.instagram.com/p/CmxucH6L7T1/",
            "network": "INSTAGRAM",
            "visual_media": [
                {
                    "media_url": "https://scontent-iad3-1.cdninstagram.com/v/t51.29350-15/323197452_926427338517295_6369335809654161527_n.jpg?_nc_cat=104&ccb=1-7&_nc_sid=8ae9d6&_nc_ohc=y4k7DO4QBHAAX8M7OZ1&_nc_ht=scontent-iad3-1.cdninstagram.com&edm=APCawUEEAAAA&oh=00_AfCps_5bFDmdZE-YVPDwVn5WF3XFWK4PWhd4-uRNTU2iCg&oe=643BF019",
                    "media_type": "PHOTO"
                },
                {
                    "media_url": "https://scontent-iad3-1.cdninstagram.com/v/t51.29350-15/322406676_8455452681195785_5328220517853332026_n.jpg?_nc_cat=101&ccb=1-7&_nc_sid=8ae9d6&_nc_ohc=VpBu3GAXQqoAX_K5LU3&_nc_ht=scontent-iad3-1.cdninstagram.com&edm=APCawUEEAAAA&oh=00_AfD4SCutTw_J7hPbzUJNpAEyaoXd6kBmzHJM-MINZapJmg&oe=643CCB3C",
                    "media_type": "PHOTO"
                },
                {
                    "media_url": "https://scontent-iad3-1.cdninstagram.com/v/t51.29350-15/322520040_494039015961334_6394396172311331958_n.jpg?_nc_cat=101&ccb=1-7&_nc_sid=8ae9d6&_nc_ohc=t6xksNZv91kAX9rE5mL&_nc_ht=scontent-iad3-1.cdninstagram.com&edm=APCawUEEAAAA&oh=00_AfBgn_HEqLsn269mk4oAFXQmbSrbRbxzpbrfwXZLg2F2YQ&oe=643BA80B",
                    "media_type": "PHOTO"
                },
                {
                    "media_url": "https://scontent-iad3-2.cdninstagram.com/v/t51.29350-15/322386857_955848772063194_984682163981872244_n.jpg?_nc_cat=105&ccb=1-7&_nc_sid=8ae9d6&_nc_ohc=zIh0QFX3T50AX95k8wg&_nc_ht=scontent-iad3-2.cdninstagram.com&edm=APCawUEEAAAA&oh=00_AfB7_8ChB-7nq4MXdOaIatp0sCw4ZXqEOoikh-cCoEUIGA&oe=643BE125",
                    "media_type": "PHOTO"
                },
                {
                    "media_url": "https://scontent-iad3-1.cdninstagram.com/v/t51.29350-15/322393885_1262531494303623_5396853589364944362_n.jpg?_nc_cat=102&ccb=1-7&_nc_sid=8ae9d6&_nc_ohc=uzwo3FqbohgAX_wtdqq&_nc_ht=scontent-iad3-1.cdninstagram.com&edm=APCawUEEAAAA&oh=00_AfAZmRdk8Va92UX3FmnjMJo_wf2rxwP5E_5ExT4-TWSSpA&oe=643BD1F1",
                    "media_type": "PHOTO"
                },
                {
                    "media_url": "https://scontent-iad3-1.cdninstagram.com/v/t51.29350-15/322830314_217584514039146_7428674933900498885_n.jpg?_nc_cat=110&ccb=1-7&_nc_sid=8ae9d6&_nc_ohc=m2PtitrP1A0AX8f6gso&_nc_ht=scontent-iad3-1.cdninstagram.com&edm=APCawUEEAAAA&oh=00_AfD6KYXBQVk_BNNQ0FUM8NihyH08v7QF_t61BY3mFdu7sA&oe=643B60F6",
                    "media_type": "PHOTO"
                },
                {
                    "media_url": "https://scontent-iad3-2.cdninstagram.com/v/t51.29350-15/322294142_738549953871939_8482926741552785486_n.jpg?_nc_cat=111&ccb=1-7&_nc_sid=8ae9d6&_nc_ohc=k8lcfSt9dhMAX_FZEyt&_nc_ht=scontent-iad3-2.cdninstagram.com&edm=APCawUEEAAAA&oh=00_AfAQYi1Lx_i-c-SRkWt6tfuhptuuvFx2PlBN1b6fb7kFGA&oe=643CA58A",
                    "media_type": "PHOTO"
                },
                {
                    "media_url": "https://scontent-iad3-1.cdninstagram.com/v/t51.29350-15/322601354_1215109445751814_6654433182308805760_n.jpg?_nc_cat=107&ccb=1-7&_nc_sid=8ae9d6&_nc_ohc=XsbPztVyu-4AX8vsyjC&_nc_ht=scontent-iad3-1.cdninstagram.com&edm=APCawUEEAAAA&oh=00_AfBdQ9GECTdbNtQ-06ruuXQVsN5qPrwKnGsghbaj8uPjig&oe=643B6CDE",
                    "media_type": "PHOTO"
                }
            ],
            "hashtags": [
                "seattlespaceneedle",
                "snoqualmienationalforest",
                "seattle",
                "stevenspass",
                "pikeplace",
                "seattlewashington",
                "mtbakersnoqualmienationalforest",
                "mtbaker",
                "pikeplacemarket",
                "snoqualmiepass"
            ],
            "created_time": "2022-12-30T03:27:02Z",
            "listening_metadata": {
                "sentiment": "neutral",
                "explicit_label": false,
                "language": "en"
            }
        }
    ],
    "paging": {
        "current_page": 1
    }
}

Listening Messages Request Limits & Pagination

• Pagination of response is based on the following request params:
  • limit - number of messages returned per response (max: 100, default: 50)
  • sort - sort order of messages in response; sorted by message created_time (default: desc)

Topic Metrics Endpoint

POST /v1/<customer ID>/listening/topics/<topic id>/metrics

The Topic metrics endpoint aggregates data across the Topic. Use this endpoint when you need answers related to key metrics such as total Topic volume, engagement, etc. or trends over time. This endpoint is best for quick insights or building complex dashboards.

Request Body - Topic Metrics Endpoint

An example request:

{
  "filters": [
    "created_time.in(2022-11-28..2022-12-29T23:59:59)",    
    "network.eq(INSTAGRAM,YOUTUBE,LINKEDIN,REDDIT,TUMBLR,WWW)",
    "sentiment.eq(positive,negative,neutral,unclassified)"
  ],
  "metrics": [
    "replies",
    "shares_count",
    "likes"
  ],
  "dimensions": [
    "sentiment"
  ],
  "timezone": "America/Chicago"
}

Response Data - Topic Metrics Endpoint

An example response:

{
 "data": [
   {
     "dimensions": {
       "sentiment": "POSITIVE"
     },
     "metrics": {
       "replies": 178563.0,
       "shares_count": 55535.0,
       "likes": 7221913.0
     }
   },
   {
     "dimensions": {
       "sentiment": "NEGATIVE"
     },
     "metrics": {
       "replies": 38758.0,
       "shares_count": 43396.0,
       "likes": 468540.0
     }
   },
   {
     "dimensions": {
       "sentiment": "NEUTRAL"
     },
     "metrics": {
       "replies": 14252.0,
       "shares_count": 25529.0,
       "likes": 807694.0
     }
   },
   {
     "dimensions": {
       "sentiment": "UNCLASSIFIED"
     },
     "metrics": {
       "replies": 31900.0,
       "shares_count": 17977.0,
       "likes": 1074959.0
     }
   }
 ]
}

Listening Metrics Request Limits & Pagination

• Pagination of response is based on the following request params:
  • limit - number of messages returned per response (max: 100, default: 50)
  • sort - sort order of messages in response; sorted by message created_time (default: desc)

Metrics & Fields

Message Metadata

Message Fields

Key	Type	Network Availability	Notes
content_category	STRING		Unified categorization of the content. The hierarchy is album, video, photo, link, poll or text.
created_time	DATE		An iso8601 timestamp representing the publication date and time of the message.
from	MAP		A shorthand for requesting all of the following "from" nested fields. Represents the social network profile that published the message.
from.guid	STRING		The native ID of the authors' profile prefixed with a Sprout code that represents where the data was collected.
from.name	STRING		The display name of the author.
from.profile_picture	STRING		URL to the profile picture.
from.screen_name	STRING		Also commonly called "handle," this field is mutable on most networks, but not changed as often as the display name.
guid	STRING		The native ID of the message prefixed with a Sprout code that represents where this type of message is.
customer_profile_id	NUMBER		ID of the profile associated with this message. Corresponds to the customer_profile_id in the requested filters.
internal	MAP		A shorthand for requesting internal.tags.id and internal.sent_by.id.
internal.tags.id	ARRAY<NUMBER>		Array of tag IDs this message is associated with. Includes active and archived tags.
internal.sent_by.id	NUMBER		ID of the team member that sent this message via Sprout.
internal.sent_by.email	STRING		Email address of the team member that sent this message.
internal.sent_by.first_name	STRING		First name of the team member that sent this message.
internal.sent_by.last_name	STRING		Last name of the team member that sent this message.
sent	BOOLEAN		(Posts endpoint only) If the message is sent by the requested profiles, true. Otherwise, the message is considered received by the requested profile(s) and returned false.
post_type	STRING		Uniquely identifies the social network and type of message this is. Refer to the Post Types table for full list of valid post_types
post_category	STRING		A unified version of post_type, these names are not network specific.
network	STRING		The social network that the data came from (e.g. INSTAGRAM).
perma_link	STRING		URL to the message on the social network.
inbox_permalink	STRING		URL to the message thread in the Sprout Social Smart Inbox.
profile_guid	STRING		The ID of the profile being tracked prefixed with an Sprout code that represents where the data was collected. When the message was made by the profile being tracked, this field will be identical to from.guid.
text	STRING		The text in the body of the message.
title	STRING		Text that is separate from the usual body of the message, usually shown as a title for the message in the social network.
clickthrough_link	MAP		Metadata about a link to another entity that appears on the message, e.g. when a Pinterest message contains a link to a different website.
clickthrough_link.name	STRING
clickthrough_link.long	STRING
clickthrough_link.short	STRING
hashtags	ARRAY<STRING>		Array of hashtags associated with the message (does not include the "#" character).
visual_media	ARRAY<MAP>		Array of media shared on the message, e.g. photos and videos. Where possible, contains URLs for the full media, a high resolution display image and a thumbnail image.
pinterest.board_name	STRING		(Posts endpoint only) The name of the collection where users save specific pins.
activity_metadata	ARRAY<MAP>		(Messages endpoint only) Contains information about the first of each Sprout Action(s) taken on a message, such as actor and timestamp. Depending on network limitations, this may include Reply, Tag, Complete and Like actions.

Listening Message Fields

Key	Type	Network Availability	Notes
content_category	STRING		Unified categorization of the content. The hierarchy is album, video, photo, link, poll or text.
created_time	DATE		An iso8601 timestamp representing the publication date and time of the message.
from.guid	STRING		The native ID of the authors' profile prefixed with a Sprout code that represents where the data was collected.
from.name	STRING		The display name of the author.
from.profile_picture	STRING		URL to the profile picture.
from.screen_name	STRING		Also commonly called "handle," this field is mutable on most networks, but not changed as often as the display name.
from.profile_url	STRING		A url back to the author profile.
from.followers_count	NUMBER		The latest number of followers for the profile.
guid	STRING		The native ID of the message prefixed with a Sprout code that represents where this type of message is.
network	STRING		The social network that the data came from (e.g. INSTAGRAM).
perma_link	STRING		URL to the message on the social network.
profile_guid	STRING		The ID of the profile being tracked prefixed with an Sprout code that represents where the data was collected. When the message was made by the profile being tracked, this field will be identical to from.guid.
text	STRING		The text in the body of the message.
title	STRING		Text that is separate from the usual body of the message, usually shown as a title for the message in the social network.
hashtags	ARRAY<STRING>		Array of hashtags associated with the message (does not include the "#" character).
visual_media	ARRAY<MAP>		Array of media shared on the message, e.g. photos and videos. Where possible, contains URLs for the full media, a high resolution display image and a thumbnail image.
sentiment	STRING		The sentiment category (e.g. positive, neutral, negative, etc) of the message.
sentiment_raw	NUMBER		A raw sentiment score between 1 and -1. Scores closer to 1 are more likely to be positive while scores closer to -1 are more likely to be negative.
language	STRING		The primary language of the text. The primary language is selected based on which language makes up most of the text.
location.city	STRING		An estimation of the city where the message was posted. Location data exists on Twitter only. In some instances, we take content from the authors bio or the message itself to determine location information for other networks.
location.province	STRING		An estimation of the province where the message was posted. Location data exists on Twitter only. In some instances, we take content from the authors bio or the message itself to determine location information for other networks.
location.country	STRING		An estimation of the country where the message was posted. Location data exists on Twitter only. In some instances, we take content from the authors bio or the message itself to determine location information for other networks.
source.name	STRING		The name of the publication or page. e.g. "The New York Times" or "Green Thumb Subreddit"
source.url	STRING		The link to the publication or page.
parent_message_id	STRING		If the message was a reply, this will hold an ID of the parent message.
explicit_label	STRING		A true or false indication of whether the message contains explicit content.
explicit_probability	NUMBER		A probability that the message contains explicit content.
mentions	ARRAY<STRING>		A list of other profiles mentioned in the message.
emoticons	ARRAY<STRING>		A list of emoticons (e.g. emoji) used in the message.
keywords	ARRAY<STRING>		A list of keywords or phrases used in the message.
related_words	ARRAY<STRING>		A list of related keywords used in the message.

Post Types

Network	post_type value	Description
	TWEET	Tweet
	TWITTER_MENTION	Twitter Mention
	RETWEET	Retweet
	RETWEET_COMMENT	Retweet Comment
	TWITTER_DIRECT_MESSAGE	Twitter DM
	TWITTER_FOLLOWER_ALERT	Twitter Follower Alert
	FACEBOOK_POST	Regular FB Post (may include ‘Organic Posts’ and Dynamic Ads)
	FBCR_COMMENT	FB Comment on a Post
	FACEBOOK_GROUP_POST	FB Group Post
	FACEBOOK_GROUP_COMMENT	FB Comment on a Group Post
	FACEBOOK_AD	FB Ad Post (excluding Dynamic Ads)
	FACEBOOK_AD_COMMENT	FB Comment on an Ad Post
	FACEBOOK_MESSENGER_PM	FB Messenger Private Message
	FACEBOOK_RATING	FB Rating
	INSTAGRAM_MEDIA	IG Media
	INSTAGRAM_MEDIA_CAPTION_MENTION	IG Media Caption Mention
	INSTAGRAM_PHOTO_TAG	IG Media Tag
	INSTAGRAM_DIRECT_MESSAGE	IG DM
	INSTAGRAM_STORY	IG Story
	INSTAGRAM_STORY_MENTION	IG Story Mention
	INSTAGRAM_COMMENT_MENTION	IG Comment Mention
	INSTAGRAM_GRAPH_COMMENT	IG Comment
	FB_INSTAGRAM_AD_POST	IG Ad Post
	FB_INSTAGRAM_AD_COMMENT	IG Comment on an Ad Post
	TIKTOK_VIDEO	Tiktok Video
	TIKTOK_VIDEO_COMMENT	Tiktok comment on a Video
	APPLE_APPSTORE_REVIEW	Apple App Store Review
	APPLE_APPSTORE_REVIEW_REPLY	Apple App Store Reply to Review
	GLASSDOOR_REVIEW	Glassdoor Review
	GLASSDOOR_REVIEW_REPLY	Glassdoor Reply to Review
	GOOGLE_MY_BUSINESS_REVIEW	Google My Business (GMB) Review
	GOOGLE_MY_BUSINESS_REVIEW_REPLY	Google My Business (GMB) Reply to Review
	GOOGLE_MY_BUSINESS_POST	Google My Business Public Post
	GBM_LOCATION_MESSAGE	Google Business Messages (GBM) Location Message
	GBM_AGENT_MESSAGE	Google Business Messages (GBM) Agent Message
	GOOGLE_PLAYSTORE_REVIEW	Google Play Store Review
	GOOGLE_PLAYSTORE_REVIEW_REPLY	Google Play Store Reply to Review
	LINKEDIN_COMPANY_COMMENT	LinkedIn Company Comment
	LINKEDIN_COMPANY_UPDATE	LinkedIn Company Update
	LINKEDIN_PERSONAL_POST	LinkedIn Personal Post
	TRIPADVISOR_REVIEW	Tripadvisor Review
	TRIPADVISOR_REVIEW_REPLY	Tripadvisor Reply to Review (can't send from Sprout due to network limitations)
	WHATSAPP_DIRECT_MESSAGE	Whatsapp Message
	YELP_REVIEW	Yelp Review
	YELP_REVIEW_REPLY	Yelp Reply to Review
	YOUTUBE_VIDEO	Youtube Video
	YOUTUBE_COMMENT	Youtube Comment

Topic Metrics

Metric	Key
Total Engagement	engagements
Total Likes	likes
Total Replies	replies
Total Shares	shares_count
Author Follower Count	from.followers_count
Authors count	authors_count
Count of Positive Messages	positive_sentiments_count
Count of Neutral Messages	neutral_sentiments_count
Count of Negative Messages	negative_sentiments_count
Total Potential Impressions	impressions
Volume or Topic Messages	messages_count

Twitter

Note: Twitter has additional review and compliance requirements around exposing data through the Sprout Analytics API. Customers are required to undergo a brief Twitter review and approval process before being able to access their Twitter data through the Sprout Analytics API. Twitter data is not available for Listening endpoints.

Twitter: Owned Profile Metrics

Metric	Key
Followers	lifetime_snapshot.followers_count
Net Follower Growth	net_follower_growth
Impressions	impressions
Media Views	post_media_views
Video Views	video_views
Reactions	reactions
Likes	likes
@Replies	comments_count
Retweets	shares_count
Post Clicks (All)	post_content_clicks
Post Link Clicks	post_link_clicks
Other Post Clicks	post_content_clicks_other
Post Media Clicks	post_media_clicks
Post Hashtag Clicks	post_hashtag_clicks
Post Detail Expand Clicks	post_detail_expand_clicks
Profile Clicks	post_profile_clicks
Other Engagements	engagements_other
App Engagements	post_app_engagements
App Install Attempts	post_app_installs
App Opens	post_app_opens
Posts Sent Count	posts_sent_count
Posts Sent By Post Type	posts_sent_by_post_type
Posts Sent By Content Type	posts_sent_by_content_type

Twitter: Calculated Profile Metrics

The following metrics are derived from owned profile metrics:

• Followers = the last available lifetime_snapshot.followers_count metric
• (Sprout’s default) Engagements = Likes + @Replies + Retweets + Post Link Clicks + Other Post Clicks + Other Engagements
• Engagement Rate (per Follower) = Engagements / Followers
• Engagement Rate (per Impression) = Engagements / Impressions
• Click-Through Rate = Post Link Clicks / Impressions

Twitter: Post Metrics

Metric	Key
Impressions	lifetime.impressions
Media Views	lifetime.post_media_views
Video Views	lifetime.video_views
Reactions	lifetime.reactions
Likes	lifetime.likes
@Replies	lifetime.comments_count
Retweets	lifetime.shares_count
Post Clicks (All)	lifetime.post_content_clicks
Post Link Clicks	lifetime.post_link_clicks
Other Post Clicks	lifetime.post_content_clicks_other
Post Media Clicks	lifetime.post_media_clicks
Post Hashtag Clicks	lifetime.post_hashtag_clicks
Post Detail Expand Clicks	lifetime.post_detail_expand_clicks
Profile Clicks	lifetime.post_profile_clicks
Other Engagements	lifetime.engagements_other
Follows from Posts	lifetime.post_followers_gained
Unfollows from Posts	lifetime.post_followers_lost
App Engagements	lifetime.post_app_engagements
App Install Attempts	lifetime.post_app_installs
App Opens	lifetime.post_app_opens

Twitter: Calculated Post Metrics

The following metrics are derived from post metrics:

• (Sprout’s default) Engagements = Likes + @Replies + Retweets + Post Link Clicks + Other Post Clicks + Other Engagements
• Engagement Rate (per Follower) = Engagements / Followers
• Engagement Rate (per Impression) = Engagements / Impressions
• Click-Through Rate = Post Link Clicks / Impressions

Facebook

Facebook: Owned Profile Metrics

Metric	Key
Followers	lifetime_snapshot.followers_count
Net Follower Growth	net_follower_growth
Followers Gained	followers_gained
Organic Followers Gained	followers_gained_organic
Paid Followers Gained	followers_gained_paid
Page Unlikes	followers_lost
Fans	lifetime_snapshot.fans_count
Page Likes	fans_gained
Organic Page Likes	fanss_gained_organic
Paid Page Likes	fans_gained_paid
Page Unlikes	fans_lost
Impressions	impressions
Organic Impressions	impressions_organic
Viral Impressions	impressions_viral
Non-viral Impressions	impressions_nonviral
Paid Impressions	impressions_paid
Page Tab Views	tab_views
Logged In Page Tab Views	tab_views_login
Logged Out Page Tab Views	tab_views_logout
Post Impressions	post_impressions
Organic Post Impressions	post_impressions_organic
Viral Post Impressions	post_impressions_viral
Non-viral Post Impressions	post_impressions_nonviral
Paid Post Impressions	post_impressions_paid
Reach	impressions_unique
Organic Reach	impressions_organic_unique
Viral Reach	impressions_viral_unique
Non-viral Reach	impressions_nonviral_unique
Paid Reach	impressions_paid_unique
Page Views	profile_views
Reactions	reactions
Comments	comments_count
Shares	shares_count
Post Link Clicks	post_link_clicks
Other Post Clicks	post_content_clicks_other
Likes	likes
Love Reactions	reactions_love
Haha Reactions	reactions_haha
Wow Reactions	reactions_wow
Sad Reactions	reactions_sad
Angry Reactions	reactions_angry
Post Photo View Clicks	post_photo_view_clicks
Post Video Play Clicks	post_video_play_clicks
Page Actions	profile_actions
Post Engagements	post_engagements
Action Button Clicks	cta_clicks_login
Answers	question_answers
Offer Claims	offer_claims
Other Positive Feedback	positive_feedback_other
Event RSVPs	event_rsvps
Place Check-ins	place_checkins
Negative Feedback	negative_feedback
Video Views	video_views
Organic Video Views	video_views_organic
Paid Video Views	video_views_paid
Autoplay Video Views	video_views_autoplay
Click to Play Video Views	video_views_click_to_play
Replayed Video Views	video_views_repeat
Video View Time	video_view_time
Unique Video Views	video_views_unique
Full Video Views	video_views_30s_complete
Organic Full Video Views	video_views_30s_complete_organic
Paid Full Video Views	video_views_30s_complete_paid
Autoplay Full Video Views	video_views_30s_complete_autoplay
Click to Play Full Video Views	video_views_30s_complete_click_to_play
Replayed Full Video Views	video_views_30s_complete_repeat
Unique Full Video Views	video_views_30s_complete_unique
Partial Video Views	video_views_partial
Organic Partial Video Views	video_views_partial_organic
Paid Partial Video Views	video_views_partial_paid
Autoplay Partial Video Views	video_views_partial_autoplay
Click to Play Partial Video Views	video_views_partial_click_to_play
Replayed Partial Video Views	video_views_partial_repeat
10-Second Video Views	video_views_10s
Organic 10-Second Video Views	video_views_10s_organic
Paid 10-Second Video Views	video_views_10s_paid
Autoplay 10-Second Video Views	video_views_10s_autoplay
Click to Play 10-Second Video Views	video_views_10s_click_to_play
Replayed 10-Second Video Views	video_views_10s_repeat
Unique 10-Second Video Views	video_views_10s_unique
Posts Sent Count	posts_sent_count
Posts Sent By Post Type	posts_sent_by_post_type
Posts Sent By Content Type	posts_sent_by_content_type

Facebook: Calculated Profile Metrics

The following metrics are derived from owned profile metrics:

• Fans = the last available lifetime_snapshot.followers_count metric
• (Sprout’s default) Engagements = Reactions + Comments + Shares + Post Link Clicks + Other Post Clicks
• Engagement Rate (per Follower) = Engagements / Followers
• Engagement Rate (per Impression) = Engagements / Impressions
• Click-Through Rate = Post Link Clicks / Impressions

Facebook: Post Metrics

Metric	Key
Impressions	lifetime.impressions
Organic Impressions	lifetime.impressions_organic
Viral Impressions	lifetime.impressions_viral
Non-viral Impressions	lifetime.impressions_nonviral
Paid Impressions	lifetime.impressions_paid
Fan Impressions	lifetime.impressions_follower
Non-fan Impressions	lifetime.impressions_nonfollower
Reach	lifetime.impressions_unique
Organic Reach	lifetime.impressions_organic_unique
Viral Reach	lifetime.impressions_viral_unique
Non-viral Reach	lifetime.impressions_nonviral_unique
Paid Reach	lifetime.impressions_paid_unique
Fan Reach	lifetime.impressions_follower_unique
Reactions	lifetime.reactions
Likes	lifetime.likes
Love Reactions	lifetime.reactions_love
Haha Reactions	lifetime.reactions_haha
Wow Reactions	lifetime.reactions_wow
Sad Reactions	lifetime.reactions_sad
Angry Reactions	lifetime.reactions_angry
Comments	lifetime.comments_count
Shares	lifetime.shares_count
Answers	lifetime.question_answers
Post Clicks (All)	lifetime.post_content_clicks
Post Link Clicks	lifetime.post_link_clicks
Post Photo View Clicks	lifetime.post_photo_view_clicks
Post Video Play Clicks	lifetime.post_video_play_clicks
Other Post Clicks	lifetime.post_content_clicks_other
Negative Feedback	lifetime.negative_feedback
Engaged Users	lifetime.engagements_unique
Engaged Fans	lifetime.engagements_follower_unique
Unique Post Clicks	lifetime.post_content_clicks_unique
Unique Post Link Clicks	lifetime.post_link_clicks_unique
Unique Post Photo View Clicks	lifetime.post_photo_view_clicks_unique
Unique Post Video Play Clicks	lifetime.post_video_play_clicks_unique
Unique Other Post Clicks	lifetime.post_other_clicks_unique
Unique Negative Feedback	lifetime.negative_feedback_unique
Video Length	video_length
Video Views	lifetime.video_views
Organic Video Views	lifetime.video_views_organic
Paid Video Views	lifetime.video_views_paid
Autoplay Video Views	lifetime.video_views_autoplay
Click to Play Video Views	lifetime.video_views_click_to_play
Sound on Video Views	lifetime.video_views_sound_on
Sound off Video Views	lifetime.video_views_sound_off
10-Second Video Views	lifetime.video_views_10s
Organic 10-Second Video Views	lifetime.video_views_10s_organic
Paid 10-Second Video Views	lifetime.video_views_10s_paid
Autoplay 10-Second Video Views	lifetime.video_views_10s_autoplay
Click to Play 10-Second Video Views	lifetime.video_views_10s_click_to_play
Sound on 10-Second Video Views	lifetime.video_views_10s_sound_on
Sound off 10-Second Video Views	lifetime.video_views_10s_sound_off
Partial Video Views	lifetime.video_views_partial
Organic Partial Video Views	lifetime.video_views_partial_organic
Paid Partial Video Views	lifetime.video_views_partial_paid
Autoplay Partial Video Views	lifetime.video_views_partial_autoplay
Click to Play Partial Video Views	lifetime.video_views_partial_click_to_play
Full Video Views	lifetime.video_views_30s_complete
Organic Full Video Views	lifetime.video_views_30s_complete_organic
Paid Full Video Views	lifetime.video_views_30s_complete_paid
Autoplay Full Video Views	lifetime.video_views_30s_complete_autoplay
Click to Play Full Video Views	lifetime.video_views_30s_complete_click_to_play
95% Video Views	lifetime.video_views_p95
Organic 95% Video Views	lifetime.video_views_p95_organic
Paid 95% Video Views	lifetime.video_views_p95_paid
Unique Video Views	lifetime.video_views_unique
Unique Organic Video Views	lifetime.video_views_organic_unique
Unique Paid Video Views	lifetime.video_views_paid_unique
Unique 10-Second Video Views	lifetime.video_views_10s_unique
Unique Full Video Views	lifetime.video_views_30s_complete_unique
Unique Organic 95% Video Views	lifetime.video_views_p95_organic_unique
Unique Paid 95% Video Views	lifetime.video_views_p95_paid_unique
Average Video Time Watched	lifetime.video_view_time_per_view
Video View Time	lifetime.video_view_time
Organic Video View Time	lifetime.video_view_time_organic
Paid Video View Time	lifetime.video_view_time_paid
Video Ad Break Ad Impressions	lifetime.video_ad_break_impressions
Video Ad Break Ad Earnings	lifetime.video_ad_break_earnings
Video Ad Break Ad Cost per Impression (CPM)	lifetime.video_ad_break_cost_per_impression

Facebook: Calculated Post Metrics

The following metrics are derived from post metrics:

• (Sprout’s default) Engagements = Reactions + Comments + Shares + Post Link Clicks + Other Post Clicks
• Engagement Rate (per Follower) = Engagements / Followers
• Engagement Rate (per Impression) = Engagements / Impressions
• Engagement Rate (per Reach) = Engagements / Reach
• Click-Through Rate = Post Link Clicks / Impressions

Instagram

Instagram: Owned Profile Metrics

Metric	Key
Followers	lifetime_snapshot.followers_count
Followers By Age Gender	lifetime_snapshot.followers_by_age_gender
Followers By City	lifetime_snapshot.followers_by_city
Followers By Country	lifetime_snapshot.followers_by_country
Net Follower Growth	net_follower_growth
Followers Gained	followers_gained
Followers Lost	followers_lost
Following	lifetime_snapshot.following_count
Net Following Growth	net_following_growth
Impressions	impressions
Reach	impressions_unique
Profile Visitors	profile_views_unique
Post Video Views	video_views
Reactions	reactions
Likes	likes
Comments	comments_count
Saves	saves
Shares	shares_count
Story Replies	story_replies
Email Clicks	email_contacts
Get Directions Clicks	get_directions_clicks
Phone Call Clicks	phone_call_clicks
Text Message Clicks	text_message_clicks
Website Clicks	website_clicks
Posts Sent Count	posts_sent_count
Posts Sent By Post Type	posts_sent_by_post_type
Posts Sent By Content Type	posts_sent_by_content_type

Instagram: Calculated Profile Metrics

The following metrics are derived from owned profile metrics:

• Followers = the last available lifetime_snapshot.followers_count metric
• (Sprout’s default) Engagements = Likes + Comments + Shares + Saves + Story Replies
• Engagement Rate (per Follower) = Engagements / Followers
• Engagement Rate (per Impression) = Engagements / Impressions
• Profile Actions = Email Clicks + Get Directions Clicks + Phone Call Clicks + Text Message Clicks + Website Clicks

Instagram: Post Metrics

Metric	Key
Comments	lifetime.comments_count
Impressions	lifetime.impressions
Likes	lifetime.likes
Reach	lifetime.impressions_unique
Reactions	lifetime.reactions
Saves	lifetime.saves
Shares	lifetime.shares_count
SproutLink Clicks	lifetime.link_in_bio_clicks
Story Exits	lifetime.story_exits
Story Replies	lifetime.comments_count
Story Taps Back	lifetime.story_taps_back
Story Taps Forward	lifetime.story_taps_forward
Video Views	lifetime.video_views

Instagram: Calculated Post Metrics

The following metrics are derived from post metrics:

• (Sprout’s default) Engagements = Likes + Comments + Shares + Saves + Story Replies
• Engagement Rate (per Follower) = Engagements / Followers
• Engagement Rate (per Impression) = Engagements / Impressions
• Engagement Rate (per Reach) = Engagements / Reach
• Click-Through Rate = Post Link Clicks / Impressions

LinkedIn

LinkedIn: Owned Profile Metrics

Metric	Key
Followers	lifetime_snapshot.followers_count
Followers By Job	lifetime_snapshot.followers_by_job_function
Followers By Seniority	lifetime_snapshot.followers_by_seniority
Net Follower Growth	net_follower_growth
Followers Gained	followers_gained
Organic Followers Gained	followers_gained_organic
Paid Followers Gained	followers_gained_paid
Followers Lost	followers_lost
Impressions	impressions
Reach	impressions_unique
Reactions	reactions
Comments	comments_count
Shares	shares_count
Post Clicks (All)	post_content_clicks
Posts Sent Count	posts_sent_count
Posts Sent By Post Type	posts_sent_by_post_type
Posts Sent By Content Type	posts_sent_by_content_type

LinkedIn: Calculated Profile Metrics

The following metrics are derived from owned profile metrics:

• Followers = the last available lifetime_snapshot.followers_count metric
• (Sprout’s default) Engagements = Reactions + Comments + Shares + Post Clicks (All)
• Engagement Rate (per Follower) = Engagements / Followers
• Engagement Rate (per Impression) = Engagements / Impressions

LinkedIn: Post Metrics

Metric	Key
Impressions	lifetime.impressions
Reactions	lifetime.reactions
Comments	lifetime.comments_count
Shares	lifetime.shares_count
Post Clicks (All)	lifetime.post_content_clicks
Video Views	lifetime.video_views
Poll Votes	lifetime.vote_count

LinkedIn: Calculated Post Metrics

The following metrics are derived from post metrics:

• (Sprout’s default) Engagements = Reactions + Comments + Shares + Post Clicks (All)
• Engagement Rate (per Follower) = Engagements / Followers
• Engagement Rate (per Impression) = Engagements / Impressions

YouTube

YouTube: Owned Profile Metrics

Metric	Key
Followers	lifetime_snapshot.followers_count
Net Follower Growth	net_follower_growth
Followers Gained	followers_gained
Followers Lost	followers_lost
Posts Sent Count	posts_sent_count

YouTube: Calculated Profile Metrics

The following metrics are derived from owned profile metrics:

• Net Follower Growth = Followers Gained - Followers Lost
• (Sprout’s default) Video Engagements = Comments + Likes + Dislikes + Shares + Subscribers Gained + Annotation Clicks + Card Clicks
• (Sprout’s default) Video Engagements Per View = Video Engagements / Video Views

YouTube: Post Metrics

Metric	Key
Annotation Clicks	lifetime.annotation_clicks
Annotation Click Rate	lifetime.annotation_click_through_rate
Clickable Annotation Impressions	lifetime.annotation_clickable_impressions
Closable Annotation Impressions	lifetime.annotation_closable_impressions
Annotation Closes	lifetime.annotation_closes
Annotation Close Rate	lifetime.annotation_close_rate
Annotation Impressions	lifetime.annotation_impressions
Card Clicks	lifetime.card_clicks
Card Impressions	lifetime.card_impressions
Card Click Rate	lifetime.card_click_rate
Card Teaser Clicks	lifetime.card_teaser_clicks
Card Teaser Impressions	lifetime.card_teaser_impressions
Card Teaser Click Rate	lifetime.card_teaser_click_rate
Estimated Minutes Watched	lifetime.estimated_minutes_watched
Estimated YT Red Minutes Watched	lifetime.estimated_red_minutes_watched
Content Click Other	lifetime.post_content_clicks_other
Shares	lifetime.shares_count
Subscribers Gained	lifetime.subscribers_gained
Subscribers Lost	lifetime.subscribers_lost
YT Red Video Views	lifetime.red_video_views
Video Views	lifetime.video_views
Video Likes	lifetime.likes
Video Dislikes	lifetime.dislikes
Video Reactions	lifetime.reactions
Video Comments	lifetime.comments_count
Video Added to Playlist	lifetime.videos_added_to_playlist
Video From to Playlist	lifetime.videos_removed_from_playlist

YouTube: Calculated Post Metrics

The following metrics are derived from post metrics:

• Content Click Other = Annotation Clicks + Card Clicks
• Video Reactions = Likes + Dislikes
• (Sprout’s default) Video Engagements = Comments + Likes + Dislikes + Shares + Subscribers Gained + Annotation Clicks + Card Clicks
• (Sprout’s default) Video Engagements Per View = Video Engagements/Video Views

Pinterest

Pinterest: Owned Profile Metrics

Metric	Key
Followers Count	lifetime_snapshot.followers_count
Following Count	lifetime_snapshot.following_count
Followers Gained	followers_gained
Followers Lost	followers_lost
Net Follower Growth	net_follower_growth
Net Following Growth	net_following_growth
Pin Count	pin_count
Pin Sent	inbox_counts_sent
Pin Received	inbox_received_sent

Pinterest: Calculated Post Metrics

The following metrics are derived from owned profile metrics:

• Net Follower Growth = Followers Gained - Followers Lost

Pinterest: Post Metrics

Metric	Key
Comments	lifetime.comments_count
Pin Saves	lifetime.saves

TikTok

TikTok: Owned Profile Metrics

Metric	Key
Comments	comments_count_total
Followers By Country	lifetime_snapshot.followers_by_country
Followers By Gender	lifetime_snapshot.followers_by_gender
Followers Count	lifetime_snapshot.followers_count
Followers Online	lifetime_snapshot.followers_online
Likes	likes_total
Net Follower Growth	net_follower_growth
Published Posts by Post Type	posts_sent_by_post_type
Published Post	posts_sent_count
Profiles Views	profile_views_total
Shares	shares_count_total
Video Views	video_views_total

TikTok: Calculated Profile Metrics

The following metrics are derived from owned profile metrics:

• (Sprout’s default) Engagements = Likes + Comments + Shares
• Engagement Rate (per Impression) = Engagements / Impressions

TikTok: Post Metrics

Metric	Key
Average Video Time Watched	lifetime.video_view_time_per_view
Comments	lifetime.comments_count
Full Video Watch Rate	lifetime.video_views_p100_per_view
Impression Source Follow	lifetime.impression_source_follow
Impression Source For You	lifetime.impression_source_for_you
Impression Source Hashtag	lifetime.impression_source_hashtag
Impression Source Personal Profile	lifetime.impression_source_personal_profile
Impression Source Sound	lifetime.impression_source_sound
Impression Source Unspecified	lifetime.impression_source_unspecified
Likes	lifetime.likes
Reach	lifetime.impressions_unique
Reactions	lifetime.reactions
Shares	lifetime.shares_count
Video Length	video_length
Video View Time	lifetime.video_view_time
Video Views	lifetime.video_views

TikTok: Calculated Post Metrics

The following metrics are derived from owned post metrics:

• (Sprout’s default) Engagements = Likes + Comments + Shares
• Engagement Rate (per Impression) = Engagements / Impressions

Sprout Tableau Connector

Available Data Overview

✅  The Tableau Connector uses the Sprout API to bring social data into Tableau. The metrics and data points pull directly from those available in the Sprout API. Of the data available via the Sprout API data, these tables are directly available in Tableau:

• ✅  Owned Profile Data - This matches the data available in Sprout’s Profile Performance, Twitter Profiles, Facebook Pages, Instagram Business Profiles, LinkedIn Pages, Pinterest Profiles, TikTok Profiles and YouTube Videos Report.
• ✅  Post Data - This matches the data available in Sprout’s Post Performance Report.
• ✅  Tag Data - This matches the tags represented in Sprout’s Tag Performance Report. Tag data can be combined with Post Data to fully analyze tagged posts.

🚫  The Sprout Tableau Connector does not currently include:

• 🚫  Messages data
• 🚫  Data Unsupported in Sprout API. For more details reference the Available Data Overview section of this doc.

Access Requirements

In order to access the Sprout Tableau Connector users must:

1. Have access to the Sprout API and a valid API Key. For more details reference the Creating an Access Token section of this doc
2. Have access to Tableau

Connection Set Up

1. Open Tableau

2. Select Data > New Data Source

3. Select a Web Data Connector

4. Input Connector URL https://api.sproutsocial.com/tableau/

   

5. Paste in API Key, Chose Date Range, and Select "Connect".

   

6. Select a Standard Connection (Post, Profile, Tag) or individual data tables

   

*Note that the Tableau connector does not support IPv6. Please use IPv4, or enable IPv6<->IPv4 translation.