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`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/get) method on the [`spreadsheets`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets) resource to retrieve a spreadsheet, comment threads and anchors are omitted by default. To include comments in the response, set the [`commentsViewMode`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets#Spreadsheet.FIELDS.comments_view_mode) query parameter to [`COMMENTS_VIEW_MODE_INCLUDED`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets#commentsviewmode). 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`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets#Spreadsheet.FIELDS.comments) and [`sheets.commentAnchors`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/sheets#Sheet.FIELDS.comment_anchors) 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`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets#commentthread) objects. - The `sheets.commentAnchors` array containing [`CommentAnchor`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/sheets#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`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/get#body.QUERY_PARAMETERS.ranges) query parameter in the `spreadsheets.get` method) or sheets (using the [`dataFilters`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/getByDataFilter#body.request_body.FIELDS.data_filters) 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`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/batchUpdate) method on the [`spreadsheets`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets) resource. When performing batch updates involving comments, you should monitor for potential partial failures. For more information, see [Comment update status](https://developers.google.com/workspace/sheets/api/guides/comments#update-status). ### Insert a comment To insert a comment thread into a spreadsheet, use the [`InsertCommentRequest`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/request#insertcommentrequest) object. You must provide the comment text contents and the [`coordinate`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/request#InsertCommentRequest.FIELDS.coordinate) where the comment is anchored using a [`GridCoordinate`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/other#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`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/request#InsertCommentRequest.FIELDS.assignee_email_address) 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`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/request#addcommentreplyrequest) object. You must provide the `commentId` and the [`post`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/request#AddCommentReplyRequest.FIELDS.post) where the reply is represented by a [`Post`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets#post) object. The `Post` object contains the reply `content` and can optionally specify a [`commentAction`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets#Post.FIELDS.comment_action) (including the action to `RESOLVE` or `REOPEN` the comment thread). It's represented by a [`CommentActionType`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets#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`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/request#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`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets#commentthread), use the [`DeleteCommentRequest`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/request#deletecommentrequest) object. You can only delete a comment thread if you're the author of the thread's [`headPost`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets#CommentThread.FIELDS.head_post) in the `CommentThread` object. - **Delete a reply:** To delete a specific reply `Post` from a `CommentThread`, use the [`DeleteCommentReplyRequest`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/request#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`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/batchUpdate#body.BatchUpdateSpreadsheetResponse.FIELDS.comment_update_state) field in the response body of the `spreadsheets.batchUpdate` method. The field is represented by a [`CommentUpdateState`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/batchUpdate#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.