---
title: "List posts"
method: GET
path: "/posts"
tags: ["Posts"]
---

# List posts

`GET /posts`

## Request

- Base URL: `https://api.postplanify.com/api/v1`
- URL: `https://api.postplanify.com/api/v1/posts`
- Auth: HTTP bearer

Returns a paginated list of posts in a workspace. Supports filtering by status, platform, social account, and date range.

## Query parameters

- `workspaceId` string, uuid, required
- `status` 'SCHEDULED' | 'PUBLISHED' | 'CANCELLED' | 'RESCHEDULED'
- `socialAccountId` string, uuid
- `platform` 'FACEBOOK' | 'INSTAGRAM' | 'X' | 'LINKEDIN' | 'TIKTOK' | 'YOUTUBE' | 'THREADS' | 'BLUESKY' | 'PINTEREST' | 'GOOGLE_BUSINESS'
- `from` string, date-time
- `to` string, date-time
- `includeMetrics` boolean
- `page` integer
- `limit` integer

## Response `200`

Paginated list of posts

- object
  - `ok` boolean
  - `data` Post[]
    - `id` string, uuid
    - `workspaceId` string, uuid
    - `caption` string, nullable
    - `status` 'SCHEDULED' | 'PUBLISHED' | 'CANCELLED' | 'RESCHEDULED'
    - `platform` 'FACEBOOK' | 'INSTAGRAM' | 'X' | 'LINKEDIN' | 'TIKTOK' | 'YOUTUBE' | 'THREADS' | 'BLUESKY' | 'PINTEREST' | 'GOOGLE_BUSINESS'
    - `socialPlatformPostId` string, nullable: The native post ID on the social platform
    - `isStory` boolean
    - `shortenLinks` boolean: Whether links are shortened with the workspace's Bitly account at publish time
    - `utmCampaign` string, nullable: The `utm_campaign` added to shortened links, if any
    - `scheduledAt` string, date-time, nullable
    - `publishedAt` string, date-time, nullable
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
    - `socialAccount` SocialAccountSummary
      - `id` string, uuid
      - `platform` 'FACEBOOK' | 'INSTAGRAM' | 'X' | 'LINKEDIN' | 'TIKTOK' | 'YOUTUBE' | 'THREADS' | 'BLUESKY' | 'PINTEREST' | 'GOOGLE_BUSINESS'
      - `accountName` string
      - `accountUrl` string, nullable
      - `profilePictureUrl` string, nullable
      - `customLabel` string, nullable: User-set label to distinguish accounts (e.g. "Downtown")
    - `medias` PostMedia[]
      - `id` string, uuid
      - `name` string
      - `url` string
      - `type` string: Media type (e.g. IMAGE_JPEG, VIDEO_MP4)
      - `size` number: File size in bytes
      - `width` integer, nullable
      - `height` integer, nullable
      - `duration` number, nullable: Video duration in seconds
      - `coverImageUrl` string, nullable
    - `logs` PostLog[]
      - `type` 'SUCCESS' | 'ERROR' | 'WARNING' | 'INFO'
      - `message` string, nullable
      - `createdAt` string, date-time
    - `platformParams` object, nullable: Platform-specific parameters (YouTube, TikTok, Pinterest, or Google Business fields)
    - `label` PostLabel, nullable: A user-defined content label attached to a post (used for organizing content pillars)
      - `name` string
      - `color` string: Hex color code
    - `metrics` PostMetrics, nullable: A post's most recent daily analytics snapshot. Snapshots are collected once per day per post, so `measuredAt` shows how fresh these figures are.
      - `views` integer, nullable
      - `likes` integer, nullable
      - `comments` integer, nullable
      - `shares` integer, nullable
      - `engagementRate` number, float, nullable: Engagement as a share of views, where the platform reports it
      - `platformMetrics` object, nullable: Platform-specific extras, present only where the platform reports them. For example X returns bookmarks and quotes, Instagram returns reach and saves.
      - `measuredAt` string, date: The date this snapshot was taken
  - `pagination` Pagination
    - `page` integer
    - `limit` integer
    - `total` integer
    - `has_more` boolean

## Other responses

- `400`: Validation error (missing workspaceId or invalid status)
- `404`: Workspace not found

---

[API](https://skmtc.dev/postplanify/apis/postplanify-api.md) · [All operations](https://skmtc.dev/postplanify/apis/postplanify-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postplanify/apis/postplanify-api/revisions/9eae5f1faa56?raw)