Query comments

Use the commentList query to read comments from any surface in Blue. There is one comment store across the product, so a single query serves all three targets: pass a category (DISCUSSION, STATUS_UPDATE, or TODO) plus the categoryId of the thing you’re reading. The result is a CommentList with the page of comments, pagination metadata, and a totalCount.

commentList is the canonical way to fetch comments. The older Chat.comments, StatusUpdate.comments, and Todo.comments fields are deprecated in favor of it — see Comments overview for the comment model and the category/categoryId targeting convention.

Request

Fetch the top-level comments on a record. category is TODO and categoryId is the record (Todo) ID.

query RecordComments {
  commentList(category: TODO, categoryId: "todo_123") {
    comments {
      id
      text
      createdAt
      user {
        id
        fullName
      }
    }
    totalCount
  }
}

The same query shape reads a chat (category: DISCUSSION, categoryId = the chat ID) or a status update (category: STATUS_UPDATE, categoryId = the status-update ID). Only category and categoryId change.

Parameters

Arguments

CommentCategory

ChatOrderByInput

orderBy takes a single ChatOrderByInput value (the type is shared with chatList). For comments the meaningful sorts are by timestamp:

Response

{
  "data": {
    "commentList": {
      "comments": [
        {
          "id": "clm4n8qwx000008l0g4oxdqn7",
          "text": "Kicking off the launch checklist — see the linked doc.",
          "createdAt": "2026-05-20T09:14:00.000Z",
          "user": {
            "id": "clm4n8qwx000108l0haz1f2pe",
            "fullName": "Ada Lovelace"
          }
        },
        {
          "id": "clm4n8qwx000208l0bk7c9xqz",
          "text": "Pricing copy is approved.",
          "createdAt": "2026-05-21T16:02:00.000Z",
          "user": {
            "id": "clm4n8qwx000308l0e1g5m4ab",
            "fullName": "Grace Hopper"
          }
        }
      ],
      "totalCount": 2
    }
  }
}

CommentList

PageInfo

Comment

The fields you’ll select most often. The Comment type exposes more — these are the common ones; the full set is documented in Comments overview.

Full example

Read the second page of a chat’s comments (10 per page, newest first), with reply counts and reactions.

query ChatComments {
  commentList(
    category: DISCUSSION
    categoryId: "chat_123"
    first: 10
    skip: 10
    orderBy: createdAt_DESC
  ) {
    comments {
      id
      uid
      html
      text
      createdAt
      updatedAt
      replyCount
      isRead
      user {
        id
        fullName
        email
      }
      reactions {
        emoji
        count
        reactedByMe
      }
    }
    pageInfo {
      totalItems
      totalPages
      page
      perPage
      hasNextPage
      hasPreviousPage
    }
    totalCount
  }
}

Errors

This query degrades gracefully: a categoryId that doesn’t exist (or points at a target you can’t see) yields an empty comments list and a totalCount of 0, rather than an error. Errors are reserved for authentication.

Permissions

Any authenticated caller can run commentList. Visibility is then scoped to the caller:

• A role configured with show-only-mentioned-comments sees a filtered subset — only comments the user authored or in which the user is mentioned. totalCount reflects that filtered set, not the thread’s full comment count.
• Comments on targets the caller can’t access return nothing rather than erroring.

Related

• Comments overview
• Create, edit & delete comments
• Reactions
• Query chats
• List records