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

# List posts

> List scheduled posts or post history with per-account delivery states.

Read access: a read-enabled personal or team REST API key, or a signed-in user. OAuth clients use the corresponding MCP tool through /mcp.

List scheduled posts or post history with per-account delivery states.

Scheduled includes groups with a scheduled, preparing or publishing delivery. History includes the remaining groups, including failed, uncertain and cancelled outcomes. It is not a list of confirmed publications alone.

MCP clients can use [`list_posts`](/mcp-reference/list_posts) for this operation.

[Request conventions](/api-reference/overview) · [API keys](/api-keys) · [MCP connections](/mcp-connections)


## OpenAPI

````yaml api-reference/openapi.json GET /api/posts
openapi: 3.1.0
info:
  title: Posted HTTP API
  version: 0.2.0
  description: >-
    All registered application, account, OAuth, MCP transport and health
    endpoints. Publishing and draft request schemas come from the shared runtime
    validators. Replace the example server with your installation. Documentation
    uses simple request examples and does not execute live publishing requests.
servers:
  - url: https://posted-api.example.com
security: []
paths:
  /api/posts:
    get:
      tags:
        - Posts
      summary: List posts
      description: >-
        List scheduled posts or post history with per-account delivery states.


        Scheduled includes groups with a scheduled, preparing or publishing
        delivery. History includes the remaining groups, including failed,
        uncertain and cancelled outcomes. It is not a list of confirmed
        publications alone.


        Read access: a read-enabled personal or team REST API key, or a
        signed-in user. OAuth clients use the corresponding MCP tool through
        /mcp.
      operationId: get_api_posts
      parameters:
        - name: view
          in: query
          required: false
          schema:
            type: string
            enum:
              - scheduled
              - history
          description: scheduled, history
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 9007199254740991
          description: integer
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
          description: integer
      responses:
        '200':
          description: >-
            Successful response. Examples are illustrative; field values vary by
            record.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        text:
                          type: string
                        additionalPosts:
                          type: array
                          items: {}
                        mediaOverrides:
                          type: object
                          properties: {}
                          additionalProperties: true
                        scheduledAt:
                          type: string
                        idempotencyKey:
                          type: string
                        state:
                          type: string
                        version:
                          type: integer
                        createdAt:
                          type: string
                        media:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              fileName:
                                type: string
                              contentType:
                                type: string
                              sizeBytes:
                                type: integer
                              width:
                                type: integer
                              height:
                                type: integer
                              alt:
                                type: string
                              durationSeconds:
                                type:
                                  - string
                                  - 'null'
                            additionalProperties: true
                        managedBy:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            avatarUrl:
                              type:
                                - string
                                - 'null'
                          additionalProperties: true
                        deliveries:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              postIndex:
                                type: integer
                              connectionId:
                                type: string
                              provider:
                                type: string
                              accountName:
                                type: string
                              textOverride:
                                type:
                                  - string
                                  - 'null'
                              state:
                                type: string
                              providerPostId:
                                type:
                                  - string
                                  - 'null'
                              publishedUrl:
                                type:
                                  - string
                                  - 'null'
                              error:
                                type:
                                  - string
                                  - 'null'
                              publishedAt:
                                type:
                                  - string
                                  - 'null'
                            additionalProperties: true
                      additionalProperties: true
                  total:
                    type: integer
                  page:
                    type: integer
                  pageSize:
                    type: integer
                additionalProperties: true
              example:
                items:
                  - id: 22222222-2222-4222-8222-222222222222
                    text: A small update from the studio.
                    additionalPosts: []
                    mediaOverrides: {}
                    scheduledAt: '2027-01-18T09:30:00.000Z'
                    idempotencyKey: studio-update-2027-01-18
                    state: scheduled
                    version: 1
                    createdAt: '2027-01-18T09:30:00.000Z'
                    media:
                      - id: 44444444-4444-4444-8444-444444444444
                        fileName: studio.jpg
                        contentType: image/jpeg
                        sizeBytes: 245760
                        width: 1600
                        height: 900
                        alt: A bright studio desk beside a window
                        durationSeconds: null
                    managedBy:
                      id: 66666666-6666-4666-8666-666666666666
                      name: Alex Morgan
                      avatarUrl: null
                    deliveries:
                      - id: 77777777-7777-4777-8777-777777777777
                        postIndex: 0
                        connectionId: 11111111-1111-4111-8111-111111111111
                        provider: bluesky
                        accountName: Alex Morgan
                        textOverride: null
                        state: scheduled
                        providerPostId: null
                        publishedUrl: null
                        error: null
                        publishedAt: null
                total: 1
                page: 1
                pageSize: 20
        default:
          description: >-
            Request failure. Inspect code, message and requestId; respect
            Retry-After on HTTP 429.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
        - sessionCookie: []
components:
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - requestId
          properties:
            code:
              type: string
            message:
              type: string
            requestId:
              type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Personal or team Posted REST API key
    sessionCookie:
      type: apiKey
      in: cookie
      name: posted_session
      description: >-
        Signed-in human browser session; mutation requests also need the exact
        UI Origin

````

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