get_post_analytics
Retrieve post-level analytics including impressions and engagements for a specified date range. Supports pagination to access all posts.
Instructions
Get post-level analytics (impressions, engagements, etc.) for posts within a date range. Supports pagination — always check paging.total_pages in the response and pull all pages. IMPORTANT: The page parameter must be in the request body, not as a URL query parameter.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| profile_ids | Yes | Array of customer_profile_id values to filter posts by. | |
| metrics | Yes | 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). | |
| created_time_start | Yes | Start of the date range in ISO 8601 format (e.g. '2026-03-23T00:00:00'). | |
| created_time_end | Yes | End of the date range in ISO 8601 format (e.g. '2026-03-30T00:00:00'). | |
| fields | No | Additional fields to include. Valid: 'created_time', 'perma_link', 'text', 'post_type'. Defaults to all if omitted. | |
| page | No | Page number (default: 1). Must be in request body, NOT URL. |
Implementation Reference
- src/index.ts:214-214 (registration)Registration of the 'get_post_analytics' tool with its name, description, and schema definition.
server.tool( - src/index.ts:219-251 (schema)Input schema for get_post_analytics: profile_ids, metrics, created_time_start/end, fields (optional), page (optional). Validated with Zod.
{ profile_ids: z .array(z.string()) .describe("Array of customer_profile_id values to filter posts by."), metrics: z .array(z.string()) .describe( "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)." ), created_time_start: z .string() .describe( "Start of the date range in ISO 8601 format (e.g. '2026-03-23T00:00:00')." ), created_time_end: z .string() .describe( "End of the date range in ISO 8601 format (e.g. '2026-03-30T00:00:00')." ), fields: z .array(z.string()) .optional() .describe( "Additional fields to include. Valid: 'created_time', 'perma_link', 'text', 'post_type'. " + "Defaults to all if omitted." ), page: z .number() .optional() .describe("Page number (default: 1). Must be in request body, NOT URL."), }, - src/index.ts:252-271 (handler)Handler function that builds the request body with filters, metrics, fields (defaults to all), and page, then POSTs to /analytics/posts.
async ({ profile_ids, metrics, created_time_start, created_time_end, fields, page }) => { const body: Record<string, unknown> = { filters: [ `customer_profile_id.eq(${profile_ids.join(", ")})`, `created_time.in(${created_time_start}..${created_time_end})`, ], metrics, }; if (fields && fields.length > 0) { body.fields = fields; } else { body.fields = ["created_time", "perma_link", "text", "post_type"]; } if (page) body.page = page; const data = await sproutRequest("POST", "/analytics/posts", body); return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] }; }