> ## Documentation Index > Fetch the complete documentation index at: https://docs.postbreeze.ai/llms.txt > Use this file to discover all available pages before exploring further. # List posts > Lists posts you can see, ordered by upcoming scheduled time first and then by most recently created. By default this returns posts from every workspace your API key can reach, so you can grab everything in one call instead of looping. Each row includes its own `workspaceId` so you can group or filter the list on your end. If you only care about one workspace, pass `?workspaceId=` and the list is narrowed to that workspace. Deleted posts are left out. ## OpenAPI ````yaml /openapi.json get /posts openapi: 3.0.0 info: title: Postbreeze API description: >- Public REST API for scheduling and managing social posts. Authenticate every request with `Authorization: Bearer pb_live_…`. All endpoints are scoped to a single workspace; an API key issued for workspace A cannot access workspace B. version: 1.0.0 contact: {} servers: - url: http://localhost:4100/api/v1 security: - bearer: [] tags: [] paths: /posts: get: tags: - Posts summary: List posts description: >- Lists posts you can see, ordered by upcoming scheduled time first and then by most recently created. By default this returns posts from every workspace your API key can reach, so you can grab everything in one call instead of looping. Each row includes its own `workspaceId` so you can group or filter the list on your end. If you only care about one workspace, pass `?workspaceId=` and the list is narrowed to that workspace. Deleted posts are left out. operationId: PostsV1Controller_list parameters: - name: workspaceId required: false in: query description: >- Optional. When set, returns posts in only this workspace. When omitted, returns posts across every workspace the API key can reach. schema: type: string responses: '200': description: Array of posts visible to the caller. content: application/json: schema: type: array items: type: object properties: id: type: string description: Prefixed cuid identifier. workspaceId: type: string description: Workspace this post belongs to. createdByUserId: type: string description: User id of the author. status: type: string enum: - DRAFT - NEEDS_APPROVAL - SCHEDULED - PUBLISHING - PARTIALLY_PUBLISHED - PUBLISHED - FAILED - CANCELED description: >- Aggregate publish state. Derived from per-target statuses (`PARTIALLY_PUBLISHED` when some succeed and some fail). caption: type: string nullable: true description: >- Default caption applied to every target unless overridden via `targets[].captionOverride`. scheduledAt: type: string format: date-time nullable: true description: >- ISO-8601 publish time. Doubles as the calendar pin for drafts (set via `draftScheduledAt`). timezone: type: string nullable: true description: >- IANA timezone the post was composed in. Cosmetic — used by the UI. workflowId: type: string nullable: true description: >- Temporal workflow id driving this post's publish, when scheduled. Null on drafts and after cancellation. pendingWorkflowId: type: string nullable: true description: >- Workflow id staged during the schedule transaction. Visible while a Temporal start is in flight; cleared on commit. approvedByUserId: type: string nullable: true description: >- User id of the approver. Set when an `NEEDS_APPROVAL` post is approved. approvedAt: type: string format: date-time nullable: true description: When the post was approved, if applicable. createdViaApi: type: boolean description: >- True when the post was authored by an API-key or OAuth request. Cookie-session dashboard posts are false. createdViaFlatShape: type: boolean description: >- True when the request used the flat `platforms[]` body shape. False for the nested `targets[]` shape and dashboard posts. deletedAt: type: string format: date-time nullable: true description: >- Soft-delete timestamp. Listings and `GET /posts/:id` exclude rows where this is non-null. createdAt: type: string format: date-time description: When the post was created. updatedAt: type: string format: date-time description: When the post was last modified. targets: description: >- One fan-out target per connected account this post publishes to. type: array items: type: object properties: id: type: string description: Prefixed cuid identifier of this target. postId: type: string description: Owning post id. socialAccountId: type: string description: >- Connected social account this target publishes to. Same id returned from `GET /social-accounts`. platform: type: string enum: - INSTAGRAM - FACEBOOK_PAGE - X - LINKEDIN_PERSON - LINKEDIN_COMPANY - TIKTOK_BUSINESS - TIKTOK_PERSONAL - YOUTUBE - PINTEREST - THREADS - BLUESKY description: >- Platform of the bound social account, denormalised for convenience. status: type: string enum: - DRAFT - SCHEDULED - PUBLISHING - PUBLISHED - FAILED - SKIPPED - CANCELED description: >- Per-target publish state. Independent of the parent `Post.status` so one target can FAIL while others PUBLISH. captionOverride: type: string nullable: true description: >- Override of the post-level caption for this target only. Null when the parent caption is used. firstComment: type: string nullable: true description: >- First-comment text posted as a reply after the main post lands. Null when no first comment was requested. firstCommentError: type: string nullable: true description: >- Set when the main post landed but the first-comment leg failed (rate limit, missing scope, comments disabled). Cleared on a successful retry. firstCommentAttempt: type: integer description: >- Monotonic count of first-comment attempts (publisher leg + manual retries). Powers the retry-cooldown gate without scanning `PublishAttempt`. platformOptions: type: object additionalProperties: true nullable: true description: >- Per-platform options discriminated on `platform`. Shape mirrors what was passed in at create / update time. mediaIds: description: >- Per-target media override. Empty array means the target inherits the post-level `media` ordering. type: array items: type: string scheduledFor: type: string format: date-time nullable: true description: >- When this target is scheduled to publish. Null on drafts. publishedAt: type: string format: date-time nullable: true description: >- When this target actually published. Null until the publisher lands. externalPostId: type: string nullable: true description: >- Stable per-platform post identifier returned by the platform after publish. Null until the publisher lands. externalUrl: type: string nullable: true description: >- Public URL of the published post on the platform, when the platform exposes one. errorCode: type: string nullable: true description: >- Machine-readable error code from the last failed publish attempt. errorMessage: type: string nullable: true description: >- Human-readable error message from the last failed publish attempt. attemptCount: type: integer description: >- Monotonic count of publish attempts the worker has made for this target. lastAttemptAt: type: string format: date-time nullable: true description: >- Timestamp of the most recent publish attempt, success or failure. createdAt: type: string format: date-time description: When this target row was created. updatedAt: type: string format: date-time description: When this target row was last modified. media: description: >- Library media attached to the post, ordered by `order`. Per-target overrides on `targets[].mediaIds` win over this list. type: array items: type: object properties: postId: type: string description: Owning post id. mediaAssetId: type: string description: >- Library `MediaAsset` id. The asset itself (storage key, kind, etc.) is fetched via `GET /media/:id`. order: type: integer description: Ordering position within the post (0-indexed). altText: type: string nullable: true description: >- Per-post alt text override. Falls back to `MediaAsset.altText` when null. '400': description: Validation error content: application/json: schema: type: object properties: statusCode: type: integer example: 400 code: type: string example: VALIDATION_FAILED message: type: string requestId: type: string '401': description: Missing or invalid API key content: application/json: schema: type: object properties: statusCode: type: integer example: 401 message: type: string example: Unauthorized requestId: type: string components: securitySchemes: bearer: scheme: bearer bearerFormat: API key type: http description: Your Postbreeze API key ````