Your Google Sheets script can now leave a comment on a cell instead of changing it

Can the Google Sheets API add comments to a cell now?

Google announced this on the Workspace Updates blog on 30 September 2026, together with the same kind of support for Docs and Slides. For Sheets, developers can now add, review and reply to comments on specific cells. The rollout started on 30 September for both Rapid Release and Scheduled Release domains and could take up to 15 days. It should be in place everywhere by now.

This is available to all Google Workspace customers and to personal Google accounts. There is no admin switch for it. An admin can still control which apps are allowed to reach Workspace data. That is the same control that already decides if a script or an outside tool can touch your sheets at all.

Before this update, the only official way to put a comment on a sheet from code was the Drive API, but it could not reliably pin a comment to one cell. People who tried it found their comment landed on the whole file instead. The new route is part of the Sheets API itself, so the comment is anchored to a real cell, just like a comment you add by hand.

Why should a script comment on a cell instead of fixing it?

Most data problems are not the script’s to fix. A negative amount might be a refund that was entered correctly, and a future date might be a pre-order. The script can see that something is unusual, but only the person who owns the data knows if it is wrong. If the script guesses, it destroys the one piece of evidence you needed, which is what the source actually sent.

I wrote about this same idea from the human side in how to check the numbers an AI put in your spreadsheet. The rule there is that you check a result against something you trust before you act on it. A comment is how a script follows that rule. It says what it found and why it thinks it is wrong, and then it waits for someone who knows the real answer.

Here is how the three options compare. A note is still useful for a fixed explanation that never needs an answer, like what a column means. But for a problem that someone has to act on, the comment is the only choice that can be assigned, answered and closed.

How do I add a comment to a cell with the Sheets API?

Comments go through spreadsheets.batchUpdate, the same call you already use to format cells or add sheets. Google’s guide Manage comments lists the requests. You send an insertComment request with the text in content and the cell in coordinate, which holds the sheet ID, the row index and the column index.

The one thing that trips people up is that the row and column numbers start at zero. Cell B2 is row index 1 and column index 1. Cell D7 is row index 6 and column index 3. To assign the comment to someone, you add assigneeEmailAddress with their email.

{
  "requests": [{
    "insertComment": {
      "content": "Amount is negative. Refund or typo? Please check the order.",
      "coordinate": { "sheetId": 0, "rowIndex": 6, "columnIndex": 3 },
      "assigneeEmailAddress": "orders@yourcompany.com"
    }
  }]
}

The other requests follow the same pattern. addCommentReply adds a reply to a thread. Its post can carry a commentAction of RESOLVE or REOPEN, so a script can close its own flag once the value is fixed. You use updateCommentPost to edit a post you wrote, deleteComment to remove a whole thread, and deleteCommentReply to remove one reply.

Can I add a cell comment from Apps Script?

Apps Script does not have a built-in method for this. SpreadsheetApp can write a note with setNote, but it has never had a method for comments. The way to do it today is to call the Sheets API endpoint directly with UrlFetchApp, using the script’s own sign-in token. If you have not used Apps Script before, my guide to automating Google Sheets with Apps Script covers the editor and triggers first.

This example checks column D of a tab called Orders. It comments on every amount that is not a number or is below zero, and it changes no values.

function flagSuspectAmounts() {
  const ss = SpreadsheetApp.getActive();
  const sheet = ss.getSheetByName('Orders');
  const values = sheet.getDataRange().getValues();
  const requests = [];

  values.forEach((row, i) => {
    if (i === 0) return;                 // skip the header row
    const amount = row[3];               // column D
    if (typeof amount !== 'number' || amount < 0) {
      requests.push({ insertComment: {
        content: '[check] Amount looks wrong: ' + amount,
        coordinate: { sheetId: sheet.getSheetId(), rowIndex: i, columnIndex: 3 }
      }});
    }
  });
  if (!requests.length) return;

  const url = 'https://sheets.googleapis.com/v4/spreadsheets/'
    + ss.getId() + ':batchUpdate';
  const res = UrlFetchApp.fetch(url, {
    method: 'post',
    contentType: 'application/json',
    headers: { Authorization: 'Bearer ' + ScriptApp.getOAuthToken() },
    payload: JSON.stringify({ requests: requests }),
    muteHttpExceptions: true
  });
  Logger.log(res.getResponseCode() + ' ' + res.getContentText());
}

The array index and the API index line up here, which is convenient. Row 0 of getValues() is the header and is also row index 0 in the API, so the i from the loop is the right row number, with nothing added or taken away.

There is one setup step that is easy to miss. If the script has the @OnlyCurrentDoc line at the top, it only gets permission for the current file, and the API call will then fail with a permission error. To be sure it works, open Project Settings, tick “Show appsscript.json”, and list the scopes yourself: https://www.googleapis.com/auth/spreadsheets and https://www.googleapis.com/auth/script.external_request. Run the function once by hand to approve them before you put it on a trigger.

Apps Script also has an advanced Sheets service that wraps the same API. I have not confirmed that it already accepts the new comment requests. So I use the direct call above, which talks to the API itself and does not depend on that wrapper being updated.

How do I stop a scheduled script from adding the same comment twice?

This is a problem you will hit on day two. The script above comments on every bad cell each time it runs. If you put it on an hourly trigger, a single bad amount collects 24 identical comments by tomorrow, and if you assign them, one person gets the same task 24 times.

The fix is to read the comments that are already there before you add new ones. Comments are left out of a normal spreadsheets.get response, so you ask for them with commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED. The response then has a comments list. In this list, each thread has an anchorId and a status such as OPEN, and each sheet has commentAnchors that map those anchor IDs to a cell range.

1. 01
   Tag your own comments

   Start every comment the script writes with a fixed tag such as [check]. That is how the script tells its own flags apart from comments people wrote by hand.
2. 02
   Read the open threads

   Call spreadsheets.get with the comments view mode included, keep the threads whose status is OPEN and whose first post starts with your tag, and turn their anchors into a list of cells.
3. 03
   Comment only on new problems

   When a row fails your check, skip it if its cell is already on that list. Everything else gets a new comment.
4. 04
   Close what got fixed

   If a flagged cell now passes the check, send addCommentReply with commentAction RESOLVE and a short reply such as "value now looks fine". The thread stays in the history, so nothing disappears.

Two limits from Google’s guide matter here. Only the author of a thread can delete it, and the author is whoever the script runs as. So a trigger set up by the sheet owner will show its comments under the owner’s name. And if someone deletes the row or cell a comment was on, that comment becomes unanchored. It still comes back when you read the whole spreadsheet, but not when you filter by a range, so read without a filter when you build the list of existing flags.

When should I use a comment, a note or a log tab?

I would not turn every check into a comment. A sheet covered in hundreds of comments is as useless as a log nobody reads. Comments work best for a small number of problems that one named person has to look at, and a summary works much better when the same issue repeats across many rows.

The third row is worth a second look. Some fixes really are safe, like trimming spaces or making a date format match, and I cover those in cleaning messy Excel data. Even then I keep the old value somewhere, because the day a rule turns out to be wrong you will want to know what it changed.

The comment route is for the step before that, when the script is not sure. It is also a good first version of any new check. You can run a new rule as comments for a couple of weeks and read what people reply. Only turn it into an automatic fix once the replies show the rule is always right.