> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postonce.to/llms.txt
> Use this file to discover all available pages before exploring further.

# List posts

> Lists the authenticated profile's posts, newest first: posts created through the API or dashboard, and posts published by workflows (origin `workflow`). Workflow posts are read-only.



## OpenAPI

````yaml /openapi/public-api.yaml get /v1/posts
openapi: 3.1.0
info:
  title: PostOnce Public API
  version: 1.0.0-alpha
  description: Public API for PostOnce paid users
servers:
  - url: https://postonce.to/api/public
security:
  - bearerAuth: []
paths:
  /v1/posts:
    get:
      summary: List posts
      description: >-
        Lists the authenticated profile's posts, newest first: posts created
        through the API or dashboard, and posts published by workflows (origin
        `workflow`). Workflow posts are read-only.
      parameters:
        - $ref: '#/components/parameters/listLimit'
        - $ref: '#/components/parameters/listAfter'
        - name: external_user_id
          in: query
          required: false
          description: >-
            Partner accounts only. Return only posts with a target on this end
            user's accounts.
          schema:
            type: string
      responses:
        '200':
          description: Posts returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Post'
                  meta:
                    type: object
                    additionalProperties: true
        '400':
          description: The after cursor is not a post ID or does not match a post.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, revoked, or expired API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
components:
  parameters:
    listLimit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
      description: Maximum number of items to return.
    listAfter:
      name: after
      in: query
      required: false
      schema:
        type: string
      description: Cursor returned by a previous list response.
  schemas:
    Post:
      type: object
      properties:
        id:
          type: string
        content:
          type: string
        external_id:
          type: string
          nullable: true
        media:
          type: array
          items:
            $ref: '#/components/schemas/MediaInput'
        origin:
          type: string
          enum:
            - ui
            - api
            - workflow
          nullable: true
        publish_at:
          type: string
          format: date-time
          nullable: true
        status:
          type: string
          enum:
            - queued
            - scheduled
            - processing
            - partial
            - published
            - failed
            - cancelled
          example: scheduled
        created_at:
          type: string
          format: date-time
          nullable: true
        targets:
          type: array
          items:
            $ref: '#/components/schemas/PostTarget'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              example: workflow_limit_reached
            message:
              type: string
              example: You have reached the maximum number of workflows for your plan.
            hint:
              type: string
              description: Suggested action to resolve the error.
    AuthErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: invalid_api_key
            message:
              type: string
              example: Invalid API key.
            hint:
              type: string
              description: Suggested action to resolve the error.
    MediaInput:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          description: >-
            Required absolute HTTP or HTTPS media URL. Surrounding whitespace is
            trimmed. Invalid URLs reject the entire request with invalid_media;
            URL contents are not fetched during validation.
          example: https://cdn.example.com/launch-image.png
        type:
          type: string
          enum:
            - image
            - video
          example: image
        width:
          type: integer
        height:
          type: integer
        size:
          type: integer
        duration:
          type: number
          description: Video duration in seconds when known.
        thumbnail_url:
          type: string
          description: >-
            Cover image URL for video media (JPEG or PNG, 8 MB or less). It is
            applied as the video cover on Instagram Reels and Stories, Facebook
            Reels, and TikTok (inserted as the video's first frame), and is also
            used in scheduled and published post previews.
    PostTarget:
      type: object
      properties:
        target_post_id:
          type: string
        account_id:
          type: string
          nullable: true
        platform:
          type: string
          nullable: true
        target_variant:
          type: string
          enum:
            - spotlight
            - public_story
          nullable: true
          description: >-
            Concrete placement for platforms that fan one account target into
            multiple publications.
        username:
          type: string
          nullable: true
        status:
          type: string
          enum:
            - pending
            - scheduled
            - processing
            - submitted
            - published
            - failed
            - skipped
            - cancelled
          example: pending
        error:
          type: string
          nullable: true
        platform_post_id:
          type: string
          nullable: true
        platform_post_url:
          type: string
          nullable: true
        scheduled_time:
          type: string
          format: date-time
          nullable: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Scoped API key issued in PostOnce Settings. OAuth authorization grants
        are not currently supported.
      x-scopes:
        accounts:read: List and read connected accounts.
        accounts:write: Connect and disconnect social accounts.
        media:read: Read uploaded media.
        media:write: Upload media.
        posts:read: Read posts and unpublished drafts.
        posts:write: Create, update, publish, cancel, retry, and delete posts and drafts.
        workflows:read: List and read crossposting workflows.
        workflows:write: Create, update, and delete crossposting workflows.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.