get_post_analytics

Instructions

Implementation Reference

• src/tools/posts.ts:237-249 (handler)

  The async handler function that executes the 'get_post_analytics' tool logic. Calls client.get<AnalyticsResponse>('/social-posts/analytics', ...) with startDate, endDate, optional platforms, and optional socialMediaIds query parameters, then returns the JSON-stringified response.

    async (input) => {
      const data = await client.get<AnalyticsResponse>('/social-posts/analytics', {
        startDate: input.startDate,
        endDate: input.endDate,
        platforms: input.platforms?.join(','),
        socialMediaIds: input.socialMediaIds?.join(','),
      });
  
      return {
        content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }],
      };
    },
  );

• src/tools/posts.ts:222-236 (schema)

  Zod schema definitions for the 'get_post_analytics' input parameters: startDate (ISO 8601 string), endDate (ISO 8601 string), optional platforms (array of platform enum values), optional socialMediaIds (array of UUID strings).

    startDate: z
      .string()
      .describe('Start of date range (ISO 8601, e.g. 2026-01-01T00:00:00.000Z)'),
    endDate: z
      .string()
      .describe('End of date range (ISO 8601, e.g. 2026-01-31T23:59:59.999Z)'),
    platforms: z
      .array(z.enum(PLATFORMS))
      .optional()
      .describe('Filter by platforms'),
    socialMediaIds: z
      .array(z.string().uuid())
      .optional()
      .describe('Filter by specific social media account IDs'),
  },

• src/tools/posts.ts:218-249 (registration)

  Registration of the 'get_post_analytics' tool via server.tool() with its name, description, input schema, and handler.

  server.tool(
    'get_post_analytics',
    'Fetch published posts with their latest performance metrics (impressions, reach, likes, comments, shares). Only returns published posts that have a platform post ID. LinkedIn personal accounts are excluded. Supported: Instagram, Facebook, TikTok, Threads, YouTube, LinkedIn (company pages), Pinterest (Business accounts). Pinterest extras include pin_clicks, outbound_clicks, saves_90d, save_rate_90d (saves are 90-day rolling because Pinterest API does not expose lifetime totals); video pins additionally surface mrc_views, views_10s, avg_watch_time, v50_watch_time, video_starts, quartile_95_views.',
    {
      startDate: z
        .string()
        .describe('Start of date range (ISO 8601, e.g. 2026-01-01T00:00:00.000Z)'),
      endDate: z
        .string()
        .describe('End of date range (ISO 8601, e.g. 2026-01-31T23:59:59.999Z)'),
      platforms: z
        .array(z.enum(PLATFORMS))
        .optional()
        .describe('Filter by platforms'),
      socialMediaIds: z
        .array(z.string().uuid())
        .optional()
        .describe('Filter by specific social media account IDs'),
    },
    async (input) => {
      const data = await client.get<AnalyticsResponse>('/social-posts/analytics', {
        startDate: input.startDate,
        endDate: input.endDate,
        platforms: input.platforms?.join(','),
        socialMediaIds: input.socialMediaIds?.join(','),
      });
  
      return {
        content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }],
      };
    },
  );

• src/types.ts:91-100 (schema)

  PostMetric interface defining the shape of individual post metrics returned by the analytics endpoint (impressions, reach, likes, comments, shares, totalInteractions, fetchedAt, extras).

  export interface PostMetric {
    impressions: string;
    reach: string;
    likes: string;
    comments: string;
    shares: string;
    totalInteractions: string;
    fetchedAt: string;
    extras: Record<string, unknown>;
  }

• src/types.ts:102-113 (schema)

  AnalyticsPost and AnalyticsResponse interfaces defining the shape of the API response for the analytics endpoint.

  export interface AnalyticsPost {
    id: string;
    content: string;
    socialMediaId: string;
    platformPostId: string;
    publishedAt: string;
    latestMetric: PostMetric | null;
  }
  
  export interface AnalyticsResponse {
    data: AnalyticsPost[];
  }