> ## 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 comments > Returns comments from your inbox, newest first. This reads from Postbreeze's own cache — calling it doesn't hit the social platforms. To pull in new comments first, call `POST /comments/refresh`. By default you get comments from every workspace your API key can reach. Each row tells you which account it came from, so you can group or filter them in your code. Add `?workspaceId=…` to narrow the list to one workspace. The list is capped at 500 rows. The inbox supports Instagram, X, YouTube, Facebook Pages, and Threads. LinkedIn, TikTok, and Pinterest don't expose comments through their APIs, so they're not included. ## OpenAPI ````yaml /openapi.json get /comments 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: /comments: get: tags: - Comments summary: List comments description: >- Returns comments from your inbox, newest first. This reads from Postbreeze's own cache — calling it doesn't hit the social platforms. To pull in new comments first, call `POST /comments/refresh`. By default you get comments from every workspace your API key can reach. Each row tells you which account it came from, so you can group or filter them in your code. Add `?workspaceId=…` to narrow the list to one workspace. The list is capped at 500 rows. The inbox supports Instagram, X, YouTube, Facebook Pages, and Threads. LinkedIn, TikTok, and Pinterest don't expose comments through their APIs, so they're not included. operationId: CommentsV1Controller_list parameters: - name: workspaceId required: false in: query description: >- Optional. When set, returns comments in only this workspace. When omitted, returns comments across every workspace the API key can reach. schema: type: string - name: platform required: false in: query description: >- Optional. Filter to comments from a specific platform (e.g. `INSTAGRAM`, `YOUTUBE`). Platforms without inbox support are rejected with `400`. schema: enum: - INSTAGRAM - FACEBOOK_PAGE - X - LINKEDIN_PERSON - LINKEDIN_COMPANY - TIKTOK_BUSINESS - TIKTOK_PERSONAL - YOUTUBE - PINTEREST - THREADS - BLUESKY type: string - name: unread required: false in: query description: >- Optional. Pass `true` to return only unread comments (`readAt` is null). Any other value (or omitting the param) returns both read and unread rows. schema: type: boolean responses: '200': description: >- Inbox comments visible to the caller, newest-first by the platform's reported `createdAt`. content: application/json: schema: type: array items: type: object properties: id: type: string description: Prefixed cuid identifier of the comment row. platform: type: string enum: - INSTAGRAM - FACEBOOK_PAGE - X - LINKEDIN_PERSON - LINKEDIN_COMPANY - TIKTOK_BUSINESS - TIKTOK_PERSONAL - YOUTUBE - PINTEREST - THREADS - BLUESKY description: Which platform this comment was pulled from. socialAccountId: type: string description: >- Prefixed cuid of the connected channel that owns the post. Matches an `id` from `GET /social-accounts`, so consumers can group inbox rows by channel without a second call. externalCommentId: type: string description: >- Platform-side identifier of the comment itself. Unique per `(socialAccountId, externalCommentId)` — re-running refresh upserts in place rather than creating duplicates. externalParentId: type: string nullable: true description: >- Platform-side parent id when this comment is itself a reply nested inside a thread. Null for top-level comments on the post. externalPostId: type: string description: >- Platform-side identifier of the post the comment belongs to. Stored even for posts that weren't scheduled through Postbreeze, so the inbox can deep-link "View on platform". externalUrl: type: string nullable: true description: >- Server-built deep link to the comment in the platform's native UI. Null when the platform doesn't expose a stable per-comment URL (some Instagram comments fall in this bucket). author: description: >- Author snapshot captured at fetch time. Frozen — platform-side renames after fetch won't be reflected here. allOf: - type: object properties: handle: type: string nullable: true description: >- The author's user-facing handle on the platform (e.g. `@brand`). Null when the platform doesn't expose a handle for the responder. displayName: type: string nullable: true description: >- Human-readable display name. Null when unavailable. avatarUrl: type: string nullable: true description: >- Profile avatar URL when the platform provides one. body: type: string description: Plain-text body of the comment. createdAt: type: string format: date-time description: When the platform says the comment was posted. readAt: type: string format: date-time nullable: true description: >- When a user marked the comment read in the Postbreeze inbox. Null while the row is still unread. Filter on `unread=true` to see only rows where this is null. reply: nullable: true description: >- The reply Postbreeze posted on this comment, if any. Null when the comment hasn't been replied to through Postbreeze. Replies posted natively on the platform are not surfaced here. type: object allOf: - type: object properties: body: type: string description: Plain-text body of the reply that was sent. externalId: type: string description: >- Platform-side identifier of the reply Postbreeze posted. Useful for cross-referencing in the platform's native UI. createdAt: type: string format: date-time description: When Postbreeze posted the reply. '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 ````