Manage comments

Google Sheets lets users collaborate by adding comments on specific cells.

This document shows how you can use the Google Sheets API to programmatically read, create, reply to, update, or delete comments.

Read comments

When you use the get method on the spreadsheets resource to retrieve a spreadsheet, comment threads and anchors are omitted by default.

To include comments in the response, set the commentsViewMode query parameter to COMMENTS_VIEW_MODE_INCLUDED. Additionally, if the calling user has comments access on the file, then setting the query parameter to COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS also returns comments.

Both the comments and sheets.commentAnchors fields are returned in the response.

The following code sample shows how to use a get request that retrieves comment threads and their anchors (grid ranges) from a spreadsheet:

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED&fields=spreadsheetId,comments,sheets(properties(sheetId,title),commentAnchors)

In the response, comments are returned in two locations:

The global comments array containing the CommentThread objects.
The sheets.commentAnchors array containing CommentAnchor objects that map comment anchor IDs to cell locations (grid ranges).

Filter comments by range or sheet

When retrieving a spreadsheet, you can filter the returned data by specifying ranges (using the ranges query parameter in the spreadsheets.get method) or sheets (using the dataFilters field in the request body of the spreadsheets.getByDataFilter method).

If you filter by range or sheet: Only the comment threads anchored within the specified ranges or sheets are returned. Unanchored comments (such as comments whose original cell coordinate was deleted) aren't included.
If you don't filter by range or sheet: All comment threads, including unanchored comments, are returned.

Sample response

The following JSON sample response shows a comment thread anchored to cell A1 (row 0, column 0) on the sheet with an ID of 0:

{
  "spreadsheetId": "SPREADSHEET_ID",
  "sheets": [
    {
      "properties": {
        "sheetId": 0,
        "title": "Sheet1"
      },
      "commentAnchors": [
        {
          "anchorId": "ANCHOR_ID",
          "range": {
            "sheetId": 0,
            "startRowIndex": 0,
            "endRowIndex": 1,
            "startColumnIndex": 0,
            "endColumnIndex": 1
          }
        }
      ]
    }
  ],
  "comments": [
    {
      "commentId": "COMMENT_ID",
      "anchorId": "ANCHOR_ID",
      "headPost": {
        "postId": "POST_ID",
        "content": "This is a comment thread head post.",
        "contentHtml": "The content of the post as HTML.",
        "author": {
          "displayName": "DISPLAY_NAME",
          "me": true,
          "user": "users/USER"
        },
        "createTime": "2026-07-01T10:13:12Z",
        "updateTime": "2026-07-01T10:13:12Z"
      },
      "replies": [
        {
          "postId": "REPLY_POST_ID",
          "content": "This is a reply to the comment.",
          "author": {
            "displayName": "DISPLAY_NAME",
            "me": false
          },
          "createTime": "2026-07-01T10:15:00Z",
          "updateTime": "2026-07-01T10:15:00Z"
        }
      ],
      "status": "OPEN"
    }
  ],
  "commentsViewMode": "COMMENTS_VIEW_MODE_INCLUDED"
}

Create and manage comments

You can programmatically add, edit, and delete comments or replies using the batchUpdate method on the spreadsheets resource.

When performing batch updates involving comments, you should monitor for potential partial failures. For more information, see Comment update status.

Insert a comment

To insert a comment thread into a spreadsheet, use the InsertCommentRequest object. You must provide the comment text contents and the coordinate where the comment is anchored using a GridCoordinate object.

The following JSON sample shows how to add a non-assigned comment thread to cell B2 (row 1, column 1) on the sheet with an ID of 0:

{
  "requests": [
    {
      "insertComment": {
        "content": "This is a comment added using the API.",
        "coordinate": {
          "sheetId": 0,
          "rowIndex": 1,
          "columnIndex": 1
        }
      }
    }
  ]
}

You can assign a comment to a specific user by providing their email in the assigneeEmailAddress field:

{
  "requests": [
    {
      "insertComment": {
        "content": "Please review the data in this cell.",
        "assigneeEmailAddress": "ASSIGNEE_EMAIL_ADDRESS",
        "coordinate": {
          "sheetId": 0,
          "rowIndex": 1,
          "columnIndex": 1
        }
      }
    }
  ]
}

Add a reply or take action

To reply to a comment thread, resolve, or reopen a thread, use the AddCommentReplyRequest object.

You must provide the commentId and the post where the reply is represented by a Post object.

The Post object contains the reply content and can optionally specify a commentAction (including the action to RESOLVE or REOPEN the comment thread). It's represented by a CommentActionType object.

You can also re-assign a comment thread by specifying a new assigneeEmail in the Post object.

The following JSON sample shows how to reply to an existing comment thread:

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "COMMENT_ID",
        "post": {
          "content": "Replying to the comment thread."
        }
      }
    }
  ]
}

The following JSON sample shows how to resolve a comment thread (which doesn't require the content field):

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "COMMENT_ID",
        "post": {
          "commentAction": "RESOLVE"
        }
      }
    }
  ]
}

The following JSON sample shows how to re-assign a comment thread:

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "COMMENT_ID",
        "post": {
          "content": "Replying to the comment thread.",
          "assigneeEmail": "ASSIGNEE_EMAIL"
        }
      }
    }
  ]
}

Edit a post

To edit the text content of a post you authored, use the UpdateCommentPostRequest object. You must specify the commentId of the thread, the postId of the post you want to edit, and the new plain text content.

The following JSON sample shows how to edit a post:

{
  "requests": [
    {
      "updateCommentPost": {
        "commentId": "COMMENT_ID",
        "postId": "POST_ID",
        "content": "This is the updated comment text."
      }
    }
  ]
}

Delete comments and replies

To delete comments and replies, you have two options:

Delete a comment thread: To remove an entire CommentThread, use the DeleteCommentRequest object. You can only delete a comment thread if you're the author of the thread's headPost in the CommentThread object.
Delete a reply: To delete a specific reply Post from a CommentThread, use the DeleteCommentReplyRequest object. You can only delete replies you authored. You cannot delete reply posts that contain a commentAction or an assigneeEmail.

The following JSON sample shows how to delete a comment thread:

{
  "requests": [
    {
      "deleteComment": {
        "commentId": "COMMENT_ID"
      }
    }
  ]
}

Comment update status

Requests that require saving comment threads (such as inserting comments or adding replies) might experience partial failures. In these cases, the spreadsheet model changes (such as updating cell values or adding sheets) might be successfully committed, but the associated comments might fail to save.

You can verify whether comment updates were successfully applied by checking the commentUpdateState field in the response body of the spreadsheets.batchUpdate method. The field is represented by a CommentUpdateState object.

The following states are returned in CommentUpdateState:

NO_UPDATES_REQUESTED: No comment updates were requested in the batch operation.
ALL_SAVED: All requested comment updates were successfully applied.
ALL_FAILED_UNKNOWN_REASON: All requested comment updates failed to save, even though other spreadsheet changes might have been committed.