---
title: "List comments on a post"
method: GET
path: "/api/posts/{post_id}/comments"
tags: ["Comments"]
---

# List comments on a post

`GET /api/posts/{post_id}/comments`

## Request

- Base URL: `https://api.postproxy.dev`
- URL: `https://api.postproxy.dev/api/posts/{post_id}/comments`
- Auth: HTTP bearer

Retrieves a paginated list of top-level comments for a published post on a specific profile. Each top-level comment includes a flat replies array containing all nested replies sorted by creation date.

## Query parameters

- `profile_group_id` string
- `profile_id` string, required
- `page` integer
- `per_page` integer
- `from` string
- `to` string

## Response `200`

Paginated list of top-level comments, each with a replies array. Pagination applies to top-level comments only.

- CommentListResponse: Paginated list of top-level comments for a post.
  - `total` integer: Total number of top-level comments
  - `page` integer: Current page number
  - `per_page` integer: Items per page
  - `data` Comment[]: Array of top-level comment objects, each with a replies array
    - `id` string: Unique comment identifier (ID)
    - `external_id` string, nullable: Platform's native comment ID (null for pending comments)
    - `body` string: Comment text content
    - `status` 'synced' | 'pending' | 'published' | 'failed' | 'failed_waiting_for_retry' | 'delivery_unconfirmed': Comment status. Only published and failed are terminal — treat every other value as still in progress.
    - `error` string, nullable: Error summary if the comment failed to publish (null otherwise)
    - `error_details` PlatformErrorDetails, nullable: Structured platform error (omitted when no platform error info is available).
      - `platform_error_code` string, nullable: Error code returned by the platform API
      - `platform_error_subcode` string, nullable: Error subcode returned by the platform API
      - `platform_error_message` string, nullable: Error message returned by the platform API
      - `postproxy_note` string, nullable: Additional context from Postproxy about the error
    - `author_username` string, nullable: Author's display name or username
    - `author_avatar_url` string, nullable: Stable Postproxy storage URL of the author's profile picture once mirrored; the platform URL until then
    - `author_external_id` string, nullable: Author's platform-specific ID
    - `metadata` CommentMetadata, nullable: Additional author signals fetched asynchronously from the platform after the comment is ingested. Null until the lookup completes; individual keys may be absent depending on platform support.
      - `author_fetched_at` string: ISO 8601 timestamp of the last author-info refresh
      - `is_verified_user` boolean: Author has a verified account (instagram)
      - `is_user_follow_business` boolean: Author follows the business profile (instagram)
      - `is_business_follow_user` boolean: The business profile follows the author (instagram)
      - `follower_count` integer: Author's follower count (instagram)
    - `parent_external_id` string, nullable: Parent comment's external ID (null for top-level comments)
    - `like_count` integer: Number of likes on the comment
    - `is_hidden` boolean: Whether the comment is hidden
    - `permalink` string, nullable: Direct URL to the comment on the platform (when available)
    - `platform_data` object, nullable: Platform-specific metadata
    - `attachments` CommentAttachment[]: Media attached to the comment. Empty array when there are none. Always empty on a freshly created (pending) comment.
      - `id` string: Attachment hashid
      - `type` 'image' | 'video' | 'audio' | 'gif' | 'external' | 'file'
      - `url` string, nullable: Stable storage URL to the asset. While status is pending, this temporarily falls back to the source URL on the platform until the file is mirrored to Postproxy storage.
      - `status` 'pending' | 'processed' | 'failed': pending (still being mirrored), processed (stored and ready), failed (could not be downloaded)
      - `external_id` string, nullable: Platform-side identifier for the attachment (e.g. Facebook attachment target ID). Omitted when the platform did not provide one.
    - `external_edited_at` string, nullable: ISO 8601 timestamp of the last edit made through Postproxy (null if never edited)
    - `posted_at` string, nullable: ISO 8601 timestamp when the comment was posted on the platform
    - `created_at` string: ISO 8601 timestamp of record creation
    - `replies` Comment[]: All replies (regardless of nesting depth) flattened under the root top-level comment, sorted by created_at ascending. Present on per-post list and get responses.

## Other responses

- `400`: Missing required parameters.
- `401`: Invalid, missing, or insufficient API key permissions.
- `404`: Resource does not exist or is not accessible.

---

[API](https://skmtc.dev/postproxy/apis/postproxy-social-media-api.md) - [All operations](https://skmtc.dev/postproxy/apis/postproxy-social-media-api/llms.txt) - [OpenAPI document](https://skmtc.dev/postproxy/apis/postproxy-social-media-api/revisions/d54482ac4ce7?raw)