---
title: "List the user's recent posts fetched live from the connected platforms"
method: GET
path: "/posts/recent-platform"
tags: ["Posts"]
---

# List the user's recent posts fetched live from the connected platforms

`GET /posts/recent-platform`

Returns the most recent posts pulled directly from each connected platform's API (Instagram, TikTok, X, YouTube, Facebook, LinkedIn, and more), including content that was published outside OmniSocials. This is the fallback for brand-new workspaces that have not published anything through OmniSocials yet, so GET /posts (which only lists OmniSocials posts) comes back empty. Each post is enriched with normalized `engagement` / `impressions` / `engagement_rate` so you can rank across platforms without re-deriving per-platform rules. Metrics are only present where the platform exposes them for historical posts: X, TikTok (views/likes/comments/shares, plus `average_time_watched`, `full_video_watched_rate`, `total_time_watched`, `favorites`, `reach` when the workspace enabled TikTok comments — the Business API authorization), Bluesky, Mastodon, Instagram (likes/comments/reach/views/saves/shares, via one insights call per post), Facebook, and YouTube return counts, while Threads, Pinterest, and Google Business return captions only (`metrics: {}`). LinkedIn personal profiles cannot be listed live (LinkedIn grants no such permission to apps), so their results contain posts published through OmniSocials with their latest collected stats; TikTok results are backfilled the same way for photo posts the video list omits. Fetched live on every call for most platforms — expect a few seconds of latency across many platforms. X is the exception: because X's API bills every returned post, X results may be served from a snapshot up to 24 hours old. The snapshot refreshes immediately after you publish to X through OmniSocials, so your own new posts always appear. Requires the `analytics:read` scope.

## Query parameters

- `limit` integer
- `platforms` string

## Response `200`

Recent posts across connected platforms, newest first

- object
  - `data` object[]
    - `platform` string
    - `id` string, nullable — The platform's own native post/media id (NOT the OmniSocials Post id). Use this as the stable key to store and de-duplicate each post when ingesting native content.
    - `permalink` string, nullable — Public URL of the post on the platform. Present for Instagram, Facebook, Threads, TikTok, YouTube, X, Pinterest, Mastodon, Bluesky, and LinkedIn; null where the platform's listing API exposes no URL (e.g. Google Business) or one can't be built.
    - `text` string — Full, untruncated caption / post text (empty string if the post has none).
    - `format` string — post, carousel, reel, video, image, text, or pin
    - `media_count` integer
    - `timestamp` string, date-time, nullable
    - `image_url` string, nullable — Display image for the post where the platform exposes one (currently Instagram: photo, video poster, or first carousel frame). Null otherwise.
    - `duration_seconds` integer, nullable — Video length in whole seconds where the platform's listing API reports it (currently TikTok and YouTube). Null for images and for platforms that don't expose it — Instagram's media API has no duration field.
    - `metrics` object — Raw per-platform metrics as exact integers (never rounded/abbreviated); only keys the platform returned are present.
    - `engagement` number
    - `impressions` number
    - `engagement_rate` number — Percentage (0-100), suppressed below a minimum impression floor.
  - `count` integer
  - `connected_platforms` string[]
  - `errors` object — Per-platform error messages for any platform that failed to fetch.
  - `note` string
  - `current_date` string, date

## Other responses

- `400` — One or more requested platforms are not supported

---

[API](https://skmtc.dev/omnisocials/apis/omnisocials-api.md) · [All operations](https://skmtc.dev/omnisocials/apis/omnisocials-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/omnisocials/omnisocials-api/revisions/e53b89af0b98/schema)