Developers

Analytics

Read performance for a post or a channel. Both endpoints route through the same compute the dashboard uses, so the numbers match what the UI shows; we never read raw insight rows directly. Scope analytics:read.

A fresh post reads 0, and that's expected

Metrics come from periodic polls of each platform, not from the publish call. A brand-new post legitimately reads 0 across the board until the first poll lands. That is the pipeline warming up, not a bug. Polling is most frequent in the first 24 hours and slows after that, so don't treat an early zero as a failure; re-read a little later.

Post insights

GET/api/v1/posts/{id}/insights

Cumulative-to-date metrics for a published post: workspace totals plus a per-channel breakdown. The post id is the one from POST /posts; a post in another workspace reads 404.

bash
curl https://postme.live/api/v1/posts/7d0a8b1c-2e3f-4a5b-9c0d-1e2f3a4b5c6d/insights \
  -H "Authorization: Bearer pml_live_..."

Response: 200 OK

json
{
  "post_id": "7d0a8b1c-2e3f-4a5b-9c0d-1e2f3a4b5c6d",
  "totals": {
    "views": 4120,
    "engagements": 318,
    "reach": 3890,
    "impressions": 5012,
    "likes": 271,
    "comments": 22,
    "shares": 14,
    "saves": 11,
    "watch_time_seconds": 8640
  },
  "channels": [
    {
      "channel_id": "5a1d6e7f-8a9b-4c0d-1e2f-3a4b5c6d7e8f",
      "platform": "meta_instagram",
      "views": 2980,
      "engagements": 240,
      "reach": 2810,
      "likes": 205,
      "comments": 18,
      "shares": 9,
      "saves": 8
    },
    {
      "channel_id": "6b2e7f8a-9b0c-4d1e-2f3a-4b5c6d7e8f90",
      "platform": "youtube",
      "views": 1140,
      "engagements": 78,
      "reach": 1080,
      "likes": 66,
      "comments": 4,
      "shares": 5,
      "saves": 3
    }
  ],
  "updated_at": "2026-06-28T09:14:22Z"
}

totals is the sum across channels; the per-channel block omits impressions and watch_time_seconds (those roll up at the post level only). updated_at is the freshest snapshot time across channels, or null if the post has never been polled.

Channel insights

GET/api/v1/channels/{id}/insights

Windowed totals for one channel, plus its current follower count. Pass ?range=24h | 7d | 28d; anything else (or an omitted value) defaults to 28d. A channel in another workspace reads 404.

bash
curl "https://postme.live/api/v1/channels/5a1d6e7f-8a9b-4c0d-1e2f-3a4b5c6d7e8f/insights?range=7d" \
  -H "Authorization: Bearer pml_live_..."

Response: 200 OK

json
{
  "channel_id": "5a1d6e7f-8a9b-4c0d-1e2f-3a4b5c6d7e8f",
  "platform": "meta_instagram",
  "window": {
    "range": "7d",
    "start": "2026-06-21T09:14:22Z",
    "end": "2026-06-28T09:14:22Z"
  },
  "totals": {
    "views": 18240,
    "engagements": 1412,
    "reach": 16890,
    "likes": 1180,
    "comments": 96,
    "shares": 71,
    "saves": 65,
    "watch_time_seconds": 41280
  },
  "source": "channel",
  "followers": 8421
}

Field reference

FieldTypeNotes
window.range24h | 7d | 28dThe range you asked for (echoed back).
window.start / window.endRFC-3339The exact UTC window the totals cover.
totalsobjectSummed over the window.
sourcechannel | posts | noneWhere the numbers came from: channel = native channel-level data, posts = a rollup of the window's posts, none = no data yet.
followersnumber | nullCurrent follower count from the latest account-stats poll, or null if not yet known.
Analytics: Public API