Skip to content
Dashboard
API Reference

Get Social Post Analytics ​

Get normalized analytics for a social post.

Returns analytics for a social post with a fixed normalized shape.

Use the post_id returned by POST /social/post.

Request ​

bash
curl -X GET "https://api.mosaic.so/social/post/2d8ca860-f8e0-4f3f-9f2c-337ead6ed91e/analytics" \
  -H "Authorization: Bearer mk_your_api_key"

Query Parameters ​

FieldTypeRequiredDescription
social_connection_idstring (uuid)NoGet analytics using one specific connected account. Useful when a post targets multiple accounts on the same platform.

Response Fields ​

FieldTypeDescription
analytics.statusstring or nullAnalytics status. null if the source response does not include it.
analytics.totalsobjectFixed normalized totals object. Every metric key is always present; the value is a number or null.
analytics.platformsarrayPer-platform analytics entries.
analytics.platforms[].platformstringOne of x, linkedin, instagram, facebook, tiktok, youtube.
analytics.platforms[].platform_post_idstring or nullNative post ID from the destination platform. null if the source response does not include it.
analytics.platforms[].post_urlstring or nullPublic post URL. null if the source response does not include it.
analytics.platforms[].metricsobjectFixed normalized metric object. Every metric key is always present; the value is a number or null.
analytics.platforms[].raw_metricsobjectUnnormalized platform-specific analytics payload for clients that need fields outside the normalized contract.
analytics.metadataobjectResponse-level metadata with platform entries removed.
statsobjectBackward-compatible analytics payload. Prefer analytics for new integrations.

Metric Object ​

Every analytics.totals and analytics.platforms[].metrics object has exactly these keys:

FieldType
likesnumber or null
commentsnumber or null
sharesnumber or null
impressionsnumber or null
viewsnumber or null
video_viewsnumber or null
video_viewersnumber or null
video_watch_time_msnumber or null
engagementnumber or null
clicksnumber or null
savesnumber or null
bookmarksnumber or null
quotesnumber or null

Response ​

json
{
  "post_id": "2d8ca860-f8e0-4f3f-9f2c-337ead6ed91e",
  "platform": "x",
  "social_connection_id": "4df2f2b9-4c5f-4b3a-9581-1bcb8b4f7d01",
  "analytics": {
    "status": "success",
    "totals": {
      "likes": 42,
      "comments": 7,
      "shares": 5,
      "impressions": 18420,
      "views": 9120,
      "video_views": null,
      "video_viewers": null,
      "video_watch_time_ms": null,
      "engagement": null,
      "clicks": null,
      "saves": null,
      "bookmarks": 18,
      "quotes": 3
    },
    "platforms": [
      {
        "platform": "x",
        "platform_post_id": "1901625213503277588",
        "post_url": "https://x.com/mosaic_so/status/1901625213503277588",
        "metrics": {
          "likes": 42,
          "comments": 7,
          "shares": 5,
          "impressions": 18420,
          "views": 9120,
          "video_views": null,
          "video_viewers": null,
          "video_watch_time_ms": null,
          "engagement": null,
          "clicks": null,
          "saves": null,
          "bookmarks": 18,
          "quotes": 3
        },
        "raw_metrics": {
          "likeCount": 42,
          "replyCount": 7,
          "repostCount": 5,
          "impressionCount": 18420,
          "viewCount": 9120,
          "bookmarkCount": 18,
          "quoteCount": 3
        }
      }
    ],
    "metadata": {}
  },
  "stats": {
    "status": "success",
    "x": {
      "id": "1901625213503277588",
      "analytics": {
        "likeCount": 42,
        "replyCount": 7,
        "repostCount": 5,
        "impressionCount": 18420,
        "viewCount": 9120,
        "bookmarkCount": 18,
        "quoteCount": 3
      }
    }
  }
}

Behavior ​

  • Metrics vary by platform and account permissions. Missing normalized metrics are returned as null, not omitted and not converted to fake zeroes.
  • For posts with multiple destinations, pass social_connection_id when you need analytics for one connected account.
  • analytics.totals only sums metrics returned in this response.