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

# List posts

`GET /posts`

## Request

- Base URL: `https://api.cut.pro/api/v1`
- URL: `https://api.cut.pro/api/v1/posts`
- Auth: API key in header `X-Api-Key`

Returns a paginated list of posts in this workspace, newest first. Each post includes its items with current status and error codes.

## Query parameters

- `page` number: Page number (default: 1)
- `limit` number: Items per page (default: 20, max: 100)
- `status` 'pending' | 'processing' | 'completed' | 'partial' | 'failed' | 'cancelled'

## Response `200`

Response for status 200

- object
  - `posts` object[], required
    - `id` string, required
    - `status` 'pending' | 'processing' | 'completed' | 'partial' | 'failed' | 'cancelled', required
    - `scheduled_at` string, nullable, required
    - `created_at` string, required
    - `updated_at` string, required
    - `item_count` number, required
    - `items` object[], required
      - `id` string, required
      - `platform` 'youtube' | 'tiktok' | 'instagram' | 'bluesky' | 'threads' | 'linkedin' | 'pinterest' | 'facebook' | 'carmedia' | 'twitter' | 'telegram' | 'mastodon' | 'discordserver' | 'dailymotion' | 'tumblr' | 'slack', required
      - `connection_id` string, required
      - `edit_id` string, nullable, required
      - `render_id` string, nullable, required: Render backing this item. `null` once the render is gone (expired, failed or cancelled): there is no file left to download.
      - `status` 'pending' | 'rendering' | 'publishing' | 'completed' | 'failed', required
      - `published_url` string, nullable, required
      - `error_code` string, nullable, required
      - `metadata` object, nullable, required: Publishing metadata of this item (title, caption/description and per-network options), in the same shape accepted by `POST /posts`.
        - `tumblr` object
          - `title` string
          - `text` string
          - `tags` string[]
          - `coverImageId` string
        - `slack` object
          - `channelId` string
          - `text` string
          - `coverImageId` string
        - `dailymotion` object
          - `title` string
          - `description` string
          - `channel` string
          - `tags` string[]
          - `visibility` 'public' | 'private'
          - `coverImageId` string
        - `telegram` object
          - `text` string
          - `silent` boolean
          - `coverImageId` string
        - `mastodon` object
          - `text` string
          - `visibility` 'public' | 'unlisted' | 'private'
          - `sensitive` boolean
          - `spoilerText` string
          - `language` string
          - `coverImageId` string
        - `discordserver` object
          - `channelId` string
          - `text` string
          - `coverImageId` string
        - `youtube` object
          - `title` string
          - `description` string
          - `categoryId` string
          - `privacyStatus` 'public' | 'private' | 'unlisted'
          - `license` 'youtube' | 'creativeCommon'
          - `embeddable` boolean
          - `publicStatsViewable` boolean
          - `madeForKids` boolean
          - `selfDeclaredMadeForKids` boolean
          - `tags` string[]
          - `notifySubscribers` boolean
          - `coverImageId` string
        - `tiktok` object
          - `title` string
          - `photoTitle` string
          - `privacyLevel` 'PUBLIC_TO_EVERYONE' | 'MUTUAL_FOLLOW_FRIENDS' | 'FOLLOWER_OF_CREATOR' | 'SELF_ONLY'
          - `disableDuet` boolean
          - `disableComment` boolean
          - `disableStitch` boolean
          - `coverImageId` string
          - `brandContentToggle` boolean
          - `brandOrganicToggle` boolean
          - `isAigc` boolean
        - `instagram` object
          - `caption` string
          - `captionGroups` object
            - `hook` string[]
            - `emoji` string[]
            - `body` string[]
            - `cta` string[]
            - `hashtags` string[]
          - `captionParts` string[]
          - `captionAutoEnvelope` boolean
          - `captionTemplate` string
          - `coverUrl` string
          - `coverImageId` string
          - `thumbOffset` number
          - `shareToFeed` boolean
          - `audioName` string
          - `collaborators` string[]
          - `userTags` string[]
          - `trialReel` 'off' | 'MANUAL' | 'SS_PERFORMANCE'
          - `firstComment` string
        - `facebook` object
          - `description` string
          - `postType` 'reel' | 'feed'
          - `link` string
          - `videoTitle` string
          - `coverImageId` string
          - `firstComment` string
        - `bluesky` object
          - `text` string
          - `languages` string[]
          - `coverImageId` string
        - `threads` object
          - `text` string
          - `replyControl` 'everyone' | 'accounts_you_follow' | 'mentioned_only'
          - `coverImageId` string
          - `firstComment` string
        - `linkedin` object
          - `text` string
          - `visibility` 'PUBLIC' | 'CONNECTIONS'
          - `coverImageId` string
        - `pinterest` object
          - `boardId` string
          - `title` string
          - `description` string
          - `link` string
          - `coverImageUrl` string
          - `coverImageId` string
        - `carmedia` object
          - `title` string
          - `description` string
          - `visibility` 'public'
          - `coverImageId` string
        - `twitter` object
          - `text` string
          - `replySettings` 'everyone' | 'following' | 'mentionedUsers'
          - `coverImageId` string
      - `created_at` string, required
      - `updated_at` string, required
      - `posted_at` string, nullable, required
  - `pagination` object, required
    - `current_page` number, required: Current page number (1-based)
    - `total_pages` number, required: Total number of pages
    - `total_count` number, required: Total number of items across all pages
    - `has_next_page` boolean, required
    - `has_previous_page` boolean, required
    - `limit` number, required: Items per page used for this response

---

[API](https://skmtc.dev/cut/apis/cutpro-api.md) · [All operations](https://skmtc.dev/cut/apis/cutpro-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cut/apis/cutpro-api/revisions/89d0bafe529c?raw)