> ## Documentation Index > Fetch the complete documentation index at: https://docs.puffle.ai/llms.txt > Use this file to discover all available pages before exploring further. # List social posts > List social posts **CLI:** ```bash theme={null} puffle calendar post puffle calendar post --status ``` ## Overview List social posts This page documents `get /api/calendar/posts`. Use the request and response sections on this page for accepted parameters, payload fields, response fields, and authentication behavior. ## AI agent notes * Confirm the operation matches the user's intent before calling it. * For write operations, confirm the user intends to change state. * Surface validation, permission, and not-found errors instead of retrying unchanged. ## OpenAPI ````yaml get /api/calendar/posts openapi: 3.0.3 info: title: Puffle API version: 1.0.0 description: >- HTTP API for the Puffle GTM platform - strategy planning, campaign-backed Outbound execution, Puffle Agent runs, sender management, and Unibox reply workflows. Designed for operation by both humans and autonomous AI agents. Agents should start at the [Agent Playbook](/guides/agent-playbook) which prescribes a workspace-context check (`GET /api/context`) and core user journeys with exact call ordering. contact: name: Puffle Support url: https://puffle.ai servers: - url: https://app.puffle.ai description: Production security: - bearerAuth: [] tags: - name: Campaigns description: >- Campaign-backed Outbound execution. These endpoints manage draft, launching, active, paused, and completed Outbound runs with sequence nodes, contacts, and sender accounts. - name: Accounts description: Signed-in user account, settings, and workspace context endpoints. - name: Senders description: >- Connected sender accounts, email inboxes, sending domains, DNS verification, warmup, and sender capacity. - name: Socials description: >- Social post scheduling and inbox — schedule, publish, archive, and delete posts across LinkedIn, Twitter, Threads, Bluesky via the Late (late.ai) integration. Connect social accounts via OAuth, pull analytics, monitor mentions. paths: /api/calendar/posts: get: tags: - Socials summary: List social posts description: >- Returns every non-archived post in the caller's calendar, ordered by `scheduled_at` ascending. Posts with status `posted` that have no connected accounts are hidden — these are onboarding stubs waiting for an account to be linked. Each post is enriched with the first linked account's profile picture and display name for rendering. operationId: listSocialPosts parameters: - name: status in: query required: false schema: description: Optional status filter. Omit to return every non-archived post. type: string enum: - draft - scheduled - posted responses: '200': description: Array of posts (possibly empty). content: application/json: schema: type: object properties: posts: type: array items: type: object properties: id: type: string format: uuid calendar_id: type: string format: uuid title: type: string nullable: true content: type: string nullable: true hashtags: type: array items: type: string channels: type: array items: type: string description: >- Legacy channel list — usually `['linkedin']` or `['x']`. Prefer `account_ids` for precise targeting. scheduled_at: description: >- ISO timestamp. Required for `scheduled` posts; ignored for `draft`. type: string format: date-time nullable: true account_ids: type: array items: type: string format: uuid description: >- Target social account IDs. If empty, selected channels fall back to the caller's first owned account per platform. status: type: string enum: - draft - scheduled - posted description: >- Lifecycle state. `draft` is fully editable and won't publish; `scheduled` is queued at the social provider for auto-publish at `scheduled_at`; `posted` is terminal — the platform has accepted publication and `late_post_id` no longer reflects a mutable object. late_post_id: description: >- Social provider post ID. Present whenever the server mirrored this post to the provider; cleared when archived or when provider creation failed. type: string nullable: true media_items: type: array items: type: object properties: url: type: string format: uri description: >- Public CDN URL returned from `uploadSocialMedia`. Must be reachable when the social provider picks up the scheduled post. type: type: string enum: - image - video - document description: Classified media type for the social provider. required: - url - type additionalProperties: false description: A single media attachment. archived_at: description: Set on soft-delete. Null on active posts. type: string format: date-time nullable: true variants: type: array items: type: object properties: post_id: type: string format: uuid channel: type: string enum: - linkedin - x content: type: string media_items: type: array items: type: object properties: url: type: string format: uri description: >- Public CDN URL returned from `uploadSocialMedia`. Must be reachable when the social provider picks up the scheduled post. type: type: string enum: - image - video - document description: >- Classified media type for the social provider. required: - url - type additionalProperties: false description: A single media attachment. provider_post_id: type: string nullable: true provider_status: type: string provider_error: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - post_id - channel - content - media_items - provider_post_id - provider_status - provider_error - created_at - updated_at additionalProperties: false account_profile_picture: type: string nullable: true account_display_name: type: string nullable: true required: - id - calendar_id - title - content - hashtags - channels - scheduled_at - account_ids - status - late_post_id - media_items - archived_at additionalProperties: false description: Canonical social post row. postsUrl: type: string description: Posts page for reviewing these results. required: - posts - postsUrl additionalProperties: false examples: default: value: posts: - id: pst_1111 calendar_id: cal_1111 title: Product launch content: Excited to share our newest feature... hashtags: - productlaunch - saas channels: - linkedin scheduled_at: '2026-04-25T14:00:00Z' account_ids: - aaaa1111-1111-1111-1111-111111111111 status: scheduled late_post_id: late_abc123 media_items: [] archived_at: null account_profile_picture: https://…/jane.jpg account_display_name: Jane Doe postsUrl: /profile/socials '401': description: Missing or invalid Bearer token. content: application/json: schema: type: object properties: error: type: string required: - error additionalProperties: false examples: default: value: error: Unauthorized '500': description: Unexpected server error. content: application/json: schema: type: object properties: error: type: string required: - error additionalProperties: false examples: default: value: error: Internal server error components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: pk_live_... ````