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.

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:

{}

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:

{
  "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:

{
  "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:

{
  "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