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

# List posts

`GET /v0/posts`

## Request

- Base URL: `https://api.schedulin.app`
- URL: `https://api.schedulin.app/v0/posts`
- Auth: one of:
  - API key in header `x-api-key`
  - OAuth 2 (authorization code, authorization URL `https://api.schedulin.app/oauth/authorize`, token URL `https://api.schedulin.app/oauth/token`, scopes: `posts:read`)

Search and filter posts with various criteria including status, date range, social accounts, and tags

## Query parameters

- `page` integer
- `status` 'SCHEDULED' | 'PROCESSING' | 'COMPLETED' | 'DRAFT' | 'FAILED'
- `statuses` string[]
- `approvalStatus` 'DRAFT' | 'PENDING_APPROVAL' | 'APPROVED' | 'REJECTED'
- `scheduledAt` object
  - `from` string
  - `to` string
- `tagIds` string[]
- `tagMode` 'ANY' | 'ALL'
- `socialAccountIds` string[]
- `limit` integer

## Response `200`

OK

- object
  - `posts` PostWithRelations[], required
    - `id` string, required
    - `externalId` string, nullable, required
    - `caption` string, required
    - `status` 'SCHEDULED' | 'PROCESSING' | 'COMPLETED' | 'DRAFT' | 'FAILED' | 'DELETED', required
    - `approvalStatus` 'DRAFT' | 'PENDING_APPROVAL' | 'APPROVED' | 'REJECTED', required
    - `approvalRequestedAt` string, date-time, nullable, required
    - `approvalRequestedBy` string, nullable, required
    - `approvedAt` string, date-time, nullable, required
    - `approvedBy` string, nullable, required
    - `rejectionReason` string, nullable, required
    - `scheduledAt` string, date-time, nullable, required
    - `platformConfiguration` object, nullable, required
    - `socialAccountId` string, required
    - `url` string, nullable, required
    - `title` string, nullable, required
    - `postedAt` string, date-time, nullable, required
    - `errorMessage` string, nullable, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `socialAccount` SocialAccount, required
      - `id` string, required
      - `platform` 'bluesky' | 'facebook' | 'google_business_profile' | 'instagram' | 'linkedin' | 'pinterest' | 'reddit' | 'snapchat' | 'threads' | 'tiktok' | 'tiktok_business' | 'twitter' | 'youtube' | 'mastodon' | 'telegram' | 'devto' | 'hashnode' | 'medium' | 'wordpress' | 'lemmy' | 'nostr' | 'discord' | 'dribbble' | 'farcaster' | 'kick' | 'listmonk' | 'mewe' | 'moltbook' | 'skool' | 'slack' | 'twitch' | 'vk' | 'whop', required
      - `imageUrl` string, nullable, required
      - `imageProcessingStatus` 'PENDING' | 'PROCESSING' | 'PROCESSED' | 'FAILED', required
      - `username` string, nullable, required
      - `status` 'connected' | 'disconnected', required
      - `disconnectedReason` 'TOKEN_EXPIRED' | 'TOKEN_INVALID' | 'TOKEN_REVOKED' | 'REFRESH_FAILED' | 'ACCOUNT_SUSPENDED' | 'PERMISSION_DENIED' | 'EMAIL_UNCONFIRMED', nullable, required
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
      - `refreshTokenValid` boolean, required
    - `media` PostMedia[], required
      - `id` string, required
      - `url` string, required
      - `name` string, required
      - `mimeType` string, required
      - `width` integer, nullable, required
      - `height` integer, nullable, required
      - `duration` integer, nullable, required
      - `size` integer, nullable, required
      - `alt` string, nullable, required
      - `thumbnailUrl` string, nullable, required
      - `tags` object[]
        - `id` string, required
        - `type` 'user' | 'business', required
        - `platform` 'bluesky' | 'facebook' | 'google_business_profile' | 'instagram' | 'linkedin' | 'pinterest' | 'reddit' | 'snapchat' | 'threads' | 'tiktok' | 'tiktok_business' | 'twitter' | 'youtube' | 'mastodon' | 'telegram' | 'devto' | 'hashnode' | 'medium' | 'wordpress' | 'lemmy' | 'nostr' | 'discord' | 'dribbble' | 'farcaster' | 'kick' | 'listmonk' | 'mewe' | 'moltbook' | 'skool' | 'slack' | 'twitch' | 'vk' | 'whop', required
        - `x` number
        - `y` number
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
    - `thumbnail` PostMedia, required
      - `id` string, required
      - `url` string, required
      - `name` string, required
      - `mimeType` string, required
      - `width` integer, nullable, required
      - `height` integer, nullable, required
      - `duration` integer, nullable, required
      - `size` integer, nullable, required
      - `alt` string, nullable, required
      - `thumbnailUrl` string, nullable, required
      - `tags` object[]
        - `id` string, required
        - `type` 'user' | 'business', required
        - `platform` 'bluesky' | 'facebook' | 'google_business_profile' | 'instagram' | 'linkedin' | 'pinterest' | 'reddit' | 'snapchat' | 'threads' | 'tiktok' | 'tiktok_business' | 'twitter' | 'youtube' | 'mastodon' | 'telegram' | 'devto' | 'hashnode' | 'medium' | 'wordpress' | 'lemmy' | 'nostr' | 'discord' | 'dribbble' | 'farcaster' | 'kick' | 'listmonk' | 'mewe' | 'moltbook' | 'skool' | 'slack' | 'twitch' | 'vk' | 'whop', required
        - `x` number
        - `y` number
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
    - `tags` Tag[], required
      - `id` string, required
      - `name` string, required
      - `color` string, required
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
    - `parts` PostThreadPart[], required
      - `caption` string, required
      - `media` PostMedia[], required
        - `id` string, required
        - `url` string, required
        - `name` string, required
        - `mimeType` string, required
        - `width` integer, nullable, required
        - `height` integer, nullable, required
        - `duration` integer, nullable, required
        - `size` integer, nullable, required
        - `alt` string, nullable, required
        - `thumbnailUrl` string, nullable, required
        - `tags` object[]
          - `id` string, required
          - `type` 'user' | 'business', required
          - `platform` 'bluesky' | 'facebook' | 'google_business_profile' | 'instagram' | 'linkedin' | 'pinterest' | 'reddit' | 'snapchat' | 'threads' | 'tiktok' | 'tiktok_business' | 'twitter' | 'youtube' | 'mastodon' | 'telegram' | 'devto' | 'hashnode' | 'medium' | 'wordpress' | 'lemmy' | 'nostr' | 'discord' | 'dribbble' | 'farcaster' | 'kick' | 'listmonk' | 'mewe' | 'moltbook' | 'skool' | 'slack' | 'twitch' | 'vk' | 'whop', required
          - `x` number
          - `y` number
        - `createdAt` string, date-time, required
        - `updatedAt` string, date-time, required
  - `page` integer, required
  - `totalPages` integer, required
  - `total` integer, required

## Other responses

- `400`: Bad Request — the request isn't allowed in the resource's current state (e.g. editing a published post).
- `401`: Unauthorized — missing or invalid API key / access token.
- `403`: Forbidden — the credential lacks the required scope or access.
- `422`: Unprocessable request. Schema validation failures have `code: "INPUT_VALIDATION_FAILED"` and `data.fieldErrors` mapping each invalid field to its messages (nested issues name their full path, e.g. `media[0].url: ...`). Business-rule rejections (e.g. a `scheduledAt` in the past) have `code: "UNPROCESSABLE_CONTENT"` and carry the reason in `data.message` and `data.formErrors`.
- `429`: Rate limit exceeded. Wait `Retry-After` seconds before retrying.
- `500`: Internal Server Error

---

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