---
title: "Synchronize external posts"
method: POST
path: "/v1/posts/sync-external"
tags: ["Analytics"]
---

# Synchronize external posts

`POST /v1/posts/sync-external`

## Request

- Base URL: `https://api.postzen.dev`
- URL: `https://api.postzen.dev/v1/posts/sync-external`
- Auth: HTTP bearer

Fetches an account's latest posts published directly on its platform. Supplying `url` or `postId` searches for a specific post. Requests made within the per-account debounce window return cached results with `synced.skipped` set to true.

## Request body

- SyncExternalPostsRequest
  - `accountId` string, required
  - `url` string, uri: Optional platform post URL to locate.
  - `postId` string: Optional platform post id to locate.

## Response `200`

External posts synchronized or served from the debounce cache.

- SyncExternalPostsResponse
  - `synced` object, required
    - `postsFound` number, required
    - `postsSynced` number, required
    - `skipped` boolean, required
  - `found` boolean, required
  - `post` ExternalSyncedPost, required
    - `platform` 'x' | 'instagram' | 'tiktok' | 'linkedin' | 'facebook' | 'youtube' | 'threads' | 'pinterest' | 'bluesky' | 'telegram', required
    - `platformPostId` string, required
    - `platformPostUrl` string, uri, required
    - `content` string, required
    - `publishedAt` string, date-time, required
    - `mediaType` string, required
    - `mediaUrl` string, uri, required
    - `thumbnailUrl` string, uri, required
    - `mediaItems` AnalyticsMediaItem[], required
      - `type` string, required
      - `url` string, uri, required
      - `thumbnail` string, uri, required
    - `analytics` AnalyticsMetrics, required: The eight normalized metrics returned for every platform. A platform that reports a single view count returns it in both `views` and `impressions`. A metric the platform does not report is returned as `0`, so check the per-platform coverage in the API reference before reading a zero as no activity. `reach` is currently reported for Instagram only.
      - `impressions` number, required
      - `reach` number, required
      - `likes` number, required
      - `comments` number, required
      - `shares` number, required
      - `saves` number, required
      - `clicks` number, required
      - `views` number, required
      - `engagementRate` number, required: Interactions (likes + comments + shares + saves + clicks) divided by impressions, multiplied by 100 and rounded to two decimals. On platforms that report no impressions, such as Bluesky, the value is the interaction count multiplied by 100 and is not a rate.
      - `lastUpdated` string, date-time, nullable, required
  - `posts` ExternalSyncedPost[], required
    - `platform` 'x' | 'instagram' | 'tiktok' | 'linkedin' | 'facebook' | 'youtube' | 'threads' | 'pinterest' | 'bluesky' | 'telegram', required
    - `platformPostId` string, required
    - `platformPostUrl` string, uri, required
    - `content` string, required
    - `publishedAt` string, date-time, required
    - `mediaType` string, required
    - `mediaUrl` string, uri, required
    - `thumbnailUrl` string, uri, required
    - `mediaItems` AnalyticsMediaItem[], required
      - `type` string, required
      - `url` string, uri, required
      - `thumbnail` string, uri, required
    - `analytics` AnalyticsMetrics, required: The eight normalized metrics returned for every platform. A platform that reports a single view count returns it in both `views` and `impressions`. A metric the platform does not report is returned as `0`, so check the per-platform coverage in the API reference before reading a zero as no activity. `reach` is currently reported for Instagram only.
      - `impressions` number, required
      - `reach` number, required
      - `likes` number, required
      - `comments` number, required
      - `shares` number, required
      - `saves` number, required
      - `clicks` number, required
      - `views` number, required
      - `engagementRate` number, required: Interactions (likes + comments + shares + saves + clicks) divided by impressions, multiplied by 100 and rounded to two decimals. On platforms that report no impressions, such as Bluesky, the value is the interaction count multiplied by 100 and is not a rate.
      - `lastUpdated` string, date-time, nullable, required

## Other responses

- `400`: Invalid request, unsupported platform, or platform synchronization failure.
- `401`: Missing or invalid API key.
- `402`: Analytics entitlement required.
- `403`: The API key does not have sufficient permission or profile access.
- `404`: Resource not found.
- `429`: Rate limit exceeded. Retry after the interval indicated by the `Retry-After` header.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/postzen/apis/postzen-public-api.md) · [All operations](https://skmtc.dev/postzen/apis/postzen-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postzen/apis/postzen-public-api/revisions/40863e3710ec?raw)