---
title: "List comments across posts"
method: GET
path: "/api/comments"
tags: ["Comments"]
---

# List comments across posts

`GET /api/comments`

## Request

- Base URL: `https://api.postproxy.dev`
- URL: `https://api.postproxy.dev/api/comments`
- Auth: HTTP bearer

Retrieves comments spanning many posts and profiles in a single request. The response is flat: every comment, top-level or reply, is its own entry in data, linked to its parent by parent_external_id, ordered by created_at descending.

## Query parameters

- `profile_group_id` string
- `post_ids` string
- `profiles` string
- `from` string
- `to` string
- `page` integer
- `per_page` integer

## Response `200`

Flat, paginated list of comments across posts. Pagination counts every comment, not just top-level ones.

- CommentCrossPostListResponse: Flat, paginated list of comments across posts and profiles. Replies are not nested: every comment is its own entry, linked to its parent by parent_external_id.
  - `total` integer: Total number of matching comments, replies included
  - `page` integer: Current page number
  - `per_page` integer: Items per page
  - `data` object[]: Flat array of comment objects
    - `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.
      - `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.
    - `post_id` string: ID of the post the comment belongs to
    - `profile_id` string: ID of the profile the comment was left on
    - `platform` string: Network name, e.g. instagram

## Other responses

- `400`: Missing required parameters.
- `401`: Invalid, missing, or insufficient API key permissions.

---

[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)