Sprout Social MCP Server

get_post_analytics

Fetch post-level metrics like impressions and engagements for a date range, with optional tag, profile, and pagination filters.

Instructions

Get post-level analytics (impressions, engagements, etc.) for posts within a date range. Supports filtering by Sprout tags via tag_ids or tagged_only. Responses include internal.tags.id by default so posts can be grouped by tag. Supports sort (e.g. lifetime.impressions:desc), timezone, page, all_pages auto-pagination, and guid_cursor for walking past the ~10k page cap. For a Tag Performance Report-style rollup, prefer get_tag_performance. IMPORTANT: The page parameter must be in the request body, not as a URL query parameter.

Input Schema

TableJSON Schema

Name	Required	Description
`page`	No	Page number (default: 1). Must be in request body, NOT URL. Ignored when all_pages is true unless starting a page walk.
`sort`	No	Sort expressions, e.g. ['lifetime.impressions:desc'] or ['created_time:asc']. Ignored when guid_cursor is set (cursor mode always sorts by guid:asc).
`limit`	No	Results per page (default 50, max 50 for posts).
`fields`	No	Additional fields to include. Valid: 'created_time', 'perma_link', 'text', 'post_type', 'network', 'customer_profile_id', 'guid', 'internal.tags.id'. Defaults to those fields if omitted.
`metrics`	Yes	Metrics to retrieve. All platforms: 'lifetime.impressions', 'lifetime.engagements', 'lifetime.reactions', 'lifetime.video_views', 'lifetime.saves', 'lifetime.comments_count', 'lifetime.post_shares_count'. Facebook only: 'lifetime.post_link_clicks', 'lifetime.post_content_clicks', 'lifetime.post_content_clicks_other'. Instagram: click metrics are NOT available (silently ignored by the API). INVALID (will error): 'lifetime.reach', 'lifetime.comments', 'lifetime.shares'.
`tag_ids`	No	Only return posts that have at least one of these Sprout tag IDs. Use get_tags to discover IDs. Filter uses internal.tags.id.eq(...).
`timezone`	No	ICANN timezone for the created_time filter (e.g. 'America/New_York'). Response timestamps stay in UTC.
`all_pages`	No	If true, follow pagination automatically and return every post up to max_pages. Uses page numbers, or guid_cursor walks when guid_cursor is provided.
`max_pages`	No	Cap on pages fetched when all_pages is true (default 40, 50 posts per page).
`guid_cursor`	No	Last post guid from a previous page. Uses guid.gt(...) so you can walk past the ~10k page-number cap. Pass the last guid from the prior response and keep calling until an empty page.
`profile_ids`	Yes	Array of customer_profile_id values to filter posts by.
`tagged_only`	No	If true, only return posts that have at least one tag. Ignored when tag_ids is provided.
`created_time_end`	Yes	End of the date range in ISO 8601 format (e.g. '2026-03-30T00:00:00').
`created_time_start`	Yes	Start of the date range in ISO 8601 format (e.g. '2026-03-23T00:00:00').

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedv1.0.3Sep 9, 2026

addedInput schema / properties / all_pages

Added value: +{
+  "description": "If true, follow pagination automatically and return every post up to max_pages. Uses page numbers, or guid_cursor walks when guid_cursor is provided.",
+  "type": "boolean"
+}

changedInput schema / properties / fields / description

Previous value: -"Additional fields to include. Valid: 'created_time', 'perma_link', 'text', 'post_type'. Defaults to all if omitted."New value: +"Additional fields to include. Valid: 'created_time', 'perma_link', 'text', 'post_type', 'network', 'customer_profile_id', 'guid', 'internal.tags.id'. Defaults to those fields if omitted."

addedInput schema / properties / guid_cursor

Added value: +{
+  "description": "Last post guid from a previous page. Uses guid.gt(...) so you can walk past the ~10k page-number cap. Pass the last guid from the prior response and keep calling until an empty page.",
+  "type": "string"
+}

addedInput schema / properties / limit

Added value: +{
+  "description": "Results per page (default 50, max 50 for posts).",
+  "type": "number"
+}

addedInput schema / properties / max_pages

Added value: +{
+  "description": "Cap on pages fetched when all_pages is true (default 40, 50 posts per page).",
+  "type": "number"
+}

changedInput schema / properties / page / description

Previous value: -"Page number (default: 1). Must be in request body, NOT URL."New value: +"Page number (default: 1). Must be in request body, NOT URL. Ignored when all_pages is true unless starting a page walk."

addedInput schema / properties / sort

Added value: +{
+  "description": "Sort expressions, e.g. ['lifetime.impressions:desc'] or ['created_time:asc']. Ignored when guid_cursor is set (cursor mode always sorts by guid:asc).",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / tag_ids

Added value: +{
+  "description": "Only return posts that have at least one of these Sprout tag IDs. Use get_tags to discover IDs. Filter uses internal.tags.id.eq(...).",
+  "items": {
+    "type": [
+      "string",
+      "number"
+    ]
+  },
+  "type": "array"
+}

addedInput schema / properties / tagged_only

Added value: +{
+  "description": "If true, only return posts that have at least one tag. Ignored when tag_ids is provided.",
+  "type": "boolean"
+}

addedInput schema / properties / timezone

Added value: +{
+  "description": "ICANN timezone for the created_time filter (e.g. 'America/New_York'). Response timestamps stay in UTC.",
+  "type": "string"
+}

Changed1 schema field changedv1.0.1May 27, 2026

changedInput schema / properties / metrics / description

Previous value: -"Metrics to retrieve. Valid options: 'lifetime.impressions', 'lifetime.engagements', 'lifetime.reactions', 'lifetime.video_views'. Do NOT request: 'lifetime.comments', 'lifetime.shares', 'lifetime.reach' (these are invalid)."New value: +"Metrics to retrieve. All platforms: 'lifetime.impressions', 'lifetime.engagements', 'lifetime.reactions', 'lifetime.video_views', 'lifetime.saves', 'lifetime.comments_count', 'lifetime.post_shares_count'. Facebook only: 'lifetime.post_link_clicks', 'lifetime.post_content_clicks', 'lifetime.post_content_clicks_other'. Instagram: click metrics are NOT available (silently ignored by the API). INVALID (will error): 'lifetime.reach', 'lifetime.comments', 'lifetime.shares'."

First observedv1.0.0May 6, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries full responsibility. It transparently explains ignored parameters, invalid metrics, the ~10k pagination cap, timezone behavior, and the fact that Instagram click metrics are silently ignored.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, with every sentence contributing useful operational detail. The 'IMPORTANT' note draws attention to a critical requirement without unnecessary verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description thoroughly covers request semantics, pagination, filtering, and alternatives. It does not describe the response shape beyond mentioning that internal.tags.id is included by default, but given the absence of an output schema, the description is still largely complete for invoking the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100% and detailed, but the description adds important behavioral meaning beyond the schema: body-vs-URL placement, ignored sort when guid_cursor is set, default fields, invalid metric names, and pagination semantics. This significantly helps an agent choose and populate parameters correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves post-level analytics with a specific resource (posts) and scope (date range). It also differentiates from get_tag_performance by calling out that a Tag Performance rollup should use that alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance for the pagination parameter placement, the special behavior of guid_cursor, and references get_tag_performance as a preferred alternative for rollup-style queries. It doesn't explicitly contrast with every sibling like get_profile_analytics or get_messages, but the core usage context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

get_post_analytics

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools