# Sprout Social

> Integrate with Sprout Social Listening API to access social media listening data, messages, and aggregated metrics.

Source: https://cotera.co/docs/reference/tools/individual-tools/sprout-social

---

**Authentication Type:** API Key
**Description:** Integrate with Sprout Social Listening API to access social media listening data, query messages from listening topics, and retrieve aggregated metrics for trend analysis and dashboards.

***

## Authentication

To authenticate, you'll need a Sprout Social API key. Learn how to create one in the [Sprout Social API documentation](https://api.sproutsocial.com/docs/#using-api-tokens).

***

## Metadata

Operations for discovering customer and topic information.

### Get Customers

Retrieves the list of customers (accounts) accessible with your API key.

**Operation Type:** Query (Read)

**Parameters:**

None required.

**Returns:**

* **customers** `array of objects`: List of customers accessible with your API key
  * **customerId** `number`: The unique customer ID
  * **name** `string`: The customer/business name

**Example Usage:**

```json
{}
```

### Get Topics

Retrieves the list of Listening Topics for a specific customer.

**Operation Type:** Query (Read)

**Parameters:**

* **customerId** `string` (required): Your Sprout Social customer ID. Obtain this from the Get Customers operation.

**Returns:**

* **topics** `array of objects`: List of Listening Topics for the customer
  * **topicId** `string`: The unique topic ID
  * **name** `string`: The topic name

**Example Usage:**

```json
{
  "customerId": "2068076"
}
```

***

## Listening

Operations for querying listening data from topics.

### Get Messages

Query messages within a Sprout Social Listening Topic. Returns individual messages with requested fields and metrics. Use for extracting raw messages for analysis or displaying sample content.

**Operation Type:** Query (Read)

**Parameters:**

* **customerId** `string` (required): Your Sprout Social customer ID
* **topicId** `string` (required): The Listening Topic ID to query
* **filters** `array of strings` (nullable): Filter criteria using Sprout filter syntax. Examples: `"created_time.in(2023-01-01..2023-02-01)"`, `"network.eq(INSTAGRAM,TWITTER)"`, `"sentiment.eq(positive)"`, `"text.match(keyword)"`
* **fields** `array of strings` (nullable): Fields to return. Examples: `content_category`, `created_time`, `hashtags`, `language`, `location.city`, `location.country`, `from.name`
* **metrics** `array of strings` (nullable): Metrics to return for each message. Examples: `engagements`, `likes`, `replies`, `shares_count`, `from.followers_count`
* **page** `number` (nullable): 1-indexed page number for pagination
* **limit** `number` (nullable): Max results per page (max: 100, default: 50)
* **sort** `array of strings` (nullable): Sort order as "field:direction". Example: `["created_time:desc"]`
* **timezone** `string` (nullable): ICANN timezone for date filters. Example: `"America/Chicago"`

**Returns:**

* **data** `array of objects`: Array of matching messages
  * **guid** `string`: Unique message identifier
  * **text** `string`: Message content
  * **permaLink** `string`: Permanent URL to the message
  * **network** `string`: Social network (INSTAGRAM, TWITTER, YOUTUBE, etc.)
  * **contentCategory** `string` (nullable): Content type (PHOTO, VIDEO, etc.)
  * **createdTime** `string`: ISO timestamp when created
  * **hashtags** `array of strings` (nullable): Hashtags in the message
  * **visualMedia** `array of objects` (nullable): Media attachments
    * **mediaUrl** `string`: URL to the media
    * **mediaType** `string`: Type of media (PHOTO, VIDEO, etc.)
  * **listeningMetadata** `object` (nullable): Sentiment and classification data
    * **sentiment** `string`: Sentiment classification (positive, negative, neutral, unclassified)
    * **explicitLabel** `boolean`: Whether content is explicit
    * **language** `string`: Language code (e.g., en)
  * **metrics** `object` (nullable): Requested metrics for the message
* **paging** `object`: Pagination information
  * **currentPage** `number`: 1-indexed page number
  * **totalPages** `number` (nullable): Total number of pages

**Example Usage:**

```json
{
  "customerId": "2068076",
  "topicId": "51fc08f5-7cf8-445d-91c4-8b4d3a15788d",
  "filters": ["created_time.in(2025-01-01..2025-01-31)", "sentiment.eq(positive)"],
  "fields": ["created_time", "text", "network", "hashtags"],
  "metrics": ["engagements", "likes"],
  "page": 1,
  "limit": 50,
  "sort": ["created_time:desc"],
  "timezone": "America/Chicago"
}
```

### Get Metrics

Aggregate metrics across a Sprout Social Listening Topic. Returns aggregated data that can be bucketed by dimensions like time, sentiment, or network. Use for quick insights, trend analysis, or building dashboards.

**Operation Type:** Query (Read)

**Parameters:**

* **customerId** `string` (required): Your Sprout Social customer ID
* **topicId** `string` (required): The Listening Topic ID to query
* **filters** `array of strings` (nullable): Filter criteria using Sprout filter syntax. Examples: `"created_time.in(2023-01-01..2023-02-01)"`, `"network.eq(INSTAGRAM,TWITTER)"`, `"sentiment.eq(positive)"`
* **metrics** `array of strings` (nullable): Metrics to aggregate. Examples: `replies`, `shares_count`, `likes`, `engagements`, `impressions`, `authors_count`
* **dimensions** `array of strings` (nullable): Dimensions to bucket metrics by. Examples: `"created_time.by(day)"`, `"created_time.by(month)"`, `sentiment`, `network`, `language`, `location.country`
* **timezone** `string` (nullable): ICANN timezone for date filters. Example: `"America/Chicago"`
* **limit** `number` (nullable): Max number of metric objects to return

**Returns:**

* **data** `array of objects`: Array of metric buckets
  * **dimensions** `object` (nullable): Dimension values for this bucket
  * **metrics** `object`: Aggregated metric values

**Example Usage:**

```json
{
  "customerId": "2068076",
  "topicId": "51fc08f5-7cf8-445d-91c4-8b4d3a15788d",
  "filters": ["created_time.in(2025-01-01..2025-01-31)"],
  "metrics": ["replies", "shares_count", "likes", "engagements", "authors_count"],
  "dimensions": ["created_time.by(day)", "sentiment"],
  "timezone": "America/Chicago",
  "limit": 100
}
```

***

## Common Use Cases

**Brand Monitoring:**

* Track brand mentions across social media platforms
* Monitor sentiment trends over time
* Identify influential voices talking about your brand

**Competitive Intelligence:**

* Compare share of voice across competitors
* Analyze competitor campaign performance
* Track industry trends and conversations

**Campaign Analysis:**

* Measure campaign reach and engagement
* Track hashtag performance during campaigns
* Analyze audience sentiment toward campaigns

**Social Listening Reports:**

* Build automated dashboards with aggregated metrics
* Generate periodic listening reports
* Track KPIs like engagement rate and sentiment distribution