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

# List posts

`GET /api/posts`

## Request

- Base URL: `https://api.postproxy.dev`
- URL: `https://api.postproxy.dev/api/posts`
- Auth: HTTP bearer

Retrieves a paginated list of all posts in the current profile group. Thread children are not returned as top-level items — only parent posts appear.

## Query parameters

- `profile_group_id` string
- `page` integer
- `per_page` integer
- `status` 'draft' | 'scheduled' | 'published' | 'failed'
- `platforms` string[]
- `source` 'postproxy' | 'imported'
- `scheduled_after` string, date-time

## Response `200`

Paginated list of posts

- object
  - `total` integer: Total number of posts
  - `page` integer: Current page number
  - `per_page` integer: Items per page
  - `data` Post[]: Array of post objects
    - `id` string: Unique post identifier (id)
    - `body` string: Post body/text content
    - `status` 'draft' | 'processing' | 'processed' | 'scheduled' | 'media_processing_failed': Post-level status
    - `source` 'postproxy' | 'imported': Origin of the post: postproxy (created via app or API) or imported (imported from a connected platform)
    - `draft` boolean: Whether the post is a draft
    - `scheduled_at` string, date-time, nullable: ISO 8601 timestamp if scheduled, null otherwise
    - `created_at` string, date-time: ISO 8601 timestamp of creation
    - `queue_id` string, nullable: Queue ID if the post belongs to a queue
    - `queue_priority` 'high' | 'medium' | 'low' | 'null', nullable: Priority level if in a queue
    - `media` PostMedia[]: Array of media attachment objects
      - `id` string: Unique attachment identifier (id)
      - `status` 'pending' | 'processed' | 'failed': Processing status
      - `error_message` string, nullable: Error details if processing failed
      - `content_type` string: MIME type (e.g. image/jpeg, video/mp4)
      - `source_url` string, nullable: Original source URL if media was provided as a URL
      - `url` string, nullable: Hosted URL of the processed file (null if not yet processed)
      - `platforms` PostMediaPlatformError[]: Per-platform formatting/upload errors for this attachment. Only included when at least one platform had an error processing this specific media file; omitted when there are no platform-level errors
        - `platform` string: Network identifier (instagram, twitter, etc.)
        - `status` string: Per-platform attachment status
        - `error` string: Error summary for this attachment on this platform
        - `error_details` PostErrorDetails: Structured platform error details.
          - `platform_error_code` string, nullable: Error code returned by the platform API
          - `platform_error_subcode` string, nullable: Error subcode returned by the platform API
          - `platform_error_message` string, nullable: Error message returned by the platform API
          - `postproxy_note` string, nullable: Additional context from Postproxy about the error
    - `platforms` PostPlatform[]: Array of platform-specific posting results. For thread posts, this only describes the parent — each thread item carries its own platforms array.
      - `platform` 'facebook' | 'instagram' | 'tiktok' | 'linkedin' | 'youtube' | 'twitter' | 'threads' | 'pinterest': Platform identifier
      - `profile_id` string: ID of the connected profile this platform entry was posted to
      - `profile_name` string: Display name of the connected profile
      - `status` string: Platform posting status: processing, published, failed, pending_deletion, deleted
      - `params` object, nullable: Platform-specific parameters used for this post
      - `error` string, nullable: Error summary (null on success)
      - `error_details` PostErrorDetails: Structured platform error details.
        - `platform_error_code` string, nullable: Error code returned by the platform API
        - `platform_error_subcode` string, nullable: Error subcode returned by the platform API
        - `platform_error_message` string, nullable: Error message returned by the platform API
        - `postproxy_note` string, nullable: Additional context from Postproxy about the error
      - `attempted_at` string, date-time, nullable: ISO 8601 timestamp of posting attempt
      - `permalink` string, nullable: Direct URL to the published post on the platform. Null if not published or permalink is unavailable
      - `insights` object: Engagement metrics (when available)
        - `impressions` integer: Number of impressions/views
        - `on` string, date-time: ISO 8601 timestamp when insights were captured
      - `attachments` PostPlatformAttachment[]: Platform-level files such as the video cover. Only returned by GET /posts/{id}, and omitted when there are none. For imported posts the cover comes from the platform (Instagram Reels, TikTok and LinkedIn videos). Imported TikTok posts have an empty media array, so use the cover as the thumbnail.
        - `id` string: Unique attachment identifier
        - `type` 'cover': Attachment type
        - `status` 'pending' | 'processed' | 'failed': Processing status
        - `content_type` string, nullable: MIME type of the file (e.g. image/jpeg)
        - `url` string, nullable: Hosted URL of the processed file (null until processed)
    - `thread` PostThreadChild[]: Array of thread child posts (only present for thread posts). Each item carries its own platforms array.
      - `id` string: Unique identifier (id) of the child post
      - `body` string: Text content of the child post
      - `media` PostMedia[]: Array of media attachment objects
        - `id` string: Unique attachment identifier (id)
        - `status` 'pending' | 'processed' | 'failed': Processing status
        - `error_message` string, nullable: Error details if processing failed
        - `content_type` string: MIME type (e.g. image/jpeg, video/mp4)
        - `source_url` string, nullable: Original source URL if media was provided as a URL
        - `url` string, nullable: Hosted URL of the processed file (null if not yet processed)
        - `platforms` PostMediaPlatformError[]: Per-platform formatting/upload errors for this attachment. Only included when at least one platform had an error processing this specific media file; omitted when there are no platform-level errors
          - `platform` string: Network identifier (instagram, twitter, etc.)
          - `status` string: Per-platform attachment status
          - `error` string: Error summary for this attachment on this platform
          - `error_details` PostErrorDetails: Structured platform error details.
            - `platform_error_code` string, nullable: Error code returned by the platform API
            - `platform_error_subcode` string, nullable: Error subcode returned by the platform API
            - `platform_error_message` string, nullable: Error message returned by the platform API
            - `postproxy_note` string, nullable: Additional context from Postproxy about the error
      - `platforms` PostPlatform[]: Per-platform delivery results for this thread item (status, permalink, error, error_details)
        - `platform` 'facebook' | 'instagram' | 'tiktok' | 'linkedin' | 'youtube' | 'twitter' | 'threads' | 'pinterest': Platform identifier
        - `profile_id` string: ID of the connected profile this platform entry was posted to
        - `profile_name` string: Display name of the connected profile
        - `status` string: Platform posting status: processing, published, failed, pending_deletion, deleted
        - `params` object, nullable: Platform-specific parameters used for this post
        - `error` string, nullable: Error summary (null on success)
        - `error_details` PostErrorDetails: Structured platform error details.
          - `platform_error_code` string, nullable: Error code returned by the platform API
          - `platform_error_subcode` string, nullable: Error subcode returned by the platform API
          - `platform_error_message` string, nullable: Error message returned by the platform API
          - `postproxy_note` string, nullable: Additional context from Postproxy about the error
        - `attempted_at` string, date-time, nullable: ISO 8601 timestamp of posting attempt
        - `permalink` string, nullable: Direct URL to the published post on the platform. Null if not published or permalink is unavailable
        - `insights` object: Engagement metrics (when available)
          - `impressions` integer: Number of impressions/views
          - `on` string, date-time: ISO 8601 timestamp when insights were captured
        - `attachments` PostPlatformAttachment[]: Platform-level files such as the video cover. Only returned by GET /posts/{id}, and omitted when there are none. For imported posts the cover comes from the platform (Instagram Reels, TikTok and LinkedIn videos). Imported TikTok posts have an empty media array, so use the cover as the thumbnail.
          - `id` string: Unique attachment identifier
          - `type` 'cover': Attachment type
          - `status` 'pending' | 'processed' | 'failed': Processing status
          - `content_type` string, nullable: MIME type of the file (e.g. image/jpeg)
          - `url` string, nullable: Hosted URL of the processed file (null until processed)

## Other responses

- `401`: Invalid, missing, or insufficient API key permissions.

---

[API](https://skmtc.dev/postproxy/apis/postproxy-social-media-api.md) - [All operations](https://skmtc.dev/postproxy/apis/postproxy-social-media-api/llms.txt) - [OpenAPI document](https://skmtc.dev/postproxy/apis/postproxy-social-media-api/revisions/d54482ac4ce7?raw)