Get Analytics

Retrieve performance metrics for your social media posts across all connected platforms.

Endpoint

GET https://api.postpeer.dev/v1/analytics

With postId, returns analytics for a single post. Without postId, returns a paginated list of published posts with analytics. Accepts both PostPeer post IDs and external platform post IDs (auto-resolved).

Each call costs 1 credit.

Query Parameters

Parameter	Type	Required	Description
`postId`	string	No	PostPeer post ID or external platform post ID (auto-resolved). When omitted, returns a paginated list of all published posts with analytics.
`platform`	string	No	Filter by platform: `twitter`, `instagram`, `youtube`, `tiktok`, `pinterest`, `linkedin`. Required for external ID lookups.
`accountId`	string	No	Integration ID. Required for external ID lookups and `source=platform`.
`source`	string	No	`"postpeer"` (posts published via PostPeer, stored in our DB) or `"platform"` (fetched directly from the connected platform account). Omit to include all sources.
`fromDate`	string	No	Inclusive start date (`YYYY-MM-DD`). Defaults to 90 days ago.
`toDate`	string	No	Inclusive end date (`YYYY-MM-DD`). Defaults to today. Max range: 366 days.
`sortBy`	string	No	Sort by: `date`, `likes`, `comments`, `impressions`, `views`, `shares`, `saves`, `clicks`, `engagement`.
`order`	string	No	`asc` or `desc`.
`limit`	integer	No	Page size (1-100).
`page`	integer	No	Page number.

Usage Modes

Mode 1: Single Post (PostPeer ID)

Pass a PostPeer postId to get metrics for a specific post across all platforms it was published to.

curl "https://api.postpeer.dev/v1/analytics?postId=69e0893109e2c65ae5957084" \
  -H "x-access-key: YOUR_API_KEY"

{
  "success": true,
  "post": {
    "source": "postpeer",
    "postId": "69e0893109e2c65ae5957084",
    "content": "Hello world!",
    "publishedAt": "2026-04-16T20:56:00.747Z",
    "aggregated": {
      "impressions": 25,
      "reach": null,
      "likes": 1,
      "comments": 0,
      "shares": null,
      "saves": 0,
      "clicks": null,
      "views": null,
      "engagementRate": null
    },
    "platforms": [
      {
        "platform": "twitter",
        "platformPostId": "2044882524506136582",
        "platformPostUrl": "https://twitter.com/user/status/2044882524506136582",
        "metrics": {
          "impressions": 25,
          "reach": null,
          "likes": 1,
          "comments": 0,
          "shares": null,
          "saves": 0,
          "clicks": null,
          "views": null,
          "engagementRate": null
        }
      }
    ]
  }
}

Mode 2: External ID (Auto-Resolved)

Pass any external platform post ID (tweet ID, YouTube video ID, Pinterest pin ID). PostPeer first searches your posts by that ID. If not found, provide platform and accountId to fetch directly from the platform API. When the post is fetched directly, source is "platform" and postId is null.

curl "https://api.postpeer.dev/v1/analytics?postId=2045080886845005934&platform=twitter&accountId=69da6882322e75b602ad2916" \
  -H "x-access-key: YOUR_API_KEY"

{
  "success": true,
  "post": {
    "source": "platform",
    "postId": null,
    "content": null,
    "publishedAt": null,
    "aggregated": {
      "impressions": 22,
      "reach": null,
      "likes": 1,
      "comments": 1,
      "shares": null,
      "saves": 0,
      "clicks": null,
      "views": null,
      "engagementRate": null
    },
    "platforms": [
      {
        "platform": "twitter",
        "platformPostId": "2045080886845005934",
        "platformPostUrl": null,
        "metrics": {
          "impressions": 22,
          "reach": null,
          "likes": 1,
          "comments": 1,
          "shares": null,
          "saves": 0,
          "clicks": null,
          "views": null,
          "engagementRate": null
        }
      }
    ]
  }
}

Mode 3: Paginated List

Omit postId to get analytics for all your published posts. Combine with platform, date range, and sorting.

curl "https://api.postpeer.dev/v1/analytics?platform=twitter&fromDate=2026-04-10&toDate=2026-04-17&sortBy=likes&order=desc&limit=10" \
  -H "x-access-key: YOUR_API_KEY"

{
  "success": true,
  "total": 43,
  "page": 1,
  "limit": 10,
  "posts": [
    {
      "source": "postpeer",
      "postId": "69e0893109e2c65ae5957084",
      "content": "Hello world!",
      "publishedAt": "2026-04-16T20:56:00.747Z",
      "aggregated": {
        "impressions": 25,
        "reach": null,
        "likes": 1,
        "comments": 0,
        "shares": null,
        "saves": 0,
        "clicks": null,
        "views": null,
        "engagementRate": null
      },
      "platforms": [
        {
          "platform": "twitter",
          "platformPostId": "2044882524506136582",
          "platformPostUrl": "https://twitter.com/user/status/2044882524506136582",
          "metrics": { "...": "..." }
        }
      ]
    }
  ]
}

Mode 4: Account Posts (from platform directly)

Set source=platform with accountId to fetch recent posts directly from the platform — including posts not published through PostPeer. Each result has source: "platform" and postId: null.

curl "https://api.postpeer.dev/v1/analytics?source=platform&accountId=69e2275c1d7a0d479237fa67&platform=pinterest&limit=10" \
  -H "x-access-key: YOUR_API_KEY"

{
  "success": true,
  "total": 2,
  "page": 1,
  "limit": 10,
  "posts": [
    {
      "source": "platform",
      "postId": null,
      "content": "PostPeer OG",
      "publishedAt": "2026-04-12T07:28:45Z",
      "aggregated": {
        "impressions": 4,
        "reach": null,
        "likes": 0,
        "comments": 0,
        "shares": null,
        "saves": 0,
        "clicks": 1,
        "views": null,
        "engagementRate": null
      },
      "platforms": [
        {
          "platform": "pinterest",
          "platformPostId": "1143210686684505466",
          "platformPostUrl": "https://www.pinterest.com/pin/1143210686684505466/",
          "metrics": { "...": "..." }
        }
      ]
    }
  ]
}

Supported platforms for source=platform: Twitter, YouTube, Pinterest.

ID Resolution Order

When you pass a postId, PostPeer resolves it in this order:

Try as a PostPeer post ID (MongoDB ObjectId)
Search PostPeer posts where platformPostId matches (auto-resolve external ID)
If platform + accountId are also provided, fetch directly from the platform API

Metrics by Platform

All metrics use a unified schema. Fields return null when the platform doesn't support that metric.

Metric	Twitter	YouTube	Pinterest	LinkedIn
`impressions`	yes	—	yes	needs scope
`reach`	—	—	—	needs scope
`likes`	yes	yes	yes (reactions)	needs scope
`comments`	yes (replies)	yes	yes	needs scope
`shares`	yes (RT + quotes)	—	—	needs scope
`saves`	yes (bookmarks)	—	yes	—
`clicks`	yes (url clicks)	—	yes (outbound + pin)	—
`views`	—	yes	—	—
`engagementRate`	—	—	—	—

LinkedIn analytics requires the r_member_postAnalytics OAuth scope. If your LinkedIn account was connected without this scope, analytics will return null. Reconnect with the required permission to enable LinkedIn analytics.

Status Codes

Code	Meaning
`200`	Success
`400`	Invalid query parameters (e.g. date range exceeds 366 days)
`402`	Not enough credits
`404`	Post not found

Error Response

{
  "success": false,
  "message": "Date range cannot exceed 366 days."
}

On this page