# List comments

Returns comments for your organization.

Comments are threaded discussions. Each comment can have:
- Author information
- Voting (upvotes/downvotes)
- Privacy settings (public/private)
- Moderation status
- Parent comment reference for threading

### Filtering

Optionally filter by:
- postId - Get comments for a specific post
- changelogId - Get comments for a specific changelog

If no filter is provided, returns all comments across the organization.

### Pagination

This endpoint uses cursor-based pagination:

- limit - Number of comments to return (1-100, default 10)
- cursor - Opaque cursor from a previous response's nextCursor field

Example: To paginate through results:
1. First request: GET /v2/comments?postId={id}&limit=10
2. If nextCursor is not null, use it for the next page
3. Next request: GET /v2/comments?postId={id}&limit=10&cursor={nextCursor}

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of comment objects (flat structure with parentCommentId for threading)
- nextCursor - Cursor for the next page (null if no more results)

### Comment Structure

Each comment includes:
- id - Unique comment identifier
- postId / changelogId - Reference to the parent content
- parentCommentId - Reference to parent comment (null for root comments)
- content - Comment content in HTML format
- author - Author information (id, name, profilePicture, type)
- upvotes / downvotes / score - Voting metrics
- isPrivate - Whether comment is only visible to admins
- inReview - Whether comment is pending moderation
- created / updated - Unix timestamps

### Additional Filters

- privacy - Filter by privacy: "public", "private", or "all"
- inReview - Filter by moderation status (true/false)

### Sorting

Use sortBy to sort results:
- best - Sort by confidence score (default, like Reddit)
- top - Sort by net score (upvotes - downvotes)
- new - Sort by creation date, newest first
- old - Sort by creation date, oldest first

Endpoint: GET /v2/comments
Version: 2026-01-01.nova
Security: bearerAuth

## Header parameters:

  - `Featurebase-Version` (string)
    API version for this request. Defaults to your organization's configured API version if not specified.
    Example: "2026-01-01.nova"

## Query parameters:

  - `postId` (string)
    Filter comments by post ID
    Example: "507f1f77bcf86cd799439011"

  - `changelogId` (string)
    Filter comments by changelog ID
    Example: "507f1f77bcf86cd799439012"

  - `privacy` (string)
    Filter comments by privacy
    Enum: "public", "private", "all"

  - `inReview` (boolean,null)
    Filter by review status

  - `limit` (integer)
    Maximum number of comments to return
    Example: 10

  - `cursor` (string)
    Cursor for pagination. Use nextCursor from previous response.
    Example: "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"

  - `sortBy` (string)
    Sort order for comments
    Enum: "best", "top", "new", "old"

## Response 200 fields (application/json):

  - `object` (string, required)
    Object type identifier
    Enum: "list"

  - `data` (array, required)
    Array of comments
    Example: []

  - `data.id` (string, required)
    Unique identifier
    Example: "507f1f77bcf86cd799439011"

  - `data.postId` (string,null, required)
    Post ID this comment belongs to
    Example: "507f1f77bcf86cd799439012"

  - `data.changelogId` (string,null, required)
    Changelog ID this comment belongs to
    Example: "507f1f77bcf86cd799439013"

  - `data.parentCommentId` (string,null, required)
    Parent comment ID for replies, null for root comments
    Example: "507f1f77bcf86cd799439014"

  - `data.content` (string, required)
    Comment content in HTML format
    Example: "<p>This is a great idea!</p>"

  - `data.author` (object,null, required)

  - `data.author.id` (string,null, required)
    Author unique identifier
    Example: "507f1f77bcf86cd799439011"

  - `data.author.name` (string, required)
    Author display name
    Example: "John Doe"

  - `data.author.profilePicture` (string,null, required)
    Author profile picture URL
    Example: "https://cdn.example.com/avatars/john.png"

  - `data.author.type` (string, required)
    Type of user who authored the comment
    Enum: "admin", "customer", "guest", "integration", "bot", "lead"

  - `data.upvotes` (number, required)
    Number of upvotes
    Example: 5

  - `data.downvotes` (number, required)
    Number of downvotes

  - `data.score` (number, required)
    Net score (upvotes - downvotes)
    Example: 5

  - `data.isPrivate` (boolean, required)
    Whether the comment is private

  - `data.isDeleted` (boolean, required)
    Whether the comment is deleted

  - `data.isPinned` (boolean, required)
    Whether the comment is pinned

  - `data.inReview` (boolean, required)
    Whether the comment is in review

  - `data.isSpam` (boolean, required)
    Whether the comment is spam

  - `data.createdAt` (string, required)
    ISO 8601 timestamp when created
    Example: "2023-12-12T00:00:00.000Z"

  - `data.updatedAt` (string, required)
    ISO 8601 timestamp when updated
    Example: "2023-12-13T00:00:00.000Z"

  - `nextCursor` (string,null, required)
    Cursor for fetching the next page (cursor-based pagination)
    Example: "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"

  - `pagination` (object)
    Pagination metadata for page-based requests

  - `pagination.page` (number, required)
    Current page number
    Example: 1

  - `pagination.limit` (number, required)
    Items per page
    Example: 10

  - `pagination.total` (number, required)
    Total number of items
    Example: 42

  - `pagination.totalPages` (number, required)
    Total number of pages
    Example: 5

## Response 400 fields (application/json):

  - `error` (object, required)

  - `error.type` (string, required)
    The type of error returned
    Enum: "invalid_request_error"

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "invalid_cursor"

  - `error.message` (string, required)
    Human-readable error message
    Example: "An error occurred"

  - `error.param` (string)
    The parameter that caused the error (if applicable)
    Example: "id"

  - `error.status` (number, required)
    HTTP status code
    Enum: 400

## Response 404 fields (application/json):

  - `error` (object, required)

  - `error.type` (string, required)
    The type of error returned
    Enum: "invalid_request_error"

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "post_not_found"

  - `error.message` (string, required)
    Human-readable error message
    Example: "An error occurred"

  - `error.param` (string)
    The parameter that caused the error (if applicable)
    Example: "id"

  - `error.status` (number, required)
    HTTP status code
    Enum: 404